Layar Developer Documentation

◀ Back to layar.com

actions

Please NOTE that this documentation describes the getPOIs API v7.1. Developers must use this specification to create new Vision layers. The API v7.1 is backward compatible with previous versions of the Layar Reality Browser (v3.0 and higher on Android and iPhone).

JSON Response - actions

For Geo layers, the actions object can be used on both layer level (root) and POI level (hotspots) in the JSON response. For Vision layers, actions can only be defined on the POI level.

  actions.uri actions.label actions.contentType actions.method actions.params actions.activityType actions.showActivity actions.activityMessage actions.closeBiw actions.autoTriggerRange actions.autoTrigger actions.autoTriggerOnly

uri string The URL to send the request to.
Introduced API: v2.1; modified in later API versions.
Mandatory/Optional: mandatory
Path: root.actions or hotspots.actions
Detailed Description: The possible URIs are "tel:", "sms:","data:text/" "mailto:", "http://", "https://", "layar://" , "layarshare://" and custom app schemes.
Regarding custom app schemes, on Android, we firstly detect whether the user has the corresponding app installed, if not, the action will not be shown. On iPhone, the action will be shown all the time. If the corresponding app is not installed, nothing will happen when clicking on the action. Therefore, it is not recommended to implement actions linking to custom app schemes if you are not sure that target user groups have already installed the app. Note that "rtsp://" is NOT supported.
The following HTTP headers will always be sent:
- Cookie (if a cookie has been set for the domain)
- User-Agent: The Layar app User-Agent is sent if the request is from within the AR view (text/plain, audio/mpeg, audio/mp4, video/3gpp, video/mp4, application/vnd.layar.async). The web browser's User-Agent is sent if the request is from within a web view (text/html or application/vnd.layar.internal in combination with http:// or https:// protocols).
Example: 
"uri" : "http://mylayer.com/anwers/?chosen=3&"
label string The text displayed in the action button
Introduced API: v2.1; modified in API v6.2.
Mandatory/Optional: mandatory for Geo layers/ deprecated for Vision layers except for the showDialog object in Vision layer.
Path: root.actions or hotspots.actions
Detailed Description: The text will be displayed in the button corresponding to the action.
Example: 
"label" : "More info"
contentType string The type of document that is being fetched.
Introduced API: v4.0; modified in later API versions.
Mandatory/Optional: mandatory
Default value: application/vnd.layar.internal
Path: root.actions or hotspots.actions
Detailed Description: The possible content types are:
- "application/vnd.layar.internal": Use it for "tel:", "mailto:", "sms:", "layar://", "layarshare://" and other custom URL schemes.
- "text/plain": This tells the Layar client to fetch a plain text document that will be shown as a pop-up to the user as a result of activating the action. This is the same pop-up as the one used for the "showMessage" param in the getPOIs response.
- "application/vnd.layar.async": This tells the client that the action is a REST call to the content provider. Only http:// is supported. The response should be a HTTP 302 redirect to a layar:// intent. The layar:// intent tells the client to perform a new getPOI request. The body of the HTTP 302 response (plain text) will be displayed as a pop-up to the user before performing the new getPOI request.
Example: 
"contentType" : "text/html"
"contentType" : "audio/mpeg"
"contentType" : "audio/mp3"
"contentType" : "video/mp4"
"contentType" : "video/3gpp"
"contentType" : "text/vcard"
method string (enum) The request type, GET or POST
Introduced API: v4.0.
Mandatory/Optional: optional
Default value: GET
Path: root.actions or hotspots.actions
Example: 
"method" : "POST"
params array of strings A list parameters can be added to the request.
Introduced API: v4.0
Mandatory/Optional: optional
Default value: empty array
Path: root.actions or hotspots.actions
Detailed Description: Comma-separated list of parameters to be added to the request:
- For a GET request, the params will be added in the URL E.g. "lat=45.462&lon=2.42346&alt=560"
- For a POST request, the params will be passed as URL-encoded parameters in the body of the response.
Possible values: lat, lon, alt, lang, countryCode, localCountryCode, version.
NOTE: countryCode is the home country of the user while localCountryCode is the country where the user is located at the moment.
Example: 
"params" :  ["lat", "lon", "alt", "lang", "countrycode", "localCountryCode", "version"]
activityType integer The icon shown on the action button.
Introduced API: v4.0
Mandatory/Optional: optional
Default value: false
Path: root.actions or hotspots.actions
Detailed Description: This determines which icon should be used if the action is displayed in a button. Layar provides a predefined set of icons that content authors can use. The icon will give the user good hint on the meaning of an action. Please view the attached list of icons at the bottom of the page.
Example: 
"activityType" :  3
showActivity boolean Indicates whether to show the background activity.
Introduced API: v4.0
Mandatory/Optional: optional
Default value: true
Path: root.actions or hotspots.actions
Detailed Description: This tells the layar client whether or not to show the user that there is background activity to fetch the action result. This is useful mostly for autoTriggered actions where it may not always be good user experience to show something suddenly.
Example: 
"showActivity" : false
activityMessage string The message shown while waiting for the activity response.
Introduced API: v4.0
Mandatory/Optional: optional
Default value: null
Path: root.actions or hotspots.actions
Detailed Description: This is shown to the user while waiting for the response, instead of the spinning wheel. Empty by default (spinning wheel shown by default).
NOTE: this is only shown for actions that run in the background. The contentType should be text/plain or application/vnd.layar.async.
Example: 
"activityMessage" : "Changing your status..."
closeBiw boolean Geo Layer Only: specifies whether BIW should be closed after clicking the action button.
Introduced API: v4.0
Mandatory/Optional: optional for Geo layer/ deprecated for Vision layer
Default value: false
Path: hotspots.actions
Detailed Description: If true, the layar client will close the BIW after the user clicked the button of the action. This way, after the action has opened/played, the user returns in the POI view (AR, map, list) rather than in the BIW.
NOTE: not included in layer level actions defined in the JSON response.
Example: 
"closeBiw" :  false
autoTriggerRange integer Only for Geo POIs, indicates whether or not this action can be autotriggered by reaching the POI.
Introduced API: v3.0
Mandatory/Optional: optional
Default value: null
Path: hotspots.actions
Detailed Description: The presence of this parameter indicates whether of not this action can be autotriggered by reaching the POI. Note that only one action can be auto-triggered, the layar client will use the first one in the array having this parameter. The parameter itself is the distance in m within which the user must be of the POI position in order for the auto-trigger to launch.
NOTE: not included in the layer level Actions object defined in the JSON response.
Example: 
"autoTriggerRange" :  50
autoTrigger boolean Only for Vision POIs, indicates whether or not this action can be autotriggered the POI is displayed for the first time.
Introduced API: v6.0
Mandatory/Optional: optional
Default value: false
Path: hotspots.actions
Detailed Description: Autotrigger indicator for Vision enabled POIs. "autoTriggerRange" mentioned above does not work for Vision enabled POIs because there is no range to be determined.
NOTE: not included in the layer level Actions object defined in the JSON response.
Example: 
"autoTrigger" :  true
autoTriggerOnly boolean Indicates whether or not this action can be invoked manually.
Introduced API: v3.0
Mandatory/Optional: optional
Default value: false
Path: hotspots.actions
Detailed Description: This indicates whether of not this action can also be invoked manually by the user outside of the range specified for a Geo POI or when a Vision POI is recognized. If true, the action will not be shown when pressing the button to display all possible actions, unless the user is within the give range of a Geo POI or a Vision POI is recognized.
NOTE: not included in the layer level Actions object defined in the JSON response.
Example: 
"autoTriggerOnly" :  true

