Client Specifications


 

Please NOTE that this documentation will not be updated anymore. Please see our new Developer Documentation Site for the latest updates!

 

 

On this page, we will list all the expected client specifications for the Layar Reality Browser. The rules should be applied to all the mobile platforms that Layar client is running on.

 

1. Auto-triggered Actions Options

2. Displaying POIs in the Map view

3. alt VS relativeAlt usage

4. Rendering POIs in the Camera view

5. The maximum number of returned POIs

6. Navigation in Layar client

 

1. Auto-triggered Actions Options

 

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.

 

Category Key Value Example Explanation Minimum API version

autotrigger control

(optional)

 autoTriggerRange integer "autoTriggerRange":25

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.

 v3.0
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.

 v3.0

 

NOTE:

 

Layar Client Behavior:

 

Affected Layar clients/versions: IPhone Layar client v4.0 and above; Android Layar client v4.0.3 and above.

 

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:

 

 

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:

 

 

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.

 

2. Displaying POIs on the Map view

 

Background Information:

 

Custom icon widget, known as CIW, can be created to represent the POI appearance in the camera view. Each set of CIW icons is related to a POI type value, from which the client determines which CIW to use if CIWs are defined. 0 = default CIW. 1-3 = use the custom CIW icons specified under Look & feel tab of the layer editing page. Since API v3.0, you can define more than 3 sets of custom CIW icons.

 

Layar Client Behavior:

 

Affected Layar clients/versions:   IPhone Layar client v4.0 and above; Android Layar client v4.0.3 and above.

 

When a set of CIW icons are defined for a POI (This POI has a type value which does not equal to 0),

 

When a set of CIW icons are not defined for a POI (This POI has a type value which equals to 0),

 

 

 

NOTE:  The unique POI icons supplied in the object dictionary of the GetPOI Response are not to be used on Map View.  Because the Map renders a large amount of POIs, the calls could take too long and provide a poor user experience given the amount of different icons that could be provided.  Instead, the system will default to the CIW or the default POIs (the circles) as indicated in the rules above.

 

3. alt VS relativeAlt usage

 

Background information:

 

In API v3.0, we introduced "alt" and "relativeAlt" parameters, so that POIs can have different altitude values in the camera view.   

 

API part  Parameter  Format  Example  Optional/Mandatory  Description
 getPOIs request
  alt  integer  alt=345  optional  The current altitude of the user in meters. This is not always known on the client and will only be passed when there is a gps fix.
 getPOIs response
  alt  integer "alt": 500
 optional  Real altitude of object in meters. If this is missing, the same altitude as the user is assumed.

NOTE: This parameter will be used only when the "alt" of the user is passed through in the getPOIs request. Otherwise, the value will be ignored.

 getPOIs response
  relativeAlt  integer  "relativeAlt":  50
  optional  Altitude in meters of the object with respect to the user's altitude (grid surface in the camera view).

NOTE: Not used if 'alt' is supplied and the user's altitude is known.

 

Layar Client behavior:

 

 Altitude known from device API
  "alt" in getPOIs request
  "alt" in getPOIs response
  "relativeAlt" in getPOIs response
  Expected Behaviors when rendering POIs in the camera view
 No  not present
  not present/ "alt": null
  not present/
"relativeAlt": null
  The same altitude as the user is assumed. In the camera view, this means that POIs will be right on top of the grid surface.
 No  not present
   not present/ "alt": null   "relativeAlt": 100  The "relativeAlt" parameter will be picked up. In the camera view, this means that POIs will be 100m above the grid surface.
 No  not present  "alt": 50
  not present/
"relativeAlt": null
  The same altitude as the user is assumed. In the camera view, this means that POIs will be right on top of the grid surface.
 No  not present
  "alt": 50  "relativeAlt": 100
  The "relativeAlt" parameter will be picked up. In the camera view, this means that POIs will be 100m above the grid surface.
Yes
 alt=200  not present/ "alt": null  not present/
