GLS Specification

From Geospike DocWiki

GLS, or "GPS Log Service" descriptor files tell GPS Log about your custom Share Service. The options are detailed here.

Contents 1 The Spec 1.1 <Header> 1.2 <Settings> 1.2.1 Username and Password 1.2.2 User Key 1.2.3 Phone Number (for SMS) 1.2.4 Management Web Page Link 1.3 <SharedExportOptions> 1.3.1 Generic 1.3.2 Short Message Mode 1.3.3 Photo Configuration 1.3.3.1 Fine-grained customisation of photos can be exported 1.3.3.2 Size, Quality control 1.4 <SingleExportOptions> 1.4.1 Include Options 1.5 <ListExportOptions> 1.6 <CustomData> 2 Examples

The Spec

<Header>

The header contains various information to describe your service, and paths like that of the export script.

Name (String) – Name of the service

Source (String) - Domain name of the service. Must match the URL. E.g. 'gpslog.cc' is valid for services downloaded from http://gpslog.cc/*

Description (String) - Text that appears on the share screen. Keep this short.

Description Long (String) – Test that appears in the settings page (can be as long as you like)

WebsiteURL (URL) – URL to your website. Can be anything, recommended that it contains information about the share service

ExportURL (URL) – The script that GPS Log exports to (most important part of the GLS).

IconURL (URL) – Path to a 114x114 PNG file that will be displayed as your service icon (displayed at 57x57)

SingleExport (BOOL) – if 'true', then your service is designed to work with sharing Single entries.