JSON Response Examples

{"hotspots": [{
   "id": "test_1",
   "anchor": { "referenceImage": "my_reference_image",  
   "actions": [{ "uri": "tel:215-862-1996",
                 "autoTrigger": false,     
                 "autoTriggerOnly": false,     
                 "contentType": "application\/vnd.layar.internal",     
                 "method": "POST"}, 
               { "uri": "http://www.example.com/music.mp3", 
                 "autoTrigger": true, 
                 "autoTriggerOnly": true, 
                 "contentType" : "audio/mp3", 
                 "method": "GET" },
 {  "uri": "http://www.example.com/yourcard.vcf",
            "contentType": "text/vcard",
            "label": "vcard" }

]
 }], 
 "layer": "snowy4",
 "errorString": "ok", 
 "errorCode": 0
} 
{"hotspots": [{
   "id": "test_1",
   "anchor": { "geolocation": {"lat":52.3739, "lon": 4.93}},  
   "actions": [{ "uri": "tel:215-862-1996",
                 "label": "call",
                 "activityType": 2,
                 "autoTriggerRange": 200,     
                 "autoTriggerOnly": false,     
                 "contentType": "application\/vnd.layar.internal",     
                 "method": "POST"}
 }], 
 "layer": "snowy4",
 "errorString": "ok", 
 "errorCode": 0
}

Attachments

Related topics

Layar Developer API - GetPOIs Response Layar Developer API - GetPOIs Response - hotspots Howto - adding Actions introduction Second Tutorial - Layer with Actions Layar Intent