Layar Developer Documentation

Back to layar.com

Actions

Feature Introduction

Users can also have interactions with each augment, for instance play some music, watch a movie trailer, go to a web page to get more information, etc. These are defined as "Actions" in a layer. Actions can be attached to a POI or defined on a layer level depends on how they should be used. Well defined "Actions" can dramatically enhance user experience. For instance, by automatically playing some music or sound effect while the user is entering certain area. Not just this, "Actions" can also be used in story boarding, gaming mechanism, etc. 

Key Steps to Implement

Change the minimum API version on the publishing site

"Actions" were introduced in API version 3.0 and enhanced in API version 4.0. If you are creating layers according to the latest API, it is better to change the Minimum API version to 4.0 or higher.

GetPOIs Response

The detailed description of "actions" object can be found here

Example Response

Here we list a few examples of action types:

"actions": [ {
  "label": "Contact Layar",
  "uri": "http:\/\/layar.com\/company\/contact\/",
  "contentType": "text\/html",
  "method": "GET",
  "activityType": 1
}]
"actions": [ {
  "label": "Music",
  "uri": "http:\/\/example.com\/music.mp3\/",
  "contentType": "audio/mpeg",
  "method": "GET",
  "activityType": 2
}]

NOTE: All formats supported natively by the device are supported. For cross-device compatibility, mp3 files are best. For audio fragments on the phone, 96kbit should be enough. Music should be max 128kbit. Higher than this is not guaranteed to work.

"actions": [ {
  "label": "Video",
  "uri": "http:\/\/example.com\/video.mp4\/",
  "contentType": "video/mp4",
  "method": "GET",
  "activityType": 3
}]

NOTE: All formats supported natively by the device are supported. In order to ensure cross-device compatibility, mpeg4 and 3gpp are best (480x320 resolutions). Ensure your video is encoded for http streaming, including progressive download hints.

"actions": [ {
  "label": "Call Layar",
  "uri": "tel:+31203201617",
  "contentType": "application/vnd.layar.internal",
  "method": "GET",
  "activityType": 4
}]
"actions": [ {
  "label": "Mail Layar",
  "uri": "mailto:info@layar.com",
  "contentType": "application/vnd.layar.internal",
  "method": "GET",
  "activityType": 5
}]
"actions": [ {
  "label": "refresh layer",
  "uri": "layar:\/\/layername\/?action=refresh&custom_params=custom", 
  "contentType": "application/vnd.layar.internal",
  "method": "GET",
  "activityType": 6
}]

NOTE that layar:// intent can be used to send a new getPOIs request to retrieve a new getPOIs response. This can be very useful when you want to provide dynamic information, feedback, etc. Another way to achieve this is to use async call mentioned below.

"actions": [ {
  "label": "vote for it!",
  "uri": "http:\/\/example.com\/vote_for_it.php", 
  "contentType": "application/vnd.layar.async",
  "method": "GET",
  "activityType": 7,
  "closeBiw":false, 
  "showActivity": true, 
  "activityMessage": "sending a vote..." 
}]

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. While retrieving a new set of POIs, the message defined in "activityMessage" parameter will be displayed in the message bar for optimized user experience.

"actions": [{
  "label": "Share message",
  "uri": "layarshare:\/\/sharingapi\/?title=message%20title&type=message&link=http%3A%2F%2Fcustom.layar.nl%2F&icon=http%3A%2F%2Fcustom.layar.nl%2FPOIimage.jpg&description=check%20out%20this%20object",
  "contentType": "application\/vnd.layar.internal",
  "activityType": 13
 },
 {
  "label": "Share screenshot",
  "uri": "layarshare:\/\/sharingapi/?type=screenshot",
  "contentType": "application\/vnd.layar.internal",
  "activityType": 13
  }
]

 In case you host your Vcard in a Url you can use the following action

"actions": [{
  "label": "Vcard",
  "uri": "http://exampleurl.com/mycard.vcf"
  "contentType": "text/vcard"
 },
]

