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.

NOTE:

• It may happen that the user enters a region that by chance is covered by 2 auto-triggered actions from two POIs. Only the closest POI is triggered in such case.  
• An action should be triggered only when the location changes from outside to inside the trigger area. If an action was already triggered, it does not get triggered repeatedly when the user stays inside the trigger area.
• External applications can not be triggered automatically (using custom URL schemes).  
  

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:

• Title: Automatic actions
• Option: Show trigger alers on/off (by default: off)
• Explanation: Certain objects in the camera view can automatically trigger actions when you are close by, like open a web page, play a sound or play a video.

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:

• Title: Title of the POI
• Text: You've reached an object that wants to [open a website | play a sound | play a movie | launch an action] depending on the action content-type.
• Two buttons: Launch + Don't Launch

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 custom CIW focus is present, this is displayed as the focus POI.
• When a custom CIW inner is present, this is displayed as non-focus POI. Please NOTE that CIW middle and outer icons are not used.

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

• When a custom CIW focus is not present for this POI, the system uses the BiwBgColor for the default icon (the circle).
• When a custom CIW inner is not present for this POI, the system uses the innerColor for all non-focus default icons (the circles). 

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.   

Layar Client behavior:

4. Rendering POIs in the Camera view

Background Information:

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:

• Provide different models for "full", "reduced" and "icon". Please make sure that all these three fields are filled in with right models. Memory usage is sometimes an issue when loading large object files, therefore, providing less detailed representations for the same object is highly recommended for good user experience.
• The three models in "full", "reduced" and "icon" should represent the same object, while the only difference is level of detail. The "full" model should be the most complex one and user can enjoy the model when user is close by. On the other hand,  "icon" is an image representation of the object with low resolution which will be shown when the object is far away. User only needs to know what he /she can expect when the object is close enough.  

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:

• object size: The size of an object in meters.
• object scale: The scale factor applied to the object size parameter.
• distance: between the object and the phone.

Layar Client Behavior:

• POI dimension = 1,  POI icon is considered as a 1d circle. 

          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:

• The icon is rendered on a 1x1 meter quad in the OpenGL world 
• At 50 meter distance, the maximum icon size is shown, which appears as a 16x16 billboard
• scale = 16
• From 0-50 meters distance, the scale is adjusted to make the icon not appear larger on screen
• scale = 16 * poi.distance/50
• At the end of the range, the size of the icon is 25% of the maximum size (at 50 meter).
• scale = range/12.5
• Between 50 meters and the end of the range, the scale is interpolated
• scale = 16 + (range/12.5 - 16) * (poi.distance - 50) / (range - 50)

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

• object size: 50
• object scale: 2
• distance: 1500

          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.

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:

1. Layers Tab
   

•  New List

     Client Specification:

• Under the Layers tab, there is a New section. 
  

• Upon clicking on the New section of Layers, the user is taken to a Catalogue View.

• The New List contains all Layers within your current country if available (localCountryCode), your Home Country (countryCode), and International Layers. The intent is to display layers most relevant to that user. As some locations contain few layers and/or rarely updated, this combination is important. 

• The New List is sorted by initial publication date. Initial publication date is the date that a layer was *FIRST* published.

•      Featured List

Client Specification:

• Upon selecting Featured from the main "Layers" Menu, the user lands at the Featured List screen.

• The Featured List contains Layers that are marked as Featured by the Layar Content Manager for the user's home country (countryCode).

• The Featured List is sorted by the order in which the Layar Content Manager ordered them.

• Popular Lists

     1) Nearby Tab

• Upon selecting Popular from the main "Layers" tab, the user lands a the Popular screen.

• The initial screen on Popular is Nearby.

• Layers returned:

• Layers that have been indexed at the location of the user (your layer must have indexing enabled in the Layar Stream options to appear here)
  

• and layers which have their bounding box set at the location of the user.

• Layers are sorted by popularity, where popularity is based on the number of views of a layer.
  

     2) Country Tab

• Within the Popular Screen, the user can select <Country> tab, where <Country> is the country where the user is currently located (localCountryCode). If the current country cannot be detected, the home country of the user is used (countryCode).
  

• Layers are sorted by popularity, where popularity is based on the number of views of a layer.

     3) Worldwide Tab 

• Within the Popular Screen, the user can select the Worldwide tab.

• Layers returned within this tab are international layers.
  

• Layers are sorted by popularity, where popularity is based on the number of views of a layer.