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:

open a web page in web view

"actions": [ {
  "label": "Contact Layar",
  "uri": "http:\/\/layar.com\/company\/contact\/",
  "contentType": "text\/html",
  "method": "GET",
  "activityType": 1
}]

Play an audio file

"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.

Play a video file

"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.

Make a phone call

"actions": [ {
  "label": "Call Layar",
  "uri": "tel:+31203201617",
  "contentType": "application/vnd.layar.internal",
  "method": "GET",
  "activityType": 4
}]

Send an email

"actions": [ {
  "label": "Mail Layar",
  "uri": "mailto:info@layar.com",
  "contentType": "application/vnd.layar.internal",
  "method": "GET",
  "activityType": 5
}]

Generate a new getPOIs request using layar:// intent

"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.

Make an async call

"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.

Share a message or screenshot to facebook, twitter or your own server using layarshare:// intent

"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
  }
]

Show and download a Vcard

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
Key	Value	Example	Explanation
`autoTriggerRange`	integer	"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.
`autoTriggerOnly`	boolean	"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:

It may happen that the user enters a region that by chance is covered by 2 auto-triggered actions from two POIs. Only the closest POI is triggered in such case.
An action should be triggered only when the location changes from outside to inside the trigger area. If an action was already triggered, it does not get triggered repeatedly when the user stays inside the trigger area.
External applications can not be triggered automatically (using custom URL schemes).

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
Key	Value	Example	Explanation
`autoTrigger`	boolean	"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:

Title: Automatic actions
Option: Show trigger alers on/off (by default: off)
Explanation: Certain objects in the camera view can automatically trigger actions when you are close by, like open a web page, play a sound or play a video.

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:

Title: Title of the POI
Text: You've reached an object that wants to [open a website | play a sound | play a movie | launch an action] depending on the action content-type.
Two buttons: Launch + Don't Launch

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.