Creating a simple Layar with ColdFusion: a step by step tutorial

Posted At : 04 July 2010 15:22 | Posted By : Glyn Jackson
Related Categories: Layar, ColdFusion 8, ColdFusion

I have been doing a lot of mobile development recently. The jqtouch plugin for jquery is awesome by the way! If you have not had the delight of developing with it yet I highly recommend the plugin for you next mobile project.

Anyhow back to Layar, I was asked to produce a simple Layar for one of our clients. Layar if you don't know is a cool augmented reality browser for the iPhone and Android. Other phone operating systems have been announced and its set to come pre-installed on most phones by 2012.

Augmented reality is exploding in Europe and I really think it's the next big thing. Creating a Layar is supper easy but no tutorial seemed to exist showing how to create POI in ColdFusion so I decided to write a quick post from an asp.NET Layar I did a few weeks back.

Before you start...

Requirements

Webserver with ColdFusion 8 or Above (JSON support needed)
Android or iPhone 3GS or above (needs GPS and compass)
Gmail Account

You should know that a Layers consist of two parts:

Layer definition: Created using a web form on the Layar Publishing site. I will show you how to do that.<.p>

Points of Interest within a layer: Fetched directly from the Layer Service Provider via the API. We will do this in CF. I will show you a quick example of this here also

Step 1. Request a Developer key

First you will need to request a developer key from Layar. This key will allow you to gain access to the developers publishing site. If can take a few hours to a couple of days to get approval of a new key. Get you key go to: http://publishing.layar.com/publishing/requestaccount/

When you receive the welcome e-mail, log out of any Google account your are using (if you plan to use a different account to access the Layar Publishing site).

Click on the token you receive in the welcome mail and log in using your Google account. This will link your Google account to the Layar Publishing site and allow you to use your Google account as single sign-on account for Layar. Done.

Step 2: Your testing environment

Once you create a Layar you will need to test it. This can be done via the Layar Publishing site and your phone. It's real easy to test Layars on Android phones. In fact all you have to do in login to Layar Browser on your Android phone (download the app from the App Store search for 'layar') and view your test Layars.

For the iPhone you'll need an iPhone 3GS with iPhone OS 3.1 or higher. In the general Settings app of your iPhone, you will find the Layar settings. Here you can enter your developer ID and key to test your layers.

Step 3: Creating a Layar via Layar Publishing site

Once you have you key and your account is linked login at http://dev.layar.com with your Google account and then click 'Create Layer'. Fill out the form:

Read the info carefully as when you come to publish your Layar anything you have done wrong here could stop it from being approved. A general overview of what you need to fill-in is below.

1) Fill in your layer's name.
2) The type of layer you want to make. For now choose "Generic 2D". We will cover the "3D and 2D objects in 3D space another time".
3) Your POI's URL. This POI will need to point to your CFC and will provide POI for this example. How to create your POI will be covered in the next step.
4) Select in which countries your layer will be working.
5) Check the box if your layer is for non-commercial use only. This is for stats and we are told will not affect you Layar being published later on.
6) Enter your layer's title. Important lowercase. Get this wrong and your Layar won't be approved!
7) Fill in a short description of your layer. The Layar users will be able to see this description once you publish your layer.
8) Enter you own or your company's name.
9) Enter some tags that relate to your layer. When you Layar go live to the General public this is will users find your Layar.

After you are done click "Save and Customize", the following screen will appear. I am not going to go step by step on this but it's important you fill learn more about this at Layar.<.p>

Step 4: Creating the Layer Service Provider POI

The POIs are fetched directly from the Layer Service Provider (the POI URL you entered in step 3) by the Layar Server using the Layer Developer API. The calls are real-time, that is each time the client needs to fetch a new list of POIs, a call will be made by the Layer Server (on your site this case in ColdFusion) using the API.

For each POI, there maybe more detailed content to show, or interaction possible with the end-user. This can be achieved by hosting web pages (made for mobile) that will be shown within the Layar client app as web views when a user selects the POI. These pages are accessed directly by the Layar client over the Internet. I will NOT cover this in this tutorial or accessing your POI via a database but the principals are the same.

The Layar API currently accepts only JSON response format. In ColdFusion we known this simple. Below is a example of a call which I will explain more.

view plain print about

