Some small changes to the Layar API in preparation for Layar Stream
Today we’ve updated our API in preparation for Layar Stream. The update is for the GetPointsOfInterest request/response and was documented on our wiki earlier today. In this post, I’ll explain in a bit more detail the reasoning behind the changes and how you can use them.
1. Switch off indexing for Layar Stream on POI level
The new parameter
doNotIndex can be added to your response for each POI to indicate to the Layar Stream engine that it should not be indexed. When our engine sees this parameter set for a POI, it will just ignore the POI.You should use this if there are specific POIs in your layer that you don’t want to have indexed. Remember that you can switch off indexing for your layer all together in the Inventory Management tab under your account. Examples where you might want to avoid indexing of a POI are:
- POIs in a gaming layer that contain clues that only should show up under certain circumstances, e.g when a user unlocked it
- POIs that are dynamically placed near a user because they contain actions for the layer, like a POI for placing an easter egg. The actual easter eggs would be indexed, not the ‘helper’ POIs.
- POIs that form part of a greater chain of POIs that don’t make sense on their own. Large geographical 3D objects in certain layers are formed by multiple POIs, like the Berlin Wall layer.
- POIs that can only be seen by the user when he logged in. Note that for layers that have the authentication required set to true, the POIs are not indexed anyway.
2. Identify the POI that triggers a getPOI request and mark it in the response
The new parameter
requestedPoiId in the request, together with the new parameter inFocus in the response permit the layer developer to make sure the POI the user is actually interested in remains in focus when the layer is opened in the AR view.When a user sees a POI in Layar Stream, selects it and decides to open the actual layer which generated the POI, he would certainly like to still see the POI once the AR view is rendered. Whilst there is no guarantee that the POI is still there, I’d like to urge you to try to include the requested POI in the response, even if the current request parameters wouldn’t return the POI in the first place.
So if you see a ‘requestedPoiId’ in the request, make an extra request to your database to include this particular POI in the response, and mark it in your response with ‘inFocus’ set to true.
3. Extra parameters identifying the client
We’ve added two parameters that will help you identifying the client that’s making the request:
- User-Agent: We now include the User-Agent string in the HTTP headers, which will tell you what Layar version on which device the user is actually using. The string has 3 parts:
- “Layar/x.y” tells you which version of the Layar app the client is running;
- “<deviceOS>/x.y” tells you what OS and which version of it is running on the device;
- “(<brand> <model>) tells you the actual brand and model of the device.
Now, <brand> and <model> tend to be pretty messy on a lot of devices, so don’t expect to recognize them all. We’re just passing what the manufacturer states here. Don’t blame the messenger…. ;-)Also, we only introduced this string in more recent versions of our apps, so you still won’t always see it.
- version: This is the API version that the client is using. All versions of our app pass this, but we were a bit sloppy in the past, so we were passing app version rather than API version. You’ll see strings like “ip2.1” (iPhone 2.1) and “2.0.2”. In the latest versions, all apps pass the actual API version, so you’ll see “3.0”, “3.1” and “3.5” both for Android and iPhone apps.
Make sure you understand the new API params and start using them! Let us know if you have any questions.
>> Visit the wiki page to see the technical details of these changes.