"relativeAlt": null		  The same altitude as the user is assumed. In the camera view, this means POIs will be right on top of the grid surface.
 Yes  alt=200
 not present/ "alt": null  "relativeAlt": 100  The "relativeAlt" parameter will be picked up. In the camera view, this means that POIs will be 100m above the grid surface.
 Yes   alt=200  "alt": 50  not present/
"relativeAlt": null		 The "alt" parameter in the response (50) will be picked up.  the POIs will be 150m below user's real altitude. In the camera view, this means 150m below the grid surface.
 Yes  alt=200   "alt": 50 "relativeAlt": 100  The "alt" parameter in the response (50) will be picked up.  the POIs will be 150m below user's real altitude. In the camera view, this means 150m below the grid surface.

 

4. Rendering POIs in the Camera view

 

Background Information:

 

POI dimension
Object/Transform
Typical JSON Response per POI
1
Optional

{

  "id": "1",

  "distance": 100,

  "title": "POI 1",

  "lat": 123456,

  "lon": 123456,

  "action": [ ],

  "dimension": 1,

  "object": {
                "baseURL": "http:\/\/custom.layar.nl\/",
                "icon": "icon.png"
                }

}
2
Mandatory

{

  "id": "1",

  "distance": 100,

  "title": "POI 1",

  "lat": 123456,

  "lon": 123456,

  "action": [ ],

  "dimension": 2,

  "object": {
                "baseURL": "http:\/\/custom.layar.nl\/",
                "full": "2dimage_full.png",
                "reduced": "2dimage_reduced.png",
                "icon": "icon.png",
                "size": 120
                },
  "transform": {
                "rel": true,
                "angle": 0,
                "scale": 5
               }

}
3 Mandatory

{

  "id": "1",

  "distance": 100,

  "title": "POI 1",

  "lat": 123456,

  "lon": 123456,

  "action": [ ],

  "dimension": 3,

  "object": {
                "baseURL": "http:\/\/custom.layar.nl\/",
                "full": "3dobject_full.l3d",
                "reduced": "3dobject_reduced.l3d",
                "icon": "icon.png",
                "size": 120
                },
  "transform": {
                "rel": true,
                "angle": 0,
                "scale": 5
               }

}

 

In Developer API v3.0, we introduced 2d and 3d objects in 3d space. The intention of using 2d and 3d objects in layar is to provide users the same realistic experience in Layar camera view as in real world. 2d images represent billboard, while 3d models can be used to represent real objects such as sculptures.

 In order to provide good and realistic user experience, please follow the guidelines provided as below:

 

 

Since a 2d/3d object can be represented by full/reduced/icon parameters, which parameter should be picked up is determined by the object projection on the phone screen (rendered object). Actually another very important factor is the memory usage which is related to the response time while loading objects.

 

In general, the following factors will influence the rendered size of the 2d/3d objects on the phone screen:

 

Layar Client Behavior:

 

 

          If 'object' dictionary is defined for this POI, only the image defined for the 'icon' parameter of the 'object' is used. Other parameters in 'object' and 'transform' will be ignored. This allows developers to specify a different icon for each POI, not having to use custom CIWs defined under "Look & feel" tab of the layer editing page in the publishing site.

          If 'icon' parameter in 'object' is not defined, CIW is the fallback. CIW as fallback means: custom CIW if defined (and available) or default 1d circle as last resort.

 

         The icon scaling in the camera view follows these rules:

 

 

  

          In order to 'predict' the rendered size of the object, the 'size' and 'scale' parameters should be used. 'size' is an indication by the layer developer for the actual size of the  object. 'scale' is applied to the object 'size' value. Therefore the actual size of the object is 'size' x 'scale'. 

 

         For instance, I have an object with the following settings:

         For 2d object, such as billboard, you can imagine that at the distance of 1500m, there is a billboard which is 100m high (originally 50m, after applying the scale factor,     now it is 100m). On a typical device, the rendered size will be around 20 pixels high (only!).  By changing object size and object scale, the actual rendered object size can be different at the same distance.

       
         Normally 'full' and 'reduced' are used only to render the object. 
    • 'icon' is used as fallback if neither 'full' nor 'reduced' can be loaded. As a last resort, CIW is used. In both cases they are scaled as if it was a billboard with the right size, so it also scales down realistically down to minimum (10 px). CIW as fallback means: custom CIW if defined (and available) or default 1d circle as last resort.

 

