hotspots

Please NOTE that this documentation describes the getPOIs API v7.1. Developers must use this specification to create new Vision layers. The API v7.1 is backward compatible with previous versions of the Layar Reality Browser (v3.0 and higher on Android and iPhone).

JSON Response - hotspots object

`id`	string	The unique id for the POI
Introduced API:	v2.1
Mandatory/Optional:	mandatory
Path:	root.hotspots
Detailed Description:	The unique id which identifies a POI in the getPOIs response. This is used to track the POIs when refreshing the layer.
Example:	"id" : "ae22826e16829a6f"

`anchor`	Type: string or json dictionary	Placement of the POI.
Introduced API:	v6.0
Mandatory/Optional:	mandatory
Path:	root.hotspots
Detailed Description:	Placement of the POI. Can either be a geolocation or the key of a reference image in Layar Vision. For geolocation, alt is optional but lat and lon are mandatory.
Example:	"anchor": { "referenceImage": "myFirstImage" } "anchor": { "geolocation": { "lat": 52.3, "lon": 4.5 } }
`geolocation`	json dictionary	The geo coordinates of a POI.
Path:	root.hotspots.anchor
Detailed Description:	The geo location coordinates of a POI, alt is optional but lat and lon are mandatory.
Example:	"geolocation": { "lat": 52.3, "lon": 4.5, "alt": 20 }
`lat`	decimal	The decimal GPS coordinate value of the latitude for the POI.
`lon`	decimal	The decimal GPS coordinate value of the longitude for the POI.
`alt`	decimal	The decimal GPS coordinate value of the altitude for the POI.
`referenceImage`	string	the key of a reference image.
Path:	root.hotspots.anchor
Detailed Description:	The image key of the reference image uploaded to the publishing site.
Example:	"referenceImage": "myFirstImage"

`text`	json dictionary	Geo Layer Only: Descriptive text about the POI displayed in the BIW.
Introduced API:	v6.0
Mandatory/Optional:	mandatory for Geo layer/deprecated for Vision layer
Path:	root.hotspots
Detailed Description:	For Geo layers, each POI has a brief information widget (BIW) which can be used to provide some text to describe the POI (no HTML is supported). It contains three parameters, title, description and footnote. The structure of the "text" object looks like follows:
Example:	"text": { "title": "Layar office", "description": "The location of the Layar HQ in Amsterdam", "footnote": "Powered by Layar" }
`title`	string	The title of the POI
Mandatory/Optional:	mandatory
Path:	root.hotspots.text
Detailed Description:	This is the first line in the BIW dialog on the client. It has larger font and uses the Banner text color defined under the "Look & feel" tab of the publishing site. The recommended maximum string length is 60 characters and it will be wrapped over 2 lines.
`description`	string	the main content of the BIW.
Mandatory/Optional:	optional
Default value:	null
Path:	root.hotspots.text
Detailed Description:	Some text can be used to explain the POI. It has normal font and uses the BIW Text Color defined under the "Look & feel" tab of the publishing site. The recommended maximum string length is 140 characters and it will be wrapped over 3 lines.
`footnote`	string	The last line in the BIW.
Mandatory/Optional:	optional
Default value:	null
Path:	root.hotspots.text
Detailed Description:	One line of string at the bottom part of the BIW. It has small font and uses the BIW Title Color defined under "Look & feel" tab of the publishing site. The recommended maximum string length is 45 characters without wrapping. Extra characters will be cut off on the screen.

`actions`	array of action objects	Defines actions on POI level.
Introduced API:	v2.1; modified in later API versions.
Mandatory/Optional:	optional
Default value:	empty array, []
Path:	root.hotspots
Detailed Description:	This enables actions on the POI level. Each POI can have its own actions. They will appear on the expanded BIW dialog. See details on the actions page.
Example:	"actions": [{ "contentType":"text/plain", "method":"GET", "uri":"http://mylayer.com/account/?online=true&", "params": ["lat","lon"], "label":"Go online", "activityType":3}]

`imageURL`	string	Geo Layer Only: an image displayed in the BIW of a POI.
Introduced API:	v2.1
Mandatory/Optional:	optional for Geo layer/deprecated for Vision layer
Default value:	null
Path:	root.hotspots
Detailed Description:	The location of the image to be displayed inside the BIW. If the image is too large, it will be resized to fit within a bounding box of 100x75 pixels, preserving aspect ratio. NOTE: the image file size should be smaller than 100kb, otherwise, the image will not be loaded.
Example:	"imageURL" : "http:\/\/94.100.16.70\/1790001\/2346232\/1344536_5_7u7.jpeg"