1<cfcomponent output="false" hint="GetPointsOfInterest">
2
3
4
5
6    <cffunction
7        name="GetPointsOfInterest"
8        access="remote"
9        returntype="struct"
10        returnformat="JSON"
11        output="false"
12        hint="This call is used to request the points of interest to be displayed for a particular layer">
13
14
15        
16        <cfargument name="userId"
17      hint="Unique ID of the end-user, anonymized"
18      required="yes"
19      type="string">
20
21      <cfargument name="developerId"
22      hint="Developer Id"
23      required="yes"
24      type="string">
25
26      <cfargument name="developerHash"
27      hint="This hash is passed in the request as a simple method to verify the authenticity of the request"
28      required="yes"
29      type="string">
30
31      <cfargument name="timestamp"
32      hint="Unique timestamp to hash the key timestamp=1242207092430"
33      required="yes"
34      type="numeric">
35
36      <cfargument name="layerName"
37      hint="Identifier of the layer"
38      required="yes"
39      type="string">
40
41      <cfargument name="lat"
42      hint="Latitude of current position (GPS coordinate)"
43      required="yes"
44      type="string">
45
46      <cfargument name="lon"
47      hint="Longitude of current position (GPS coordinate"
48      required="yes"
49      type="string">
50
51      <cfargument name="accuracy"
52      hint="Optional: the accuracy of the current location, as given by the device."
53      required="no"
54      type="numeric">
55
56      <cfargument name="radius"
57      hint="Optional: the optionid corresponding to the value of the radio button list option selected by the user"
58      required="no"
59      type="numeric">
60
61
62
63
64
65
66
67            <cfscript>
68            var response = StructNew();
69            var obj = {};
70            var objAct = {};
71            response['hotspots'] = [];
72
73
74
75
76            obj['distance'] = "5000";
77            obj['attribution'] ="This is a test layer";
78            obj['title']= "Where is Glyn?";
79            obj['lat']= "53.472668";
80            obj['lon']= "-2.261596";
81            obj['imageURL']= "http://www.gravatar.com/avatar/5951a17e5152bfdcd1e2e6612ea33d86?s=40&r=pg&d=http://www.cfcoffee.co.uk/images/gravatar.gif";
82            obj['line4']= "";
83            obj['line3']= "of course!";
84            obj['line2']= "I am here at Gencia";
85            obj['type']= "0";
86            obj['id']= "test_1";
87            obj['dimension']= "1";
88
89
90            obj['actions']= [];
91
92            objAct['uri'] = "http:www.cfcoffee.co.uk";
93            objAct['label'] = "Open my blog";
94
95
96            arrayAppend(obj['actions'],objAct);
97
98            objAct = {};
99
100            objAct['uri'] = "audio://www.yourbrandreality.co.uk/service/alarm_1.mp3";
101            objAct['label'] = "Play Sound";
102            objAct['autoTriggerRange'] = "25";
103            objAct['autoTriggerOnly'] = "false";
104
105            arrayAppend(obj['actions'],objAct);
106
107
108
109            arrayappend(response['hotspots'],obj);
110
111
112
113
114
115
116            response['layer'] = "genciamedialtd";
117            response['errorString']='ok';
118             response['morePages']='false';
119            response['errorCode']= '0';
120            response['nextPageKey']='null';
121
122            </cfscript>
123
124
125
126
127        
128        <cfreturn response />
129    </cffunction>
130
131
132</cfcomponent>

Title: the title of your POI
Lon: the longitude of your POI.
imageURL: link to a small picture of your object
line4: Fourth information line
line3: Third information line
line2: Second information line
lat: the latitude of your POI.

To test your service login and go to: http://publishing.layar.com/publishing/test/

Enhancements, whats next

keep in mind this is just a quick and dirty example to get you started.

POI, objects, actions pulled from a database: This is really what I should be doing but for the point of this quick tutorial it's not necessary and is easy to see how this could be done.

Security. Normally I would not accept any connections like this.

The developerKey is entered together with the developerId by the user in the corresponding settings field in the client. The hash is obtained in the following way:

Append the timestamp as a string to the developerKey
Make sure the string is encoded using ASCII
Calculate the SHA-1 hash of the so obtained string.

For example: developerKey=492ac3114, timestamp=1242207092843 Key to hash with SHA-1: 492ac31141242207092843.

developerHash: 9df7273b410761f74331bde746e5c2354b73b487

Issues I had!

I have issues preserving the case of the key. CFtalk was a big help. It was solved using the bracket structure syntax: i.e. response['hotspots'] = []; to preserve the case of the key. however I have an array I have tried adding the array different ways to the struct but it still comes out uppercase! To get around this I just used arrayappend and got rid.