Glympse

glympse

Overview

The Glympse application for Android and iPhone register the “glympse:” protocol handler.  The protocol handler allows Glympse to be launched (or brought to the foreground if already running) by simply invoking a URL.  The query-string parameters passed to the Glympse URL allow the caller to automate certain functions of Glympse, including viewing a Glympse and sending a Glympse.

 

The Glympse URL can be invoked by the user or by other applications.  For example, the URL could be a user-clickable hyperlink on an external or local web page, in an SMS text, in an email, etc.  The URL can also be invoked from code by other applications on the device.

 

Some examples of how the Glympse protocol handler could get used.

 

Application homepage: http://glympse.com
iTunes link: https://itunes.apple.com/us/app/glympse-share-location-friends/id330316698
HTML Link example: glympse:?src=sample&rec_type=email&rec_addr=sylvia@glympse.com&dur_min=30 &dest_ll=33.812099,-117.918972&dest_name=Disneyland&msg_text=Meet+here!
Native application URL string example:
Extended example: https://developer.glympse.com/content/client/schema/guides/glympse_uri_schema.html
Tags: temporary location sharing

URL format

The most basic Glympse URL is one that will simply launch the Glympse client (or bring it to the foreground if it is already running):

 

 

glympse:

URL

 

 

 

Now, let’s take a look at how we can add some parameters to the URL.  Parameters are passed using standard URL encoded query-string formatting.  Most Glympse parameters are passed as name/value pairs in the form of name=value.  However, there is one case that allows just a nameless value.  This condensed format is used when you want to specify a Glympse code to watch.  In this one case, the parameter value is just the Glympse code.  For example, to start the Glympse client and tell it to watch the user that sent the Glympse code of ABC-123, the URL would look like this:

 

 

 

glympse:?ABC-123

URL

 

 

 

Glympse supports multiple parameters.  Here is an example of how to start Glympse and watch three different Glympse codes:

 

 

 

glympse:?ABC-123&DEF-456&GHI-789

URL

 

 

Just about every feature of Glympse can be automated via a parameter in the URL.  Here is an example of how to start Glympse and pre-populate the “Send a Glympse” page with an email recipient:

 

glympse:?src=sample&rec_type=email&rec_addr=sylvia@glympse.com

URL

 

Here is that same URL, but we are setting the duration and adding a message and a destination:

 

glympse:?src=sample&rec_type=email&rec_addr=sylvia@glympse.com&dur_min=30

    &dest_ll=33.812099,-117.918972&dest_name=Disneyland&msg_text=Meet+here!

URL

 

Here are some rules about how URLs are processed by Glympse.

  1. Question marks is required after colon, if any arguments are passed. Slashes are not allowed.

 

glympse:?ABC-123

URL

 

  1. Multiple parameters are separated by ampersands (&)

 

glympse:?src=sample&rec_type=sms&rec_addr=4255551212

URL

 

  1. The value portion of each name/value pair should be URL encoded to escape any special characters.  For example, ampersands (&) should be encoded as %26, question marks (?) should be encoded as %3F, equals (=) should be encoded as %3D, spaces should be encoded as %20 or plus (+), etc.

 

glympse:?src=sample&msg_text=Meet+here+for+drinks%3F

URL

Parameters

The following table lists the parameters currently supported by the Glympse URL protocol handler.  Unless noted otherwise, all parameters work on iPhone and Android.

 

Parameter

Description

None

Any value on the query-string that has no name is treated as a Glympse code to view.  For example, the URL “glympse:?ABC-123” has a nameless value of “ABC-123”.  This value is assumed to be a Glympse code, and the Glympse application will attempt to view the Glympse with this code.

src

This is a required value that specifies an application key for the caller.  If you intend to use the Glympse protocol handler, please contact partners@glympse.com for an application key.  For testing, you can use the Glympse protocol handler without a key.  However, before releasing an application that uses the Glympse protocol handler, you will need to obtain a registered application key to prevent your application from getting blocked from calling the Glympse protocol handler.

