LBS Quickstart: Hello World!

What should you have done by now?

Georeferenced POI
Pop up after click
  1. 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.
  2. You should install a nice development environment. Eclipse is a nice-to-have environment with the PDT (PHP Development Tool) installed (Download from Eclipse).
  3. It helps to have a local apache running (e.g. XAMPP) to test things quickly
  4. And you should of course have a Developer Account (Sign Up here) and your API Key (click "Show My API Key") at hand.
  5. 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 geo location POI
  • Allow routing to your POI with Google Maps
  • Link a phone number and website to your POI
  • Troubleshooting your channel/server if something does not work as planned

Download

Get Started

  1. 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;
}

  1. 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

  1. 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;
	}
}

  1. 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 as shown next.

    Your first POI will be given a name, a description, an icon, thumbnail and a position. The position is defined as latitude, longitude, altitude. There may be no spaces in between and all values (lat,lng,alt) must be set. Be aware that this position in this example is somewhere in San Francisco. So adjust it to something close to you so you can actually see it. Based on the mime-type, junaio will know what type of POI you have defined to render it correctly. Additionally, there is a phone number and a homepage given. Those will be represented as buttons in the POI's 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.

echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<results>
   <poi id=\"1\" interactionfeedback=\"none\">
    <name><![CDATA[Hotel Hello World]]></name>    
    <description><![CDATA[This is a beautiful, family hotel and restaurant, just around the corner.
Special Dinner and Rooms available.]]></description> 
    <l> 37.776685,-122.422771,0</l>
    <o> 0,0,0</o>    
    <mime-type>text/plain</mime-type>    
    <icon>http://dev.junaio.com/publisherDownload/tutorial/icon_map.png</icon> 
<thumbnail>http://dev.junaio.com/publisherDownload/tutorial/thumb.jpg</thumbnail>
    <phone>555/1234567</phone> 
    <homepage> http://www.hotelaroundthecorner.com </homepage> 
	</poi>
</results>"
  1. There is one more parameter we want to define in this first "Hello World" – Tutorial. This will allow the user to route to the information using Google Maps from the description window.
<route>true</route>
IMG: Screenshot
  1. The return information for the "Hello World" – 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 Location Based Channel.
  2. After creating your channel, you are lead back to "My Channels". 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 World” further down.

Using the PHP 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 World" - Tutorial coding e.g. 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" in the description. It's 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();

//create a basic location based POI
$poi = $jPoiBuilder->createBasicLocationBasedPOI(
        "Hotel Hello World", //the name
        "37.776685,-122.422771,0", //the location
        "This is a beautiful, family hotel and restaurant, just around the corner.\nSpecial Dinner and Rooms available.", //the description
        "http://www.junaio.com/publisherDownload/tutorial/icon_map.png", //the icon
        "http://www.junaio.com/publisherDownload/tutorial/thumb.jpg", //thumbnail
        "1", //id 
        "true" //routing enabled
);

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

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

Trouble Shooting "Hello World"

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:

  1. 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');
  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.

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