Layar Developer Documentation

Back to layar.com

API v8.5 Changes

NOTE: These are the changes in Developer API v8.5. It is supported in Layar client and LayarSDK v8.5 (and above) on both Android and iPhone.

In Layar API v8.5 we added the following features:

GetPOIs response change

Event Handlers

Layar 8.5 introduces the concept of event handlers to the Layar API, which allows actions or POI updates to be triggered after certain events. This enables developers to add more complex functionality to their experiences, e.g. sequencing of videos, but also dynamic content without server interaction.

Event Types

The following event types are defined on the hotspots 'object' element:

API syntax:
"object:" {
    "url": "...",
    "contentType": "image/png",
    "size": 1.0,
    "onClick": {
        "action": {
            "contentType": "application/vnd.layar.internal",
            "uri": "layar://[layername]/?parameters"
        }
    }
}

Event Handler object

The event handler object tied to an event is a simple JSON dictionary with 3 optional attributes.

Event Object
Attribute name Attribute name
action Action to be executed the moment the event is triggered. Follow the same syntax as the hotspots 'actions' attribute.
update The update attribute can be used to perform a POI update without requiring a server call.
handler String value referring to another event handler registered in the global event handler registry.

An event handler should have at minimum one of these attributes, but can have more. If it defines more, all actions are triggered. This allows us to update POIs, but still do an async server call to notify the backend of the event.

update object
Attribute name Attribute name
hotspots Array of hotspots that need to be added/updated
deleted_hotspots    Array of hotspot ids that need to be deleted

The update object allows us to add/update hotspots dynamically as a result of a triggered event without having to rely on server calls. The app handles this as if we would have received a getPOIrequest response with fullRefresh="false".

API syntax:
"object": {
   "url": "...",
   "contentType": "image/jpeg",
   "size": 1.0,
   "onClick": {
      "update": {
         "hotspots": [
            {
               "id": "poiToUpdate",
               ...
            }
         ],
         "deletedHotspots": ["poiId1ToDelete", "poiId2ToDelete"]
      }
   }
}

Global Event Handler Registry

At the root level of a getPOIs response a new attribute named 'handlers' is added. The value of this attribute is a JSON dict. This allows the developer to specify event handlers at a global level so they can be reused by different POI objects. This also allows us to have more advanced functionality like toggles.

Example:
"hotspots": [{
   "id": "door",
   "object:" {
      ...
      "onClick": {
         "handler": "open_door"
      }
      ...   }}],
"handlers": {
   "open_door": {
      "update": {
         "hotspots": [{
            "id": "door",
            "object": {
               ...
               "onClick": {
                  "handler": "close_door"
               }
               ...
            }
         }]
      }
   },
   "close_door": {
      "update": {
         "hotspots": [{
            "id": "door",
            "object": {
               ...
               "onClick": {
                  "handler": "open_door"
               }
               ...
            }
         }]
      }
   }
}