`showSmallBiw`	boolean	Geo Layer Only: decides whether a small BIW dialog should be shown
Introduced API:	v4.0
Mandatory/Optional:	optional for Geo layer / deprecated for Vision layer
Default value:	true
Path:	root.hotspots
Detailed Description:	This tells the layar client whether or not a small BIW (the one at the bottom of the screen) should be shown when the POI is in focus.
Example:	"showSmallBiw" : false

`showBiwOnClick`	boolean	Geo Layer Only: decides whether a detailed BIW dialog together with actions list should be shown
Introduced API:	v4.0
Mandatory/Optional:	optional for Geo layer / deprecated for Vision layer
Default value:	true
Path:	root.hotspots
Detailed Description:	This tells the client whether or not a detailed BIW (the big one in the middle of the screen) should be shown when the user clicks on the POI or on the small BIW. If the value is false, the first action from the list of actions will be fired instead. NOTE: This means there is no way for the user to manually access the actions. The first one is triggered by a user click, one other action can be activated by using autoTrigger settings. More than 2 actions won't be used.
Example:	"showBiwOnClick": false

`biwStyle`	string	Geo Layer Only: specifies the BIW display style.
Introduced API:	v6.0
Mandatory/Optional:	optional for Geo layer / deprecated for Vision layer
Default value:	"classic"
Path:	root.hotspots
Detailed Description:	This tells the client which BIW style should be used, classic or collapsed. "classic" style displays the entire "text" object when a POI is in focus while "collapsed" style only shows the text.title parameter. This POI level "biwStyle" will overrule the "biwStyle" defined on the layer level.
Example:	"biwStyle": "collapsed"

`icon`	json dictionary	Geo Layer Only: defines the CIW icon representation for a POI in the Camera view.
Introduced API:	v6.0
Mandatory/Optional:	optional for Geo layer/ deprecated for Vision layer
Path:	root.hotspots
Detailed Description:	A POI can be represented by an icon defined in the "url" parameter below or a set of CIW (Custom POI Indicator Widget) icons defined on the publishing site. If a few POIs serve the same kind of purpose and can be represented by the same icon set, it is recommended to use the CIW icon sets. You can check here to learn more on how Layar client renders POIs in the Camera view.
Example:	"icon": { "url": "http://example.com/icon.png", "type": 2 }
`url`	string	The URL to the icon image
Mandatory/Optional:	optional
Default value:	null
Path:	root.hotspots.icon
Detailed Description:	Each POI can be represented by an image defined in this url
`type`	integer	The type of CIW set
Mandatory/Optional:	optional
Default value:	0
Path:	root.hotspots.icon
Detailed Description:	On the publishing site, CIW icon set can be defined under the "Look & feel" tab. Each CIW icon set will have a type value. In the JSON response, you can fill in the right type value to determine which CIW icon set should be used to represent a POI.