ListExport (BOOL) – if 'true', then your service is designed to work with multiple entries (from the list screen). You are welcome to support both ListExport and SingleExport (but note that different information is passed by GPS Log.

ServiceVersion (float) – Any value you like, should indicate your service version. Will be passed to your script. Use this to identify which version of the GLS file people are using. If it's too old, you can prompt them to refresh (currently a manual action).

MinSupportedAppVersion (float) – Minimum version of GPS Log the user must be running to use your service.

<Settings>

This configures the "Settings" page of your service (accessed via GPS Log -> Settings -> Sharing Settings).

IncludesUDID (BOOL) {false} – if true, the user's UDID is sent (useful way to identify devices)

Username and Password

RequiresUsernameAndPassword (BOOL) {false} – if true, then the user is forced to enter a username and password

UsernamePlaceholderText (String) {"username"} - Placeholder text for the username input widget

PasswordPlaceholderText (String) {"password"} - Placeholder text for the password input widget

User Key

RequiresUserKey (BOOL) {false} – if true, then the user is forced to enter a "user key" (like a unique id – can be anything you like)

UserKeyLabel (String) {nil} – Text of the label for the User Key. Set this to whatever you like.

UserKeyPlaceholderText (String) {"user key"} - Placeholder text for the user-key input widget

Phone Number (for SMS)

IncludesPhoneNumber (BOOL) {false} - if true, the service has a phone number (for SMS)

PhoneNumberEditable (BOOL) {false} - if true, the phone number is editable (depends: IncludesPhoneNumber)

PhoneNumberDefault (String) {nil} - the default phone number

PhoneNumberPlaceholderText (String) {"phone number"} - Placeholder text for the phone number input widget

Management Web Page Link

MgmtLinkNoDetails (URL) {nil} - URL to a web site where the user can sign up to your service (or other actions). Only shown when the user key, username and password are nil

MgmtLinkNoDetailsText {"User Management"} - The text displayed on the button for MgmtLinkNoDetails

MgmtLinkDetails (URL) {nil} - Same as MgmtLinkNoDetails, but shown when the user has entered details like the user-key or username. The user key is passed as a GET parameter of this link, if MgmtLinkAddUserArgs is true.

MgmtLinkDetailsText (String) {"User Management"} - Same as MgmtLinkNoDetailsText, but used for MgmtLinkDetails

MgmtLinkAddUserArgs (BOOL) {false} - if true, the user args will be passed as the GET paramters if the user presses the management link defined in MgmtLinkDetails. GET params are: 'UserKey', 'UDID' and 'Username' (only those values set to be requested are passed)

<SharedExportOptions>

Generic

ActionIconURL (URL) {default export link} – Path to a 48x40 PNG file that will be displayed on the "action" (share) button (displayed at 24x20).

ExportActionTitle (String) - sets the text of the export button

SuccessMessage (String) - the message to be shown to the user on success (you can also set this in the reply)

ShowEmailRecipient (BOOL) {false} - if true, user is prompted to pick address(es) to export to

ShowSubject (BOOL) {false} - if true, user is prompted to set a subject

SubjectTitle (String) {"Subject"} - changes the label of the subject field

ShowMessage (BOOL) {false} - if true, user can write a message

MessageTitle (String) {"Message"} - changes the label of the message field

ShowServiceConfig (BOOL) {true} - allows the user to edit the configuration details of the Service. If false, the user can only do this via GPS Log -> Settings -> Sharing Settings -> your service.

SupportsTransactions (BOOL) {false} - set to true if your service supports Service Transactions (that is, where the export can be split over multiple HTTP requests, suitable for uploading large files. A simple PHP sample implementation can be provided on request.

TransactionsVersion (Float) {1.0} - Set this value to match the version of the transaction code you support. [added in GPS Log 3.0]

IncludeGeospikeStory (BOOL) {false} – if true, sync's the records to Geospike.com and provides a public link. [added in GPS Log 3.0]

ExportImmediately (BOOL) {false} - if true, export starts immediately and the export options are not shown. [added in GPS Log 3.0]

Short Message Mode

These settings totally change the share export to a "short message" style, suitable for Twitter, SMS, etc. Most other options are disabled (like photos).

ShowShortMessageField (BOOL) {false} - Enables short message mode

ShowShortMessageActionTitle (String) - Sets the action button text

ShortMessageURLCoordDelim (char) {,} – The character used to delimit the coordinates in the URL. By default, a comma is used, but some twitter clients do not handle this very well, so you can change to something more appropriate like '_'

ShortMessageCharLimit (int) {140} - The character limit that is used ShortMessageCharLimitIsStrict (BOOL) {true} - if true, user cannot perform the action if the characters exceed the limit

ShortMessageCopyToClipboardAndSMS (BOOL) {false} - if true, user is prompted to SMS the info

ShortMessagePostAsFacebookStatus (BOOL) {false} - if true, user is prompted to set as facebook status

Photo Configuration

ShowPhotoOptions (BOOL) {true} - enables photo sharing. If false, photos will never be exported, and the options will not be shown. (nb. the default setting changed in 2.5.3 from false, to true).

Fine-grained customisation of photos can be exported

Generally this section can be left blank. But you can use it to specify what users can do. For example, you can force the export of photos by setting ShowPhotoOptionChoiceNone to false.

ShowPhotoOptionChoiceNone (BOOL) {true} - shows the 'None' photo export option in the segmented control. ShowPhotoOptionChoiceMainOnly (BOOL) {true} - shows the 'Main' photo export option in the segmented control. ShowPhotoOptionChoiceAll (BOOL) {true} - shows the 'All' photo export option in the segmented control. ShowPhotoOptionChoiceDefault (int) {1} - sets the default choice (index, starting at 0. i.e. 1 would set the main photo to be the default, if all options are true. If ChoiceNone is set to false, and the rest true, then 1 would set the 'All' choice as default).

Size, Quality control

ShowPhotoOptionSize (BOOL) {true} - shows the list of sizes for export. Use PhotoMaximumDimensions to set the maximum. If this value is set to false, then the photos are exported at maximum size (unless PhotoMaximumDimensions is set, in which case they are constrained to that size). So if you want all your photos at 300x300, set this to false, and PhotoMaximumDimensions to 300.

PhotoMaximumDimensions (int) {nil} – if set, this constrains the height and width of the images uploaded to the size specified. Images are resized if needed, preserving aspect ratio.

ShowPhotoOptionQuality (BOOL) {false} - shows a slider allowing the user to manually set the JPEG quality (use PhotoMaximumJPEGQuality to specify the maximum quality they can choose).

PhotoMaximumJPEGQuality (float) {0.8} - value between 0 and 1.0 where 1.0 is the highest quality. Sets the JPEG quality that you want to export.

<SingleExportOptions>

Options only relevant for the single export

SingleExportHint (String) {nil} - a hint that is shown on the export screen

Include Options

Include options allow users to fine-tune what is exported. E.g. the Flikr share service uses this to allow users to not share tags, for example.

ShowIncludeOptions (BOOL) {false} - if set, allows users to fine-tune these options. Otherwise, all info is exported.

ShowIncludeOptionNote (BOOL) {true} - allows the user to decide if the Note should be exported (depends on ShowIncludeOptions) ShowIncludeOptionTags (BOOL) {true} - allows the user to decide if the Tags should be exported (depends on ShowIncludeOptions) ShowIncludeOptionVisits (BOOL) {true} - allows the user to decide if the Visits should be exported (depends on ShowIncludeOptions)

<ListExportOptions>

IncludePhotosForUnexportedAndChangedOnly (BOOL) {false} - if true, GPS Log remembers which images have been exported to this service (stored on SUCCESS, so duplicate uploads are possible), and doesn't resend them. User can reset this list if they need to in the share service settings.

ListExportHint (String) {nil} - a hint that is shown on the export screen

ShowGeneralSettings (BOOL) {true} - if true, allows user to change what data is exported

DataFormat (enum=GPX,KML,POSTArgs,JSON,None) - specifies the data format. The GPX and KML formats are standards, POSTArgs sets all the values in a big array of HTTP post arguments. DataFormat2 (enum=GPX,KML,POSTArgs) {nil} - specifies the second data format. This allows you to get the data in say both KML and POSTArgs. NB. if the format you are exporting contains pictures (e.g. KML), then that format must be the one set in DataFormat. DataFormat2 will not get pictures.

<CustomData>

You can use this section to put any information you like. All information is passed back to your service. This is useful for example if the GLS file is dynamically generated. The Twitter OAuth service uses this to store the user's OAuth token, rather than as a UserKey which the user must enter. When combined with the GPS Log Custom URL Scheme this can be particularly powerful.

PHP Example:

 
	<CustomData>
		<oauth_token><?php echo $_GET['oauth_token']; ?></oauth_token>
		<oauth_token_secret><?php echo $_GET['oauth_token_secret']; ?></oauth_token_secret>
	</CustomData>
 

This sets the token & secret in the GLS file to be that which was passed via GET.

Then in the service itself, we can access these variables like so:

 
	echo $_POST['CustomData']['oauth_token'];
	echo $_POST['CustomData']['oauth_token_secret'];
 

Examples

• Example of Basic-Auth twitter client
• Example Short Message with default Phone Number

The list of services which GPS Log accesses is stored at this URL (view the xml source). You can view the source of any GLS file that is listed there.