API v6.2 Preview

NOTE: This is the highlight of Developer API v6.2. It is supported in Layar client v6.2 (and above) on both Android and iPhone.

New Feature - AR Video

In API v6.2, developers can implement the video playback functionality in the Camera view for Vision enabled layers only. In addition to the supported object types (2d image and 3d models), a new type of object called AR Video is introduced to the "hotspots.object" JSON dictionary. Please see the details below:

"object": {
  "contentType": "video/mp4",
  "url": "http://example.com/example_video.mp4",   
  "previewImage": "http://example.com/example_video_still.png",
  "size": 2
}

Client Behavior:

Not all the devices support video playback. In general, only devices with dual-core processor can run AR video. The Android devices that we have tested are Google Galaxy Nexus, Samsung Galaxy S II and LG Optimus. AR video was also tested on iPhone 4S and iPad 2 with iOS v5.0 and above.

For devices that support AR video,

 1) As soon as tracking starts, “object.previewImage” with loading indicator will be used while buffering. It is mandatory to provide a valid “previewImage”.
 2) The video defined in “object.url” is played automatically after buffering enough content.
 3) When tracking stops, the video pauses. It continues to play when tracking starts again.
 4) When clicking on the AR video augment, the entire video is shown in the native video player (full screen).
 5) In the event that the user watches the video in AR View and it completes, a reload icon is shown on top of the preview image defined in "object.previewImage". Clicking this restarts the video in the AR view.

For devices that do not support AR video,

1) As soon as tracking starts, “object.previewImage” is displayed with a play button on top of it.
2) Clicking this “object.previewImage” takes the user to the default video player and video begins in full screen mode like how video action is launched. 

NOTE: In both cases mentioned above, no actions can be associated with clicking on the video object, because that is taken by the full screen view. And no extra buttons for start/stop or full screen to be added on top of the video. 

GetPOIs Response Optimization

Based on a lot of user testing and user feedback, we've decided to 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. 

We'll implement these changes in a future version of Layar, not v6.2. The most important change is that vision and geo POIs cannot be mixed in the same layer. A layer is either vision-enabled or geo only.

NOTE: While v6.2 clients will still support the current GetPOI API, we are deprecating parts of the API. This means that these parameters are still supported by the Layar Browser, but forward-compatibility is not guaranteed. This ensures developers have time to prepare for these changes. The next major version (v6.3 or v7.0) will not support these parameters.

Therefore in API v6.2, besides introducing AR Video to Vision layers, we also decided to deprecate large parts of the GetPOIs response for vision layers. The detailed API v6.2 documentation can be found at Layar Developer API - GetPOIs Response. Below is a brief summary of the changes:

Vision Layers

A few parameters are deprecated for Vision layers to ease the layer creation.

• In future Layar clients, there will not be BIWs in the UI. Therefore, all parameters related to BIW display in hotspots are deprecated, such as text, imageURL, showSmallBiw, showBiwOnClick and biwStyle.

• Layer level actions will be removed. Since BIWs are gone, actions.label and actions.activityType are deprecated 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.
  If the first action in the array has "autoTrigger = true" and "autoTriggerOnly = false", both Click events and Auto-trigger events will trigger that action. Any other actions in the array will be ignored.

• hotspots.icon object is deprecated 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 future Layar clients after v6.2. 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 the future. We strongly recommend our developers to start developing Vision layers based on the API v6.2 specification so that your layers are prepared for future changes in Layar clients.

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"

}

Frequently Asked Questions:

• Is AR video object also supported in Geo layer ? 

[Anwser]: No, it is only supported in Vision layer.

• Can I have multiple AR video objects on the same reference image ? 

[Answer]: No, only one AR video object is allowed for one reference image. If you want multiple AR videos on one page, upload the parts of the page that have different videos as separate reference images.

• How will the "hotspots.transform" dictionary be applied to the AR video object ?

[Answer]: No changes here. It is the same as how it is done for the 2d images and 3d models.

• Is API v6.2 backward compatible ? 

[Answer]: Yes. The API v6.2 is backward compatible with previous versions of the Layar Reality Browser on Android and iPhone. Layers created using API v6.2 will still function in older layar clients. Old layers created using API v6.0 or earlier will still work in Layar client v6.2 and above. However, since quite some keys are deprecated in API v6.2, the same layer might not work the same way in newer clients as in lower layar client versions. For instance, the entire BIW dialog will be ignored in future layar clients for Vision layers.

• Are there any tutorials available for creating vision layers based on API v6.2 ?

[Answer]: The existing tutorials will be updated shortly to API v6.2. However, 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.