GLUE Quickstart: Hello GLUE!

Scan this marker with
junaio to see what you are
getting in this tutorial.

Additional Links

What should you have done by now?

: Augmented metaio man

: Popup on click

You should know where you want to upload your channel files to. You will need a web host that supports PHP. You could use servers supporting other languages such as ASP .NET as well, but the quick starts are written in PHP. Most of the server spaces you can rent or sign up to work well with junaio.
You should install a nice development environment. Eclipse is a nice-to-have environment with the PDT (PHP Development Tool) installed (Download from Eclipse).
It helps to have a local apache running (e.g. XAMPP) to test things quickly
And you should of course have a Developer Account (Sign Up here) and your API Key (click "Show My API Key") at hand.
Download the Getting Started Package for PHP

What will you learn?

Scan the QR Code on the right with junaio to see what you are getting.

How to set up your server to host your own junaio channel
How junaio Authentication works
How the pois/search request works
Creating your first GLUE POI
Creating a trackingXML (information about the reference image)
Link a phone number and website to your POI
Troubleshooting your channel/server if something does not work as planned

Downloads

junaio Getting Started Package
Eclipse Download Page
Hello GLUE - Tutorial .zip (Note: this is shortened a little, returning the information directly in the index.html)

Reference Images used

Get started

The Getting Started Package you have just downloaded will help you provide correct information to junaio. This package will be uploaded to your server and the callback URL of your channel will have to point to the index.php in the html folder of the package. So let's see what happens if a user opens your channel (a POIs/search request to your channel)

When you have a look at the index.php you will first see the authentication process. This allows your server to check, whether the junaio server is asking for information, or somebody you might not want to allow access.

// Check junaio authentication header
// Settings for the authentication can be found in config.php
if (!Junaio::checkAuthentication()) {
		header('HTTP/1.0 401 Unauthorized');
		exit;
}

In order to do this, you need to fill in your API key in the config.php in the config folder of the Getting Started Package:

define('JUNAIO_KEY', 'Your_API_KEY_HERE'); // Junaio developer key

Once the request has passed the authentication, it is determined, whether this is a pois/search or a pois/event call to your server. Based on the request sent either the event.php for a pois/event request or the search.php for a pois/search request will be included.

Currently, there are no events, so let's just comment out the event include line.

//.htaccess rewrite enabled:
//Callback URL: http://www.callbackURL.com
//
//.htacces disabled, please use:
//Callback URL: http://www.callbackURL.com/index.php?path=
 
if(isset($_GET['path']))
	$path = $_GET['path'];
else
	$path = $_SERVER['REQUEST_URI'];
	
$aUrl = explode('/', $path);
if(in_array('pois', $aUrl))
{
	if(in_array_substr('event', $aUrl))
	{
		//include '../src/event.php';
		exit;
	}
	else if(in_array_substr('search', $aUrl))
	{
		include '../src/search.php';
		exit;
	}
}

We will have a look at the search.php next, where the information to be returned to junaio is gathered. For this tutorial, adjust the information like this (Please make sure to remove tags you do not need from the default output):

echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
	<results trackingurl=\"http://www.junaio.com/publisherDownload/tutorial/tracking_tutorial.xml_enc\">
		<poi id=\"1\" cosid=\"1\" interactionfeedback=\"none\">
		<name><![CDATA[metaio Man]]></name>
		<translation>0.0,0.0,0.0</translation>
		<o>1.57,0,1.57</o>
		<mime-type>model/md2</mime-type>
		<description><![CDATA[This could be a model of your hotel on your flyer?! Or just the metaio man :D]]></description>
		<mainresource><![CDATA[http://www.junaio.com/publisherDownload/tutorial/metaioman.md2_enc]]></mainresource>
		<thumbnail>http://www.junaio.com/publisherDownload/tutorial/thumb.jpg</thumbnail>
		<s>1</s>
		<resources>
			<resource>http://www.junaio.com/publisherDownload/tutorial/metaioman.png</resource>
		</resources> 
		<phone>555/1234567</phone> 
		<homepage> http://www.hotelaroundthecorner.com </homepage>        
		</poi>
	</results>";

: Tracking File Creator

In your <result> - tag there is a trackingXML referenced. The trackingXML tells junaio what to do. In case of a GLUE channel, it tells junaio which images to look out for to overlay your specific information onto (each poi has a cosid, stating the image ID it is assigned to). TrackingXMLs of your reference images can be created here (you need to be logged in as a developer).
ATTENTION: Please read the information on pattern creation carefully, since inapplicable reference images are the most common issue for unsatisfactory results.

: Online Model Encrypter

Based on the mime-type, junaio will know what type of POI you have defined to render it correctly.
Please understand that you have to use a 3D model with junaio GLUE. The 3D model is referenced with the mainresource (3D Model) and resource (texture). To reference the 3D model, it needs be encrypted, which can be done with the online Model Encrypter.

Update: Since junaio 3.1 (apilevel 3), you can also zip the unencrypted md2 model (also with it's texture if liked) or use an unencrypted md2 and reference this in the mainresource. This is especially senseful, if you do not need to encrypt your model and work with bigger or a lot of models to reduce data to be downloaded.

Have a look at junaio's specification for 3D models, to learn how to use obj models with junaio and where are the differences. Generally obj models need to be zipped with all required information (mtl, textures). The zip archive is then referenced in the mainresource (no resource required). Only the obj can be encrypted.
Additionally, there is a phone number and a homepage given. Those will be represented as buttons in your pop up, once the POI was clicked. Be aware that they are just made up and will not work. An overview of all parameters usable in your XML return can be found here.

: Create a new Channel with Type "junaio GLUE Channel"

The information to be returned for the "Hello GLUE" - Tutorial is completely defined. You just need to upload all files and folders to your server and create a new channel with the Callback URL pointing to the html folder on your server.
Note that the channel is defined as a junaio GLUE Channel.

Next, press the validate button to get some first information on your channel's correctness.

If your channel passes all tests without errors (warnings are to be considered as hints for you. So they will most likely not affect the functionality of your channel, but you can double check whether this is intended), you can open your channel on your device and test it there.
If there are some errors showing up, please have a look at Trouble Shooting "Hello GLUE".

With Helper Library

Junaio also provides some Helper Libraries, you are encouraged to use. The Helper Libraries provide a set of methods that avoid errors when creating the xml output yourself. The "Hello GLUE" - Tutorial looks like this (without homepage and phone number - it's just to familiarize you with the structure), with the PHP Helper Library.

Note the "\n" -> a new line character in order to get the line break in the description.

//use the poiBuilder class
$jPoiBuilder = new JunaioBuilder();

//create the xml start and activate output buffer
$jPoiBuilder->start("http://www.junaio.com/publisherDownload/tutorial/tracking_tutorial.xml_enc");

//create a basic location based POI
$poi = $jPoiBuilder->createBasicGluePOI (
"metaio Man", //name
	"0,0,0",  //translation
	"http://www.junaio.com/publisherDownload/tutorial/metaioman.md2_enc", //mainresource (model)
	"http://www.junaio.com/publisherDownload/tutorial/metaioman.png", //resource (texture)
	1, //scale
	1, //cos ID -> which reference the POI is assigned to
	"This could be a model of your hotel on your flyer?! Or just the metaio man :D", //description
	"http://www.junaio.com/publisherDownload/tutorial/thumb.jpg", //thumbnail
	"metaioman1", //id
	"1.57,0,1.57" //orientation
);

//echo the POI
$jPoiBuilder->outputPOI($poi); 

//create the end and end output buffer
$jPoiBuilder->end();

Trouble Shooting "Hello GLUE"

If the validation shows any errors, the next lines will most likely help you resolve the issues. Please keep in mind that warnings do not mean they will effect the functionality of your channel. It's more that you should have a look at them in order to make sure that this is intended (e.g. no return on certain calls).

Failure of Validation Test 1 - Check Callback URL

Error Code 404

Double check whether the underscore of _.htaccess has been removed, leaving .htaccess on your server.
Make sure your URL really is available by typing in the URL in your browser. If your browser shows a page not found or similar, please correct your Callback URL. A blank page is usually a good sign.
Perhaps your server does not support mod_rewrite. Please add at the end of your Callback URL "?path=". For more information, look at the Readme.pdf in your Getting Started Package.

Error Code 500

There is most likely a php error in your script. It is best to check your script locally first using a local server setup (e.g. xampp - a package with apache, mysql and some more).

Either on your server or locally, to make sure to see the php errors and warning, do the following temporary adjustments to your script:

If available, set the DEBUG Variable to true in the config.php, if not, please add the following lines to your index.php. This will show all warning and errors coming from php and makes sure they are not supressed by your server (if possible on your server)

error_reporting(E_ALL);
ini_set('display_errors', '1');

You can then validate your channel again and in Test 2 click "Show Request Response" to look for php errors or warnings. You can also copy and paste the request URL of Test 1 in your browser. Just make sure you have commented out the authentication in your index.php for the debugging process, so your channel does not return an unauthorized response.

Failure of Validation Test 2 - Check pois/search

For certain servers, this test will output an unauthorized error.

Make sure you have edited the config.php and added your correct API key. Your API key can be found here.
Certain servers will not forward the authorization header. If your server supports mod_rewrite, please add the folowing line to your .htaccess in the channel's html folder on your server.

RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

Make sure that your server time is correct. Requests to your server that are older than 15 minutes will be refused with unauthorized. You can extent that time period in your config.php.
Try to comment out the authorization on your server (line 13 - 16 of your index.php) and the require_once junaio.class.php statement (line 9 of your index.php). If the error still occurs, there is a server reason why HTTP Status Code 401 - Unauthorized is send. Please ask your administrator for more information.
If you pass this test now, please make sure, the AUTHORIZATION header (or HTTP_AUTHORIZATION or REDIRECT_HTTP_AUTHORIZATION) is allowed. Please ask your administrator for more information.

Note: It is not recommended to comment out the authorization for active channels, because there will be no authentication, that only junaio can access the channel information on your server.

Failure of Validation Test 3

Please read the error message of this step. Most common errors are:

There is an error in your XML. Please make sure you have followed the Tutorial closely.
There are additional characters at the end or the beginning of your XML output. Please make sure there are no additional characters there (also no spaces, newlines or similar).
Make sure the information provided within your output is UTF-8 encoded.

junaio