`object`	json dictionary	Uses a 2D (image), 3D (model), AR video or HTML Widgets object to represent a POI.
Introduced API:	v3.0; in v6.2 introduced "AR video" object for Vision layer.
Mandatory/Optional:	optional for Geo layers ; *mandatory for Vision layers*
Path:	root.hotspots
Detailed Description:	In the Camera view, a POI can be represented by: 2D image (introduced in API v3.0), file size should be smaller than 100Kb. 3D model (introduced in API v3.0), file size should be smaller than 1Mb. AR Video (introduced in API v6.2), videos need to be in MP4 container with h264 codec for video and AAC codec for audio. The resolution should be 320x240 pixels. HTML Widgets (introduced in API v7.1), need to represent small snippets of web content that can be dynamic and interactive, created using HTML, javascript, and CSS. These objects will be rendered realistically as if they are placed in the real world. More detailed explanations on how to add objects to a layer and how layar clients render objects are documented here .
Example:	"object": { "contentType": "model/vnd.layar.l3d", "url": "http://example.com/example_full.l3d", "reducedURL": "http://example_reduced.l3d", "size": 2 }
`contentType`	string	The content type of the object.
Mandatory/Optional:	mandatory
Path:	root.hotspots.object
Detailed Description:	This determines whether a POI should be represented by a 2D image, a 3D model or an AR Video. The available options are: image/vnd.layar.generic for any supported image type (PNG, GIF, JPEG); image/jpeg, image/gif, image/png for images. model/vnd.layar.l3d for 3D models. video/mp4 for AR video. text/html for HTML Widgets
`url`	string	The URL of the object to be displayed./HTML Widgets: the URL of the page that the viewport refers to is hosted
Mandatory/Optional:	mandatory
Path:	root.hotspots.object
Detailed Description:	HTML Widgets: This URL should point to the webpage that can be displayed in HTML Widgets. Only pages written in HTML, javascript, and CSS will be recognized. Availability of the page is checked inline and reported if 404 error is found, as a warning.
`size`	float	The height of the object in meters.
Mandatory/Optional:	mandatory
Path:	root.hotspots.object
Detailed Description:	This is used to specify the size of the object. For 2D images and AR videos, this determines the size at which the object will be rendered. For 3D models, this is a cue to the client whether to select the full model or the reduced model (if there is a reduced model) to download. For HTML Widgets this value specifies the size of the widget with respect to the reference image/Page, preserving the aspect ratio of the widget. This also affects the size of the content within the viewport, i.e. the pixel size within the viewport will scale proportionally as the value of size is changed.
`reducedURL`	string	Geo Layer Only: the URL of a smaller version of object to be displayed.
Mandatory/Optional:	optional for Geo layer / deprecated for Vision layer
Default value:	null
Path:	root.hotspots.object
Detailed Description:	This defines a smaller version to be rendered when the POI is further away from the user. Specifying this can improve performance when there are many POIs on the screen. NOTE: Do not put the same URL here as for object.url, it will not have any functional effect and only consume bandwidth.
`previewImage`	string	Vision Layer Only: a placeholder of the AR video
Mandatory/Optional:	Not needed for 2d image and 3d model mandatory for AR video
Path:	root.hotspots.object
Detailed Description:	This image is used while buffering the video. To make the AR video work across all platforms, developers can provide an image as the placeholder when no AR video playback is available on the device.
`viewport`	Json dictionary	HTML Widgets only:The visible area of the webpage
Mandatory/Optional:	mandatory
Path:	root.hotspots.object
Detailed Description:	This defines the viewport of an HTML panel. The width and height of the viewport define the portion of the webpage visible to the augment in CSS pixels. Their values should match the page dimensions of your web page if you want to fully display it. We strongly suggest setting viewport to less than 300x400 pixels. Technically we allow a maximum viewport of 512x512 pixels.The image bellow shows how a page will be displayed if viewport's width and height values are smaller than the actual size in CSS pixels.
`width`	pixels	HTML Widgets only:The width of the viewport
Path:	root.hotspots.object.viewport
Description:	The width of the viewport in CSS pixels.

`height`	pixels	HTML Widgets only:The height of the viewport in pixels
Path:	root.hotspots.object.viewport
Description:	the height of the viewport in CSS pixels.

`Scrollable`	Boolean	HTML Widgets only:Enables scrolling of the viewport
Path:	root.hotspots.object.viewport
Default value:	false (recommended, unless there is a good reason to set it to true)
Description:	If set to true users can scroll to view the overflown content of the page. Please NOTE that on Android devices users will still be able to scroll even if value is set to false, scrolling bars will not be shown however. On iPhone, the content is not scrollable if value is set to false as expected. In general for AR use cases it is good practice to make your HTML content fit exactly within the viewport, so that no scrolling is needed.
`Interactive`	Boolean	HTML Widgets only:Enables interaction within the viewport.
Path:	root.hotspots.object.viewport
Default value:	true
Description:	When set to true the web view behaves like a normal browser, users can click links and select buttons. Please NOTE that users will navigate away to a new Page that is displayed in the web view in full screen. If set to false it will overrule the scrollable parameter and its value will be considered as false. In that case users will no longer be able to interact with the page content but view it. Once viewport.interactive is set to false, it is possible to attach POI level actions to the HTML widget. If a user clicks on the HTML widget, the action will be triggered. For more information on actions please check actions