NOTE:  The actual 2d image file size in pixels (for instance, the actual image file size is 128 x 128 pixels), can be used to influence the quality of the rendered 2d object on the phone screen.  For instance, for the 'full' object, 256 x 256 pixels, 'reduced' object, 128 x128 pixels and 32 x 32 pixels for the 'icon'.

 

 

 

 

          In order to 'predict' the rendered size of the object, the 'size' and 'scale' parameters should be used. 'size' is an indication by the layer developer for the actual size of the object. 'scale' is applied to the object 'size'. Therefore the actual size of the object is 'size' x 'scale'. 

 

          For instance, I have an object with the following settings:

          For 3d object, such as a cube, you can imagine that at the distance of 1500m, there is a cube which is 100m in height, width and depth. On a typical device, the calculated rendered size will be around 20 pixels high. This calculated rendered size will be used to determine which object ('full'/'reduced'/'icon') will be picked up.

 

          Here we use 'full', 'reduced' and 'icon':

 

          NOTE:  For 3d objects, the actual size of the object is embedded in the 3D model file (1 unit is 1 meter). The object 'size' parameter in the response should reflect the real size of the model, but it is just used for the selecting of the 'full'/'reduced'/'icon'.  Once the client determines which object to render, during the actual rendering, the embedded size is used with the scaling applied.  For instance, in our previous example, the object size is 50m, while the 3D model is a shape of 50mX40mX30m. In that case with the scale it becomes an object of 100mX80mX60m. This value will be used during the actual rendering on the client. 

 

5. The maximum number of returned POIs
There are actually 2 maximums we need to consider:

- Threshold number of POIs received after which the client will not request a new page (if there still are more pages in the JSON response, morePages=true). This should be 50.

- Maximum number of POIs the client will render, i.e. it will discard POIs from the last JSON response. This should also be 50.

 

So for example:

- A POI provider returns multiple pages, each page has 15 POIs. Client will fetch 4 pages: 15, 30, 45, 60. It will not fetch another page because the number of POIs is > 50 and it will render only the first 5 POIs from the last page.

- A POI provider returns one page containing 80 POIs. Client will render the first 50 POIs of response and discard the last 30.

 

6. Navigation in Layar client

  

In Layar client 5.0, we introduce a new user interface which has designed to promote the visibility of layers and encourage user retention.   

 

Before we started explaining the new navigation, lets review the following definitions in getPOIs request:

 

Parameter Format Example Explanation Introduced API version

countryCode

(mandatory)

 string

countryCode=NL

 

list of country code can be found here.

This is the home country of the user, as determined by the network provider of the SIM card in the phone. If this is not available (e.g. iPhone or no SIM card inserted), it will return the locale value set on the phone.

 

NOTE: If you have development mode on, the country setting in developer settings will overrule the values from SIM card and Locale setting.		 v2.1

localCountryCode

(optional)

 string localCountryCode=JP

country code for the current country the device is located in, based on the country of the current mobile network provider the user is roaming in. If not available (e.g iPhone

In Layar client 5.0, we introduce a new user interface which has designed to promote the visibility of layers and encourage user retention.   

 

Before we started explaining the new navigation, lets review the following definitions in getPOIs request:

 

or no SIM card), the app will try to determine the current country based on the GPS location (reverse geo-coding lookup). However this may be unsuccessful and therefore incorrect.

 v3.0

 

 

  1. Layers Tab

 

 

 

 

     Client Specification:

 

 

 

Client Specification:

 

 

 

     1) Nearby Tab

 

     2) Country Tab

 

     3) Worldwide Tab