Quick Start Guide
From fringDocumentation
Contents |
1. Intro
This guide contains step-by-step instructions for developing a simple fring add-on. It uses as an example "Hello World" fring add-on. By following it, you'll get a feel for the core steps involved in creating and deploying fring add-ons. Once you are done, you should have a foundational understanding of the fring API. You will be able to use this example as a template for your future add-ons.
2. Prerequisites
To get started, you'll need programming access to a webserver that is accessible from the Internet. It can be your own server or a hosted one, so long as it can expose URLs and respond to HTTP requests from the Internet. For this example, it must be running either PHP or .NET.
This guide also assumes you already have a supported handset on which you have installed fring application. If you have not done this, please take a moment to do it now.
3. The Sample Add-On
Before you get going, you'll need to perform some routine setup. You'll probably perform some version of this set of steps every time your create a new add-on. Here's an outline of the steps. For each of these steps, there is a section of instructions below which explains it.
- Deploy the source code on your webserver
- Register your add-on
- Configure your add-on
- Test your add-on on your handset
3.1. Deploying the Source Code
If you have your webserver set up as described above, go ahead and deploy the source code from the "Hello World" example to it:
- Download the sample files to your server. Go to download page and download the PHP or .NET version of the sample files. Once you have downloaded them, unpack them at your webserver's document root.
Note: The download site has links to both a PHP version of the sample and a .NET version. The code samples in this Quick Start Guide refer to the PHP version, but you should be able to follow along even if you plan to use .NET version.
- Test your URL. Notice that one of the files is called "callback.php". Test your URL by pointing a browser to that location, via the internet. So for example, if you deployed hello.php at your document ment root, and your web server is reachable at "<tt>http://myserver.com</tt>", then you should point your browser to "http://myserver.com/callback.php".
It should display a blank page. If it does not, something is wrong with your webserver, PHP, or .NET deployment, independent of the fring API. You will have to fix this before you are able to move on to the next step.
3.2. Registering Your Add-on
If you successfully tested your URL in step above, you can now register your add-on. It's important to have a successfully functioning URL first, as it will be used when your register your add-on.
Note: This guide assumes you have already registered as a fring developer. If you have not, please do so now at the fring developer's site.
If you aren't logged into the fring developer's site, go ahead and do that now. Then click the Register Your Addon link in the side navigation panel.
This leads you to the Create Add-on Page.
Fill in the fields circled in red in the illustration above -- for now, you can skip the other's. A few words of explanation on the required fields:
- Addon Name
This can be any string of characters, including numbers and spaces. You may want to name it something like "Your-fring-ID-Hello World", each add-on should have a unique name.
- Callback URL
This is the URL you [#Deploying the Source Code | tested above]. Enter that URL here.
- IMEI
This is the serial number of the handset you'll test with. To get your device's IMEI, press *#06# on the numeric keypad -- the device will display the IMEI. Enter that number in the text box labeled IMEIs that should have access to this add-on. Your add-on will be visible only to this handset. You can enter more than one IMEI if you want to test your add-on on more than one handset. Only when you are ready and have contacted fring to publish the add-on will it be visible to all fring users.
You can ignore the other fields on this page for now, and click Save.
3.3. Configuring Your Add-on
Now, back on your webserver, you configure your add-on by editing the config.ini file you downloaded when you set up your server. The fring SDK uses this file during the authentication step.
On your webserver, config.ini should reside in the same directory as the file that your URL points to. The only thing you have to do is to replace the generic username, password, and addon-id with the ones that belong to your addon.
Here's what the generic config file looks like before you edit it:
[Addon configuration] ; fring interface server URL fis_url = api.fring.com ;fring interface server port fis_port = 8080 ; Default content encoding encoding = "UTF-8" ; Addon login addon_login = USER_NAME_HERE ; Addon password addon_password = PASSWORD_HERE ; Addon ID number addon_id = ADDON_ID_HERE ; Flag for logging data (1 for logging, 0 for not logging) log_data = 1
- USER_NAME_HERE
Replace this with the user name of your developer account, in the section Registering Your Addon.
- PASSWORD_HERE
Replace this with the password that fring assigned you for your developer account.
- ADDON_ID_HERE
Replace this with the addon id that fring assigned you when you registered your addon. (You can look up the addon id by going to the My Addons page, and clicking on the Edit link next to your addon's name.)
Save the file. You are now ready to test your handset.
3.4. Running Your Add-On
At this point, you should be able to run your add-on. Begin by restarting fring on your handset. This causes fring to regenerate the list of add-ons your handset is subscribed to. If you supplied the correct serial number for your handset when you registered your add-on, you should see "Hello World" (or whatever you named your add-on) in the Add-On Catalog. Scroll down to your add-on and select it by pressing the selection key button.
Hello World will open into it's own tab. With the selection key, select Ok. If your add-on works correctly, you'll see an alert saying "Subscribing" and a progress bar. These should disappear in a moment or so. (If there's a problem, you'll get a "Subscription Failed" alert.) You've now subscribed to your add-on.
To run it, select it from the list again, and click on it. The hour glass will spin while your handset is waiting for your server to respond. If you've done everything correctly, you'll see the message "Hello World!"
At this point your are ready to develop your own add-on. You can do this by using Hello World or any of the other samples in SDK as models. The rest of this guide steps through the most basic elements of fring add-on development using the Hello World source code as a reference.
4. Where to Go From Here?
If everything worked as described, you're probably ready for bigger and better things. The Hello World add-on we created here is very simple. For a framework of a more robust add-on, you probably should take a look at callback.php in the PHP SDK you downloaded earlier. This file does everything that helloworld.php does, so you should be able to follow it. But it's much more generalized, and handles a more complete set of fring notifications and requests. Along with that file, and the complete fring API You can use it as a basis for real-world fring applications.
For better understanding the "Hello World" example click here
Appendix: Source code