Layar Developer Documentation

Back to layar.com

Edit a Layer

In the previous Register a layer section, we came across several mandatory fields that are needed in layer creation. In this section, we will have a look at the rest fields and how to customize a layer using these fields.

To edit a layer (we will take layer "firsttutorialxuan" with Layar Vision enabled as an example), click on "Edit" button for this layer to open the layer editing page (see screenshot below).

In total, there are 8 tabs:

General tab

In screenshot below, basic information about this layer is provided, such as layer status and layer developer / publisher emails. Again, layer type can be changed here. NOTE that Once Layar Vision is enabled, this will also change the Layer type to 3D and 2D objects in 3D spaces and the Minimum API version to version 6.0 automatically after the settings are saved.

API endpoint tab

As we can see that API endpoint URL (which was defined when this layer was created) can be modified here.

Since Layar client 5.0 release, it is possible for users to upload screenshots taken from the camera view directly to layer developer's web server. This can be defined under Hosted screenshots section. The detailed description of each field can be found below:

Fields Required/Default Definition
URL to post screenshots to Optional (mandatory when this function is used) The URL of your website where end users can post screenshots to. If this is filled out, and a user selects to share a screenshot with this option, an HTTP post (encoded as multipart/form-data) will be sent to this URL containing parameters:
  • screenshot: the image
  • layer_name: the name of the layer
  • message: a message from the user
  • lat: latitude of the user
  • lon: longitude of the user
  • location_name: friendly location name
Button text  Optional (mandatory when this function is used) The text shown when the user chooses to share the screenshot. 

For more information on how to implement this sharing feature, please read the "share a screenshot to a developer defined URL" section on Howto-sharing a screenshot to a developer defined URL .

If you want to check genuine requests from layar, OAuth signature can be used. Detailed definition for OAuth signing is provided in the following table:

Fields Required/Default
Value
Definition
OAuth signing requried Optional/false Whether or not the Layar Server should sign requests using OAuth signing
OAuth consumer key Optional (mandatory when OAuth signing is required) The OAuth Consumer key to be used when signing
OAuth consumer secret Optional (mandatory when OAuth signing is required) The OAuth Consumer secret to be used when signing

Listing & indexing tab

As we can see that "Title" and "Short description" fields (which were defined when this layer was created) can be modified here.

Fields Required/
Default Value
Definition Tooltips
layer icon high-res icon is mandatory(while requesting for publication) The icon to be used in the list of layers in the Layer Gallery. It is possible to have this icon (in PNG format) in different resolutions, high-res (128X128), medium-res (96X96) and low-res (64X64).
  • The medium-res and low-res icons can be generated automatically based on the high-res icon.
  • Please refrain from using corner effects and/or rounded corners. A mask with 4px radius rounded corners will be applied automatically.
layer Screenshot Optional A screenshot which will be shown below the detail description text on layer listing page. size 480x320 px
 Category Mandatory(while requesting for publication) A list of categories that a layer belong to.  Please assign your layer to the right category. This will make sure that users can find your layers using Categories section in Layar app on the phone. 
Detail description Mandatory(while requesting for publication) Some text that will further describe what this layer is about and how to use it and where hotspots are located, etc.
  • Goal of your layer, e.g. find the nearest restaurant, play a game and win or City guide
  • Location of the Spots, e.g. Amsterdam only, New York, Alps, Scandinavia, Santa Barbara university campus, all over the world, etc.
  • If your data source is user generated, please mention this. E.g. "This data is taken from www.worldpeaks.org. You can add mountain peaks on this site.
  • If your layer is temporary (e.g. for the duration of a festival) please inform the user.
  • Please mention it if users interact with your layer (e.g. submit Spots, give a Spots a rating).
Tags Mandatory/at least 1 tag A list of words describing the layer. A maximum of 15 words is supported. Note that the words in the layer title and publisher name are automatically added to the tag list.
  • Try to come up with the right keywords that can cover the content of your layer. Therefore your target audience should be able to find your layer easily.
  • Add keywords in English for foreign users if your layer is also useful to them.

To get an idea on how these fields fit in layar application on the phone, please see the screenshot below:

Fields Required/
DefaultValue
Definition Tooltips
Minimum API version Mandatory / version 3.0 The earliest API version that supports all the required features in your layer. This ensures your layer will be found and working well on Layar clients that have the same or newer version. For instance, if your layer relies heavily on POI actions using asynchronous requests with your server, the minimum API version should be v4.0. Your layer will be shown on Layar clients which support API version 4.0 or above. NOTE: if Layar Vision is enabled, the minimum API version should be 6.0. Please note that backward compatibility is best effort: The layar server will remove fields that are not defined/supported from the response, which may lead to unintended behaviour on older clients.

Look & Feel

