API v7.1 Changes
NOTE: These are the changes in Developer API v7.1. It is supported in Layar client v7.1 (and above) on both Android and iPhone.
In Layar API v7.1 we introduced HTML widgets. This option allows you to add dynamic AR content to your vision layers. Using HTML, javascript, and CSS you now have the opportunity to create varying types of content.
Although the possibilities are only limited to coding language and client feasibility, we strongly advise you to think of user experience before creating your HTML content. Avoid placing complete websites on top of your images. Remember the screen size of mobile devices is small and any content you place in AR looks even smaller than when viewed full-screen. HTML widgets should be used to place little snippets of web content that can be dynamic and interactive. Some typical use cases are:
- Score boards
- Twitter feeds
- Slide shows
- Voting/polling mechanism
- Web widgets
New content type supported in object (hotspots.object)
New contentType text/html is used in order to represent HTML panels. An example response is shown bellow:
"object": {
"url": "http://example.com/~myfolder/page.html",
"contentType": "text/html",
"size": 1,
"viewport": {
"width": 200,
"height": 256,
"scrollable": false,
"interactive": true
}
}| url | string | The URL of the page that the viewport refers to is hosted |
|---|---|---|
| Mandatory/Optional: | mandatory | |
| Path: | root.hotspots.object | |
| Detailed Description: | 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 size of the widget |
|---|---|---|
| Mandatory/Optional: | mandatory | |
| Path: | root.hotspots.object | |
| Detailed Description: | 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. The image bellow shows the result if you set size value higher  | |
| viewport | Json dictionary | 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 | The width of the viewport |
| Path: | root.hotspots.object.viewport | |
| Description: | The width of the viewport in CSS pixels. | |
| height | pixels | The height of the viewport in pixels |
| Path: | root.hotspots.object.viewport | |
| Description: | the height of the viewport in CSS pixels. | |
| Scrollable | Boolean | 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 | 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 . | |
General Notes
- Since HTML widgets are part of the object, transforms and animations can be applied in the same way as for static images. More information on animation can be found in GetPois animation
- The web view panels should not intersect with any other objects. It is always shown on top of the OpenGL stack and therefore it is not possible to place it behind other objects.
- The background of a web page is rendered transparent if background color is set to transparent (in html or css). We recommend to set background color to transparent in CSS to avoid rendering issue on Android devices.
- Any link to another web page that the user clicks will open in a full screen, not in AR. If you want to make your HTML widget interactive in AR, you'll need to change the content in-place using javascript: Fetch the new content using XHR and modify your DOM-tree to replace specific elemenets (divs) with the new content.
Frequently asked questions
- What is the difference between size and width * Height of viewport?
The value of the size defines how big the HTML widget will appear in respect to the Page (first image). The width and height of the viewport define the portion of the webpage that will be shown in the viewport(second image).
image 1 - Setting viewport's width and height
image 2 - Enlarging view port size
- What is supported and what is not ?
Now, with the support of HTML widgets there are countless possibilities of what can be created. As already mentioned, these are only limited to coding language and client feasibility. In light of this it is not possible from our side to fully test and document everything that can be supported. There are also differences as to what iOS and Android support natively, therefore we urge you to test on both platforms.
Our tests so far indicate that the following are not supported:
- Flash content
- Embedded audio and video
- Forms with text input fields. Forms that use checkboxes, radio-buttons etc. should work.
- Web storage
- The canvas element
In general many of the new HTML 5 elements are not supported but it might be the case that few things may work. We are also curious as what works and does not. Please let us know! We will also update this topic in Customer Support environment so that you can see what works and does not. You are very welcome to share with us what you have created and tips & tricks!
- Will the content of my page refresh automatically?
The content of the pages does not refresh automatically within Layar. Please explicitly define that in your web page.
- So now I do not need a website button i can just display my web page on top of a Page ?
Please note that, although HTML widgets indeed allow you to display entire web pages in AR ,we strongly advice you not to do so, since this will just result in poor user experience. It should instead be used to place little snippets of web content that can be dynamic and interactive.