API v7.0 Changes
NOTE: These are the changes in Developer API v7.0. It is supported in Layar client v7.0 (and above) on both Android and iPhone that will be released soon.
Changes in GetPOIs Response
When API v6.2 was introduced, we announced that we would separate Geo-location and Vision based content completely in v7.0. We made this decision based on a lot of user testing, user feedback and looking at what features were used by layer developers. This will simplify the user interface for vision layers. All user interaction should take place directly in AR, on top of the content being augmented. This gives a context to each action, as it needs to be associated with a visible augment on top of the page being augmented. If you need multiple actions on one printed item, create multiple 'buttons', each with its own action. A nice trick is to create your assets in such a way that the buttons together look like one larger augment with multiple interaction parts. In API v7.0, the changes mentioned below will take effect.
Some parameters are not supported anymore for Vision layers
The detailed API v7.0 documentation can be found at Layar Developer API - GetPOIs Response . These changes were also communicated when API v6.2 was introduced. Below is a brief summary of the changes:
- In Layar clients v7.0 and above, there will be no BIWs in the UI. Therefore, all parameters related to BIW display in hotspots are removed, such as text, imageURL, showSmallBiw, showBiwOnClick and biwStyle.
- Layer level actions will be removed. Since BIWs are gone, actions.label and actions.activityType are removed for POI level actions. For Vision POIs, each augment can have maximum two action events, namely Click event and Auto-trigger event.
- Click event happens when a user clicks on the augment. The first action in the array with "autoTriggerOnly = false" will be executed.
- Auto-trigger event, the first action in the array with "autoTrigger=true" will be triggered automatically when a Vision POI is recognized.
- hotspots.icon object is removed since only 2d image, 3d model and AR video are supported in Vision layer.
NOTE: The UI optimization related to the API changes mentioned above will take place in Layar clients v7.0. In addition, since BIW dialog will be removed, there will be no need to provide list view and map view anymore for Vision Layers. These two views will be removed in Layar v7.0. Unsupported parameters will be filtered out by Layar servers before being passed to Layar clients (v7.0 and above). This might affect the user experience of a vision layer which heavily relies on these removed parameters in Layar client v7.0 and above.
JSON Response Example for Vision layers
{
"layer": "arvideotest",
"hotspots": [
{
"object": {
"url": "http://example.com/video.mp4",
"size": 0.1,
"contentType": "video/mp4"
},
"anchor": {
"referenceImage": "m1-darknight"
},
"id": "1"
}
],
"errorCode": 0,
"errorString": "ok"
}Separation of Geo-location and Vision based layers
in API v7.0, Vision and geo-location POIs cannot be mixed in the same layer. A layer is either vision-enabled or geo-location based only. For a layer with mixed geo-location and vision POIs, depending on whether Layar Vision is enabled or not on the publishing site, Layar server will:
- pass vision POIs only to layar apps if Layar Vision is enabled (checked).
- pass geo POIs only to layar apps if Layar Vision is disabled (unchecked).
This means a layer with mixed vision and geo POIs will not function exactly the same in Layar App v7.0 and above as it used to be. Developers can still mix geo and Vision in one experience. Create two layers and link between them using actions. This will allow the user to switch between the two modes while at the same time enabling the content provider to clearly tell the user what is going to happen (e.g. "Now look around you!" when switching to geo-mode).
Enhanced "recognizedReferenceImage" parameter in GetPOIs Request
In API v7.0, if multiple reference images in a layer are recognized when scanning a page or an object, image keys defined on the publishing site will be added to the getPOIs request. The keys are separated using comma(%2C), for instance, recognizedReferenceImage=cheating%2Cmonkey%2Cbeer. More information can be found here .
Added "service" parameter to layarshare:// intent
A new parameter "service" is added to specify a particular service that a share button is meant to be used for. Developers can define whether users can share a message / screenshot to facebook, twitter or developer URL using this parameter. If not specified, the user gets to choose which service to use. If specified, the user will directly use the defined service. For more information, please check out Layar Intent page.
Frequently Asked Questions:
- Is API v7.0 backward compatible ?
[Answer]: Yes. The API v7.0 is backward compatible with previous versions of the Layar Reality Browser on Android and iPhone. Layers created using API v7.0 will still function in older layar clients. Old layers created using API v6.2 or earlier will still work in Layar client v7.0 and above. However, since quite some keys are removed in API v7.0, the same layer might not work the same way in newer clients (v7.0 and above) as in lower layar client versions. For instance, the entire BIW dialog will be ignored in Layar clients v7.0 and above for Vision layers.
- Are there any tutorials available for creating vision layers based on API v7.0 ?
[Answer]: The existing Layar tutorials are based on Layar API v6.0. It is fairly easy to convert the existing sample codes to reflect the changes. If you want to create Vision layers, some parameters need to be removed from the JSON response. For Geo layer creation, you can still use the existing sample codes since nothing is changed for Geo layer.