rec_addr[#]

Recipient address.  This can be a phone number or an email address.  This value is ignored if the recipient type (rec_type) is Twitter or Facebook.

 

The [#] part of the name is an optional index value if more than one recipient is being specified. See the Sending to multiple recipients section below for more information.

rec_type[#]

Type of recipient.  This value is required if sending to Twitter or Facebook and recommended if sending to a phone number or email address.  If this value is not specified, then Glympse will examine the text in rec_addr to determine if the recipient is a phone number or an email address.

 

email

Recipient is an email address.

sms

Recipient is a mobile phone number.  Glympse will attempt to use the user’s local phone number and operating system to send the invite if possible.  If Glympse detects the device is not capable of sending SMS (like an iPod, iPad, or Android tablet), then the invite will be sent via the Glympse server’s SMS system.

group

Recipient is a Glympse group. The rec_addr for this rec_type must include a ‘!’ as the first character.

clipboard

The Glympse URL is copied to the clipboard.

twitter

Post to Twitter.  This assumes the user has Twitter setup locally.

facebook

Post to Facebook.  This assumes the user has Facebook setup locally.

 

The [#] part of the name is an optional index value if more than one recipient is being specified. See the Sending to multiple recipients section below for more information.

rec_name[#]

Friendly display name of the recipient specified in rec_addr.  This value is ignored if the recipient is Twitter or Facebook, and optional if the recipient is a phone number or email address.  If this value is specified, then it will be shown along with the raw value set in rec_addr.  The value is intended to provide a friendly context for the recipient.  Make sure this value is URL encoded.

 

The [#] part of the name is an optional index value if more than one recipient is being specified.  See the Sending to multiple recipients section below for more information

dur_secs

When sending a Glympse, this specifies the total duration in seconds.  This value is optional and defaults to the user preferred duration if not specified.  dur_secsdur_mins, and dur_hrs are mutually exclusive.  You should only specify one of them.

dur_mins

When sending a Glympse, this specifies the total duration in minutes. This value is optional and defaults to the user preferred duration if not specified.  dur_secs,dur_mins, and dur_hrs are mutually exclusive.  You should only specify one of them.

dur_hrs

When sending a Glympse, this specifies the total duration in hours.  This value is optional and defaults to the user preferred duration if not specified.  dur_secs,dur_mins, and dur_hrs are mutually exclusive.  You should only specify one of them.

dest_addr

Destination.  Currently, the only supported format is: latitude,longitude

dest_name

Friendly display name of destination.  Optional, but highly recommended ifdest_addr is specified.  If no name is provided, a name will be automatically generated using the latitude and longitude.  Make sure this value is URL encoded.

msg_text

Text to use for the message of the Glympse.  Make sure this value is URL encoded.

screen

This optional value can be used to set the initial screen when Glympse is started (or when brought to the foreground if already running).  This value is ignored if the query-string parameters also contain any parameters for sending a Glympse (like recipient, duration, destination, or message parameters) since those parameters infer that Glympse should start on the “Send a Glympse” screen.  Possible values for this parameter are…

 

send

Start Glympse on the “Send a Glympse” screen.  This value is assumed if any parameters for sending a Glympse (like recipient, duration, destination, or message parameters) are also specified on the query-string.

history

Start Glympse on the “History” screen.  This can be useful if other applications want to have a “View your Glympse history” action.

favorites

Start Glympse on the “Favorites” screen.  This can be useful if other applications want to have a “Send a favorite Glympse” action.

map (iPhone only)

Start Glympse on the “Map” screen.

settings (iPhone only)

Start Glympse on the “Settings” screen.

language (iPhone only)

Start Glympse on the Language select Settings screen.

about

Start Glympse on the “About” screen.

intro (iPhone only)

Start Glympse and start the first time user experience, “Introduction” screen.

 

ret_url

[iOS only] This optional value specifies a URL to navigate to after a Glympse has successfully been sent.  This parameter is intended to be used with other parameters for sending a Glympse (like recipient, duration, destination, or message parameters).  A common use for this parameter is when the calling application would like control returned to it after a Glympse has been sent.  The URL specified can have any schema, so it is possible to take the user to a web site via an http URL, another application using a custom schema, or can even be used to call another glympse URL for nested Glympse actions.  Make sure this value is URL encoded.

ret_cancel_url

[iOS only] This optional value specifies a URL to navigate to after the user cancels a “Send a Glympse” operation.  This parameter is intended to be used with other parameters for sending a Glympse (like recipient, duration, destination, or message parameters).  The parameter is similar to ret_url, except that this URL is invoked when the user chooses not to send the Glympse that the caller passes in on the query-string.  Make sure this value is URL encoded.

Sending to multiple recipients

There are three parameters related to specifying a recipient: rec_addr, rec_type, and rec_name.  To enable sending to multiple recipients, these three parameters support an optional index number.  Here is an example of sending to two recipients…

glympse:?src=sample&rec_type1=email&rec_addr1=sylvia@glympse.net&rec_name1=Silvia

    &rec_type2=sms&rec_addr2=425-555-1212&rec_name2=Nicole

URL

 

If no index value is specified, then a value of 1 is assumed.  The order of the parameters don’t matter (you could specify rec_addr2 before rec_addr1 if you wanted).  The index numbers do not need to be consecutive (you could specify rec_addr1 and rec_addr3 without a rec_addr2).  Once all the parameters have been processed by Glympse, the recipients will be sorted by index value and added to the recipient list UI in this order.