Developer / Documentation / OpenSocial tutorial: an example app in PHP
Building a simple application
This is part 3 of our OpenSocial tutorial. While part 1 focused on building a gadget within Netlog and part 2 on applications hosted on external sites using OpenSocial REST, we will now use what we learned to build a real application.
Our application is a game called Speedbox that measures how good you know your friends: it fetches the avatars and nicknames of some friends, and you have to match each avatar with the correct nickname by dragging it into a box. The faster you can do this the better of course.
Testing the application
Speedbox consists of just 3 files. Download them here, extract the files and put them together in a folder on your online web host. Additionally, to get the app working you will need to:
- Edit speedbox.xml on this line so that it points to the correct location of speedbox.php:
window.phpPageLocation = 'http://www.mydomain.com/opensocial/speedbox.php';
- speedbox.php - the actual application. View source
- class.osrest.php - utility class to do the OpenSocial REST calls. View source
Defining the gadget which loads the iframe + doing OpenSocial REST calls
First of all we have the spec XML file, speedbox.xml, which defines the gadget. The gadget does not do very much: it requests a security token and the language of the Netlog site we are on. It then creates an iframe pointing to our real application. See part 1 for an explanation about gadgets and the spec XML.
Our openSocial REST utility class class.osrest.php will be used to do 'social REST calls' like fetching the user's friends and posting activities. See part 2 for an explanation about openSocial REST.
The application itself
- Using php the security token and language are caught from the iframe URL parameters, and used to instantiate an instance of the OSRest class.
- We also define the round (if none is detected we assume round 1) and the number of friends to be fetched per round.
- Still with PHP, we detect if the user made it to round 4 and post an activity log for his friends if he did.
- Using CSS we set the layout of the visual elements of our app.
- We include the Prototype and Scriptaculous JS libraries (Google hosts them for you!) which will make implementing drag-and-drop easy.
- We start with the HTML of our page.
- We define a hidden POST form which will make the rounds advance.
- Using PHP and our OSRest object, we fetch an array with the user's friends including avatar thumbnails, and use that to display both the pictures and the boxes to drop them in.
- Using JS at the bottom we implement most of the
- A timer to count how long it takes the user to complete the round
- Turn the images and drop boxes into 'draggables' and 'droppables', which is made super-easy by the Scriptaculous JS library.
- Some logic for detecting if an image was dropped in the correct box, showing a 'report' phrase with green or red highlighting depending on if the image was dropped correctly ...
- If the round is finished we submit the hidden POST form with a new round number.
- And that's all!
Obviously this application is very primitive (but at least it's small): a game never actually 'ends', so it would be better to count down with the timer from a fixed number of seconds, and see how many rounds the player makes it. Also, detecting the box is simply done comparing attributes of HTML elements, etc..
A more important flaw of this application relates to something very important: Netlog's security token will automatically become invalid 20 minutes after the last call. This means that if the user loads the app but then leaves it alone for long enough, the REST calls will receive '401 unauthorised' responses instead of what we actually want.
Since the token expires 20 minutes after the last call and not after the token was generated, here's one simple way to keep an application 'alive': just implement an automatic 'dummy call' to Netlog every 10 minutes or so (e.g. re-fetching the viewer info), and your app will stay authorized for as long as needed.
OpenSocial applications can be directly treated as a game within Netlog: the necessary high score calls are custom Netlog extensions to the OpenSocial REST API so it's but a small stap to implement these at the appropriate moments.
Articles for app developersMust-reads:
- Tutorial 1: OpenSocial JS API
- Tutorial 2: OpenSocial REST API
- Tutorial 3: OpenSocial example app
- Tutorial 4: OpenSocial PHP client
- Tutorial 5: Flash and OpenSocial