Scan this marker with junaio to see what you are getting in this tutorial.
What should you have done by now?
- Georeferenced POI
- Pop up after 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).
- Download the quickstarts or check out from github.
What will you learn?
Scan the QR Code on the left with junaio to see what you are getting...
- How to set up your server to host your own junaio channel
- How the pois/search request works
- Creating your first geo location POI
- How to add links to the POI (e.g. website, phone, sms, etc)
- Troubleshooting your channel and server if something does not work as planned
Download
Get Started
The "Hello World" Example you have just downloaded is the most cut down information you can provide to still have a running channel. The callback URL of your channel will have to point to the index.php in the channel folder on your server. So let’s see what happens if a user opens your channel (this means you receive a pois/search request to your server)
When you have a look at the index.php you will see that the information for junaio is echoed as a regular XML. All necessary information is included in that XML.
Your first Object will be given a title, an icon, thumbnail and a location. The location is defined as latitude, longitude, altitude. Be aware that the location set in this example is somewhere in San Francisco. So adjust it to something close to you so you can actually see it. Additionally, there is a popup defined. You can assign a description to the popup as well as buttons. In this example we add a link to a website, but you can also link videos, sounds, images, to route, to call, write sms, etc. Please check this overview of protocols that are supported specific for mobile phones.
An overview of all parameters usable in your XML return can be found here.
echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?> <results> <object id=\"1\"> <title><![CDATA[Hotel Hello World]]></title> <thumbnail><![CDATA[http://dev.junaio.com/publisherDownload/thumb_a1.png]]></thumbnail> <icon><![CDATA[http://dev.junaio.com/publisherDownload/icon_a1.png]]></icon> <location> <lat>37.776685</lat> <lon>-122.422771</lon> <alt>0</alt> </location> <popup> <description><![CDATA[This is a beautiful, family hotel and restaurant, just around the corner. Special Dinner and Rooms available.]]></description> <buttons> <button id=\"url\" name=\"Website\"><![CDATA[http://www.junaio.com]]></button> </buttons> </popup> </object> </results>"; exit;
- Screenshot Create New Channel
- 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 folder your index.php and .htaccess is in on your server.
Note that the channel is defined as a Location Based Channel and uses AREL. - 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 AREL XML Helper for PHP
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 with the AREL XML Helper for PHP:
Note the "\n" in the description. It's a new line character in order to get the line break in the description.
require_once dirname(dirname(dirname((dirname(__FILE__))))) . "/libArel/arel_xmlhelper.class.php";
ArelXMLHelper::start();
$object = ArelXMLHelper::createLocationBasedPOI(
"1", //id
"Hotel Hello World", //title
array(37.776685, -122.422771, 0), //location
"http://dev.junaio.com/publisherDownload/thumb_a1.png", //thumb
"http://dev.junaio.com/publisherDownload/icon_a1.png", //icon
"This is a beautiful, family hotel and restaurant, just around the corner.\nSpecial Dinner and Rooms available.", //description
array(array("Website", "1", "http://www.junaio.com")) //buttons
);
ArelXMLHelper::outputObject($object);
ArelXMLHelper::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:
- 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)
- 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.
error_reporting(E_ALL);
ini_set('display_errors', '1');
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.