Fields Required/Default
Value
Definition Tooltips
 Banner Icon Required (High-res icon) The icon (in PNG format) to use in the banner for branding the layer. The high-res icon is required. The high-res icon will also generate a scaled down version of medium-res and low-res. Optionally, you can upload your own medium-res and low-res icons.
color fields Optional All color fields that will affect the layer appearance in Camera view (see screenshot below)
Note: Outer and Middle colors are DEPRECATED in Layar v8.0, we'll remove this soon.
Test them on the phone to see whether they look nice.

By default, hotspots in camera view are represented by black disks. Instead of this default disk shape, developers are able to specify custom CIWs.

Each CIW set has four states:

  - Focus: when it is selected
  - Inner: when it is located in the inner (closest) ring of the radar
  - Middle: DEPRECATED in Layar v8.0, will be removed soon
  - Outer: DEPRECATED in Layar v8.0, will be removed soon

The custom CIW object is returned as:

Fields Value Required/Default
Value
Explanation
POI Type Integer (1..3) Optional/Empty An integer identifying the POI type. When the client needs to display a POI with this type, it will use the custom icons defined with this CIW.
Focus PNG Optional/Empty The icon for the focus state. 110x110 pixels. If you leave empty, the client will display the standard colored disk.
Inner PNG Optional/Empty The icon for the inner, unfocused state. 110x110 pixels. If you leave empty, the client will display the standard colored disk. 
Middle PNG Optional/Empty DEPRECATED in Layar v8.0
Outer PNG Optional/Empty DEPRECATED in Layar v8.0

Instructions for making a good custom CIW:

Your icon should be build in the following way in order to stand out regardless of the background the camera is pointing at:

Some guidelines:

The following screenshot shows how these fields are applied in Layar application on the phone.

Coverage

Fields Required/
DefaultValue
Definition Tooltips
Countries Mandatory (while requesting for publication) The country for which the layer is relevant, ISO format.
  • Select the countries in which the Spots of your layer are located. You can select multiple countries, up to a maximum of 20.
  • Country code 'international' can only be used for layers that have user-generated input and can thus contain Spots anywhere (e.g. Flickr, Twitter or Foursquare) or for layers that have Spots in more than 20 countries.
Bounding Boxes Optional/Empty The layer should be made "local" if all (or most of) its Spots are clustered in one city/region. You can make your layer local by defining one or more bounding boxes. This will make your layer more visible to users because it shows up in the nearby tab of the client if a user is in this particular area
  • Zoom in until the map border becomes green, you can then left click on the map to add a bounding box.
  • Each bounding box has a geo-coordinates representation. Move mouse to a blue geo-coordinates set, the corresponding bounding box will be zoomed to an editable level on the map.
  • Do not make your bounding boxes too large. Users should be able to find your Spots from anywhere within the area covered by the bounding boxes.
  • The number of bounding boxes is limited to 20.

Filters

There are five different filters that can be associated with each layer. The values of each filter will be sent in the request for hotspots. They are all optional. The screenshot below shows two of the filters (Range Slider and Textbox).

The detailed definition of each filter is listed below:

Fields Required/Default
Value
Example Explanation
Label Mandatory "Search terms" The label to be displayed in the filter settings view
Default value Optional / Empty "" Default value to display and use in the search box
Fields Required/Default
Value
Value Example Explanation
Label Mandatory String "Max price" The label to be displayed on top of the slider
Label Unit Mandatory String "\u20ac" The unit to be associated with the label, unicode supported (here e.g. €)
Max value Mandatory / 0 Integer 2000000 The maximum value of the slider
Min value Mandatory / 0 Integer 10000 The minimum value of the slider
Default value Mandatory / 0 Integer 500000 The default value of the slider
Fields Required/Default
Value
Value Example Explanation
Label Mandatory String "Max price"              The label to be displayed on top of the slider
Label Unit Mandatory String "\u20ac" The unit to be associated with the label, unicode supported (here e.g. €)
Max value Mandatory / 0 Integer 2000000 The maximum value of the slider
Min value Mandatory / 0 Integer 10000 The minimum value of the slider
Default value Mandatory / 0 Integer 500000 The default value of the slider
Fields Required/Default
Value
Value Example Explanation
label Mandatory / Empty String "Choose industry" The label to be displayed above the radio list

options:

Value

Mandatory / Empty

Array of Strings ["1000", "1001", "1002"] These are the internal values used to define the various options. This value is passed as parameter in the query for the POI's.

options:

Display Text

Mandatory / Empty Array of Strings ["all industries", "administrative", "commercial"] The are the values shown to the user, each corresponding to one option value.

options:

Default

Mandatory / Empty String "1000" The value that is selected by default
Fields Required/Default
Value
Value Example Explanation
label Mandatory / Empty String "Choose industry" The label to be displayed above the radio list

options:

Value

Mandatory / Empty

Array of Strings ["1000", "1001", "1002"] These are the internal values used to define the various options. This value is passed as parameter in the query for the POI's.