Alternatively you can use the URI "data:text/" as shown below

  "actions": [
        {
            "uri": "data:text/plain;charset=utf-8;base64,QkVHSU46VkNBUkQNClZFUlNJT046Mi4xDQpOOkd1bXA7Rm9ycmVzdA0KRk46Rm9ycmVzdCBHdW1wDQpPUkc6QnViYmEgR3VtcCBTaHJpbXAgQ28uDQpUSVRMRTpTaHJpbXAgTWFuDQpQSE9UTztHSUY6aHR0cDovL3d3dy5leGFtcGxlLmNvbS9kaXJfcGhvdG9zL215X3Bob3RvLmdpZg0KVEVMO1dPUks7Vk9JQ0U6KDExMSkgNTU1LTEyMTINClRFTDtIT01FO1ZPSUNFOig0MDQpIDU1NS0xMjEyDQpBRFI7V09SSzo7OzEwMCBXYXRlcnMgRWRnZTtCYXl0b3duO0xBOzMwMzE0O1VuaXRlZCBTdGF0ZXMgb2YgQW1lcmljYQ0KTEFCRUw7V09SSztFTkNPRElORz1RVU9URUQtUFJJTlRBQkxFOjEwMCBXYXRlcnMgRWRnZT0wRD0wQUJheXRvd24sIExBIDMwMzE0PTBEPTBBVW5pdGVkIFN0YXRlcyBvZiBBbWVyaWNhDQpBRFI7SE9NRTo7OzQyIFBsYW50YXRpb24gU3QuO0JheXRvd247TEE7MzAzMTQ7VW5pdGVkIFN0YXRlcyBvZiBBbWVyaWNhDQpMQUJFTDtIT01FO0VOQ09ESU5HPVFVT1RFRC1QUklOVEFCTEU6NDIgUGxhbnRhdGlvbiBTdC49MEQ9MEFCYXl0b3duLCBMQSAzMDMxND0wRD0wQVVuaXRlZCBTdGF0ZXMgb2YgQW1lcmljYQ0KRU1BSUw7UFJFRjtJTlRFUk5FVDpmb3JyZXN0Z3VtcEBleGFtcGxlLmNvbQ0KUkVWOjIwMDgwNDI0VDE5NTI0M1oNCkVORDpWQ0FSRA==",
            "contentType": "text/vcard",
            "label": "vcard"
        }
    ]

There are some tools you can use to create this type of you data URI for you. for this example we used the tool provided by dopiaza.org . if you are not familiar in creating Vcard files the Wikipedia page has some useful examples.

Tutorials & Sample Code

We also created a tutorial which explains how to add "actions" to a simple layer. Sample Code written in php is available for downloading at the end of the tutorial. 

Notes

Auto-triggered actions

Auto-trigger options are also available in each action. Depending on whether a POI is geo-location based or vision based, different auto-trigger parameters are used. The layar client behaves differently as well.

Prerequisite: a layer with both Geo POIs and Vision enabled POIs.

Background information:

Since Layar Developer API 3.0, auto-triggered actions have been introduced. The following two parameters were defined to control the auto-triggered actions for Geo POIs.

Geo-location POIs
KeyValueExampleExplanation
autoTriggerRangeinteger
"autoTriggerRange": 50
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 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 new Actions object (layer level) defined in the JSON response.
autoTriggerOnlyboolean
"autoTriggerOnly":false
Indicates whether of not this action can also be invoked manually by the user outside of the range specified. 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 the POI.
NOTE: not included in the new Actions object (layer level) defined in the JSON response.

NOTE:

For Geo POIs, "autoTriggerRange" is used to determine when an action should be triggered automatically. However, for Vision enabled POIs, it is not possible to calculate the distance between those POIs and the user. In getPOIs API v6, a new "autoTrigger" parameter is defined in "action" object on POI level.

Vision POIs
KeyValueExampleExplanation
autoTriggerboolean
"autoTrigger":true
Indicates whether an action should be automatically triggered at the moment when the augment is rendered successfully. "autoTriggerRange" parameter is not used. "autoTriggerOnly" remains its meaning for Vision enabled POIs. 

Layar Client Behavior:

By default, auto-triggered actions are launched automatically without warning the user.

In the layar client settings, there should be one setting regarding auto-triggers:

When the user sets this option to true, an alert is shown each time that an auto-trigger action is to be launched asking whether or not to launch the action. This pop-up alert has the following attributes:

NOTE: The user cannot disable the alert directly from this pop-up alert. If the alert is shown, it means he enabled it in the settings so he should know how to switch it off.