`transform`	json dictionary	Enhanced control of positioning objects.
Introduced API:	v3.0; modified in API v6.0.
Mandatory/Optional:	optional
Path:	root.hotspots
Detailed Description:	A few factors can be used to transform objects in Camera view, for instance scale, rotation and translate.
Example:	"transform": { "rotate": { "rel": true, "axis": { "x": 0, "y": 0, "z": 1 }, "angle": 0 }, "translate": { "x": 0, "y": -0.075, "z": 0 }, "scale": 0.01 }
`rotate`	json dictionary	Rotates object over the given axis in its own local coordinate system.
Mandatory/Optional:	optional
Path:	root.hotspots.transform
Example:	"rotate": { "rel": true, "axis": { "x": 0, "y": 0, "z": 1 }, "angle": 0 }
`rel`	boolean,	optional, false by default	Means the rotation is relative to the user around z-axis. On layar client, "axis" and "angle" are applied after "rel" has been applied. If "rel" is set to true, the Geo-location or Vision enabled POI will rotate over the Z-axis to face the user first, then it will rotate around the defined "axis" with a certain degrees defined in "angle" parameter. From then on, the rotation is relative to the user around z-axis.
`axis`	json dictionary	mandatory	Each axis has a type of float.
`angle`	decimal	mandatory	Rotation angle in degrees to rotate the object around the z-axis. The rotation direction is determined by the usual right-hand thumb rule (positive angle: counter clock-wise in the x-y plane).
`translate`	json dictionary	Translate the POI to another location from its anchor point.
Mandatory/Optional:	optional. If used, all the axes are mandatory and the type should be decimal.
Path:	root.hotspots.transform
Detailed Description:	This can be used to position the object at another location within the coordinate system. The distance unit is meter. NOTE that "transform.translate.z" parameter is applied to object's altitude. If you want to place a POI always relative to user's latitude (object's initial anchor point), do not provide "alt" in anchor dictionary in the getPOI response and just specify this "transform.translate.z" parameter.
Example:	"translate": { "x": 0, "y": -0.075, "z": 0 }
`scale`	decimal	The multiplication factor to scale the object.
Mandatory/Optional:	optional
Default value:	1.0
Path:	root.hotspots.transform

`animations`	string or json dictionary	Animations can be applied to a POI.
Mandatory/Optional:	Optional
Default value:	null
Path:	root.hotspots
Detailed Description:	This defines the animation for this specific POI. If defined, it overrides the default animations definition on layer root level. Please read here for detailed specification.
Example:	"animations": { "onClick": [ { "interpolation": "overshoot", "to": 2, "length": 2000, "from": 0, "delay": 0, "repeat": false, "type": "scale", "axis": { "y": 1, "x": 1, "z": 1 }, "persist": true }] }

`inFocus`	boolean	Geo Layer Only: specifies whether a POI should be locked initially in the AR view.
Mandatory/Optional:	optional for Geo layer/ deprecated for Vision layer
Default value:	false
Path:	root.hotspots
Detailed Description:	A value of True indicates to the client that this particular POI should be locked directly when the POIs are shown. Only one POI can have this flag set to true in the getPOIs response. If more than one POI has this value set to True, the client will pick one (no guarantee which). By default, it is false.
Example:	"inFocus": true

Complete JSON Response Example

When Vision POIs are returned

{"hotspots": [{
   "id": "test_1",
   "anchor": { "referenceImage": "my_reference_image",  
   "actions": [{
     "uri": "tel:215-862-1996",
     "autoTrigger": true,
     "autoTriggerOnly": true,
     "contentType": "application\/vnd.layar.internal",
     "method": "POST",
     "showActivity": false,
     "activityMessage": "calling layar"
    }], 
    "object": {
      "contentType": "model/vnd.layar.l3d",
      "url": "http://example.com/example_full.l3d",   
      "size": 2
    },
    "transform":  {
      "rotate": {  
      "rel": true,    
      "axis": { "x": 0, "y": 0, "z": 1 },
      "angle": 0   },  
      "translate": { "x": 0, "y": -0.075, "z": 0 },  
      "scale": 0.01
    } 
 }], 
 "layer": "snowy4",
 "errorString": "ok", 
 "errorCode": 0
}

When Geo-location POIs are returned

{"hotspots": [{
   "id": "test_1",
   "anchor": { "geolocation": { "lat": 52.3729, "lon": 4.93 } },  
   "text": {
     "title": "The Layar Office", 
     "description": "The Location of the Layar Office", 
     "footnote": "Powered by Layar" },
   "imageURL": "http:\/\/custom.layar.nl\/layarimage.jpeg",
   "actions": [{
     "label": "Contact Layar",
     "uri": "http:\/\/layar.com\/company\/contact\/",
     "autoTriggerRange": 5000,
     "autoTriggerOnly": true,
     "contentType": "text\/plain",
     "method": "GET",
     "activityType": 1,
     "params": [
       "lat",
       "lon"
     ],
     "closeBiw": false,
     "showActivity": true,
     "activityMessage": "contact layar"
    }]
 }], 
 "layer": "snowy4",
 "errorString": "ok", 
 "errorCode": 0
}

hotspots

JSON Response - hotspots object

Complete JSON Response Example

Related topics