options:

Display Text

Mandatory / Empty Array of Strings ["all industries", "administrative", "commercial"] The are the values shown to the user, each corresponding to one option value.

options:

Default

Mandatory / Empty Array of Strings ["1000", "1001"] The values that ares selected by default

All these filter settings will appear in the layer settings page in Layar application on the phone. If "Show filters before loading layer" is checked, this layer settings page will always appear before camera view is shown. The following image shows how these filters look like on Layar client.

Permissions

Under "Permissions" tab, publisher name which was defined while layer creation can be edited. At the same time, the ownership of a layer can be transferred from current publisher to another publisher. Developer can also add a viewer for a layer so that this viewer can see this layer on Layar client even it is still in development.

By default, the layer developer is also the publisher of this layer. The ownership of this layer can be transferred to another publisher by following the steps below:

  1. Click on "Assign new publisher" button.
  2. Fill in the email address of this new publisher.
  3. An email is sent to this email address to notify this publisher on his role and assignment. Meanwhile, it explains what this publisher needs to do in order to see this layer in the publishing site environment.

By adding viewers to a layer, other people can see this layer on Layar client even it is not in public status. This is especially useful when you want to show it to other people, such as project clients. To Add a viewer:

  1. Click on "Add viewer" button.
  2. Fill in the email address of this viewer.
  3. An email is sent to this viewer to notify him/her on this assignment.
  4. If this viewer already has a Layar account (with the same email address), he/she can directly start viewing your layer on Layar client after logging in.
  5. If not, he will then need to create a Layar account on layar website (www.layar.com) first in order to see this layer on layar client.

Reference images

For Vision enabled layers, reference images can be uploaded and maintained here.

For the uploaded reference image, the following information needs to be provided:

FieldsDescriptionRequirement (Best Practices)
ImageThe image itself that is uploaded from your computerImage resolution must be at least 640 x 480 pixels, though larger images are accepted and encouraged. Supported file types include .JPG, .PNG, and .GIF. File size may not exceed 10MB.
Image keyThe key that is used to identify a reference image. It is the value of "referenceImage" defined in "anchor" object of a POI in getPOI response.The image key is a quick way to identify your images. It has to be unique for a layer. We recommend using a personalized, easily remembered key.
NOTE: After you create an Image Key, the image will be processed by our server and you will not be able to edit it. To change the image or its key, you must delete the original and upload a replacement.
Real World HeightHow high is your image in the real world in meters?Fill in the real height of the target object that you want to augment. This determines how the unit length of the coordinate system is scaled with respect to the target object. So it will determine the size of the augment with respect to the target object and the lengths when "transform" or "animation" are applied to the augment.

Once a reference image is uploaded, the legend below is used to show ratings assigned by Layar server based on the quality and clarity of images and their ability to be used for Layar Vision.

Additional Settings

Under this tab, some more layer level settings can be configured to support complex mechanisms in a layer.

Explanations for each field can be found in the table below:

Key

Required/Default
Value

Example

Explanation

Show 'Take me there' Optional / true checked or unchecked If it is checked (true), a "take me there" button will be shown as an action in the Spots Detailed BIW. This button will launch Google Maps, which shows the Spots location on the map. If it is not checked (false), this button is not shown.  This option is based on a layer level.
Enable additional settings Optional / false checked or unchecked If checked (true), the additional layer settings listed below will be enabled

valid cookie required

Optional / false

false (by default)

Indicates whether valid cookie(s) is required prior to launching the layer. If it is checked (true), the Client will firstly check whether there is a cookie, if not, it will redirect the user to the page defined in "URL for layer settings page".

URL for layer settings page Required when 'Enable additional settings' is checked https://m.hyves.nl/layar/signin The URL to call for the webview to authenticate the user. Usually https. NOTE that this URL needs to be on the same domain as the poiURL (it's just a cookie we're using, so all normal browser cookie rules apply), different sub domains are allowed.

Description for button

Required when 'Enable additional settings' is checked User Authentication A description is shown on top of the button which explains what this button is about.

Button label

Required when 'Enable additional settings' is checked login The text that is displayed on the button itself.
Replace filters Optional / false unchecked Indicates whether the web page launched by 'URL for layer settings page' will replace the entire filter settings defined under "Filters" tab. If it is checked (true), the web page content will appear under the filter settings button in the camera view. By default, it is unchecked (false).
Parameters added in request Optional / Empty https://custom.layar.nl/login.php?
lon=4.933156943889342&
lat=52.373196116536235
A group of preset parameters that can be added to the request when the button is clicked. The possible multiple values are "latitude", "longitude", "country code", "accuracy", "language", "API version".

The button which has these additional settings enabled can be found on the layer filter settings page in Camera view on layar client.

This is the end of layer editing section. Please do not forget to save changes made to layer editing. You will probably come back to this section from time to time to configure the best options for your layer.