Step-by-step guide to create an app

Overview

This step-by-step tutorial illustrates how to create a Friendster application which you can use as an example when creating your own. It assumes that you use PHP and the API client library for PHP.

You will need someone to host your application. This can be your own web server or a third party server as long as it is accessible from the internet (since your application will be added or updated into the users' profile page using the Install URL or Callback URL).

For the purpose of this example, let's assume you have the following environment setup:

Apache running at port 80
PHP 5 installed with all the required dependencies
Server is accessed as www.myfirstapp.com
The Friendster API client library files under <document-root>/lib
Your app file index.php under <document-root>/index.php. You will copy the sample code into this file.

Integrating your application

1) Go to www.friendster.com/developer.
2) Click on ‘Get API Key’.
3) Here are instructions for filling out the form:

Application Name: This is the name that will be displayed in your application’s listing in the Application Directory
Can it be added to Friendster Profile?: Put ‘Yes’ if your application can be displayed in a user’s profile page
Number of instances per profile: We put ‘Single Instance’ for our sample application as it has been designed for this option. This means users can only install 1 instance of the application on their profile. Users can install multiple instances of your application on their profile if you select ‘Multiple Instance’. Choose this option if your application has customization options such that users will want to install it multiple times with different options selected, such as a slideshow application.
Check the Terms of service box
Click on the Optional Information link which will bring up more options
Category: Select the category in which you would like your application to appear in the Application Directory.
Application Description: Provide a short description of your application. This description will be displayed in your application’s listing in the Application Directory and the Add App page.
Default content: You can leave this blank. If you want your application to display specific content on the user’s profile page once it is installed, specify HTML (for instance ‘<p> Hello World! </p>’). The content will not be used if you provide an Install URL.
Canvas Page URL: Use ‘http://apps.friendster.com/your_unique_app_name’ but substitute ‘your_unique_app_name’ with the name of your app. This is the public name for your app, which must be unique across all Friendster apps
Callback URL: You should put the url of the directory on your server where you will create your application. For our application, we put ‘http://www.myfirstapp.com/index.php’. This url will be called by Friendster after a successful login or from your app's Canvas URL.
Install URL: For our app, we put ‘http://www.myfirstapp.com/index.php?install=y’. You should put the url of the directory on your server where you will create your application. This url will be called by Friendster when adding your application. It allows the user to customize the profile content for the app. If left blank, the default content is set in the profile.
Uninstall URL (Coming soon): For our app, we put ‘http://www.myfirstapp.com/index.php?uninstall=y’. This url will be called by Friendster when a user removes your app.
Admin E-mail: Put an email address which we can use to notify you of important updates or issues with your app
Directory icon: Upload the image you would like to use for your app’s listing in the Application directory. The image size should be 75 pixels by 75 pixels.
Tiny icon: Upload the image you would like to use for your app’s listing in the user’s ‘My Apps’ page (coming soon). The image size should be 16 pixels by 16 pixels.

4) Click on the 'Save' button.
5) Click 'Manage Apps' on the developer page and verify that your application was created. If you would like to edit the information, click ‘Edit Settings’.
6) Copy the latest version of the php5 client library into your application's directory on the server.

Latest php client library: Download site

Each app that you create should have a distinct API key and secret.

Under no circumstances should you reveal your secret (especially in forums or when submitting test code for others to debug), otherwise other people can send API requests on your behalf.

Running your application

This sample application displays your user information in the Install Page and saves it in your user profile. Create an 'index.php' file which will be your application's home page. Copy the following code into your index.php file:

<?php

require_once(dirname(__FILE__). '/lib/FriendsterAPI.php');

// TO DO: Enter your secret key below
define('T_SECRET', '<secret key>');
define('T_CSS_STYLE', ' style=" height: 120px; background: #fff; overflow: hidden; margin: 0 auto; "');

// GET parameters from callback URL
$user_id = $_REQUEST['user_id'];
$api_key = $_REQUEST['api_key'];
$session_key = isset($_REQUEST['session_key'])? $_REQUEST['session_key'] : null;
$auth_token = isset($_REQUEST['auth_token'])? $_REQUEST['auth_token'] : null;
try {
 // Validate the request was really constructed and sent by Friendster 

 FriendsterAPI::validateSignature(T_SECRET);
 // Access friendster API
 if ( $session_key != null ) {
 $fapi = new FriendsterAPI($api_key, T_SECRET, $session_key);
 }
 else {
 $fapi = new FriendsterAPI($api_key, T_SECRET);
 $session_key = $fapi->session($auth_token);
 $_GET['session_key'] = $session_key;
 }
 // Access user info from friendster API
 $user_info = $fapi->users($user_id);
 $user_info = $user_info[0];

 // User content
 $content = 'Hello ' . $user_info['first_name'] . "\n";
 $content .= '<p><img '. T_CSS_STYLE . ' src="'
	  . $user_info['primary_photo_url']. '" align="top"/></p>' . "\n";

 // Update content in user profile
 if ( isset($_POST['updateapp']) ) {
 $fapi->post_widget($content);
 $params = array();
 $fapi->redirectToProfile($user_id, $params);
 exit;
 }
 
 // Submit form
 $html = $content;
 $html .= '<form action="" method="post">' . "\n";
 foreach ($_GET as $key => $value) 
 $html .= '<input type="hidden" name="' . $key . '" value="' . $value . '">';
 $html .= '<input type="submit" name="updateapp" value="update my profile"><br>' . "\n";
 $html .= '</form>';
 echo $html;

} catch (FriendsterAPIException $e){
 echo 'Error: ' . $e->getMessage() . '<br/><br/>';
 echo $e->getTraceAsString();
 exit;
}
?>

To run the app in the Install Page you may enter your canvas URL http://apps.friendster.com/your_unique_name

As initially there is no app instance present in your user profile, this will prompt you to add the app. After you click on 'Add' you will be directed to the Install Page.

In this sample application, the Install Page displays your user name and profile photo within an iframe and lets you add the same content to your profile page.

At this stage you have built a fully functional Friendster app. You can go one step further with 'adding friends to your profile'.

Adding friends to your profile

The following code adds a random 'featured friend' in your Install Page and lets you save the content in your profile. You can then go back and forth between your profile and the Canvas Page to update your profile with a different friend.
Don't forget to update the secret key!

<?php
require_once(dirname(__FILE__). '/lib/FriendsterAPI.php');

// TO DO: Enter your secret key below
define('T_SECRET', '<secret key>');
define('T_CSS_STYLE', ' style=" height: 120px; background: #fff; overflow: hidden; margin: 0 auto; "');

// GET parameters from callback URL or hidden parameters
$user_id = $_REQUEST['user_id'];
$api_key = $_REQUEST['api_key'];
$session_key = isset($_REQUEST['session_key'])? $_REQUEST['session_key'] : null;
$auth_token = isset($_REQUEST['auth_token'])? $_REQUEST['auth_token'] : null;
$friend_id = isset($_REQUEST['friend_id']) ? $_REQUEST['friend_id'] : null;

try {
 // Validate the callback URL signature
 FriendsterAPI::validateSignature(T_SECRET);

 // Access friendster API
 if ( $session_key != null ) {
 $fapi = new FriendsterAPI($api_key, T_SECRET, $session_key);
 }
 else {
 $fapi = new FriendsterAPI($api_key, T_SECRET);
 $session_key = $fapi->session($auth_token);
 $_GET['session_key'] = $session_key;
 }

 // Access user info from friendster API
 $user_info = $fapi->users($user_id);
 $user_info = $user_info[0];

 // Access one random friend from friendster API
 if ( $friend_id === null ) {
 $friend_ids = $fapi->friends($user_id);
 $friend_ids = $friend_ids['friends'];
 if ( count($friend_ids) > 0 )
 $friend_id = $friend_ids[array_rand($friend_ids)];
 }

 // Content for featured friend
 if ( $friend_id === null ) {
 $content = '<p>You need friends!</p>';
 } 
 else {
 $friends = $fapi->users($friend_id);
 $friend_info = $friends[0];
 $content = '<p>My Featured Friend: ' . $friend_info['first_name'] . '</p>' . "\n";
 $content .= '<p><a href="http://profiles.friendster.com/' . $friend_id . '">';
 $content .= '<img '. T_CSS_STYLE . ' src="'
	. $friend_info['primary_photo_url']. '" align="top"/></a></p>' . "\n";
 }

 // Update featured friend in user profile
 if ( isset($_POST['updateapp']) ) {
 $fapi->post_widget($content);
 $params = array();
 $fapi->redirectToProfile($user_id, $params);
 exit;
 }

 // Display user
 $html = 'Hello ' . $user_info['first_name'] . "\n";
 $html .= '<p><img '. T_CSS_STYLE . ' src="'
	. $user_info['primary_photo_url']. '" align="top"/></p>' . "\n";
 $html .= $content;
 
 // Submit form
 $html .= '<form action="" method="post">' . "\n";
 if ( $friend_id !== null )
 $html .= '<input type="hidden" name="friend_id" value="' . $friend_id . '">';
 foreach ($_GET as $key => $value) 
 $html .= '<input type="hidden" name="' . $key . '" value="' . $value . '">';
 $html .= '<input type="submit" name="updateapp" value="update featured friend in my profile"><br>' . "\n";
 $html .= '</form>';
 echo $html;

} catch (FriendsterAPIException $e){
 echo 'Error: ' . $e->getMessage() . '<br/><br/>';
 echo $e->getTraceAsString();
 exit;
}
?>

How your application gets called

Once the application is installed in your profile it will direct you to the Canvas Page if you click on the 'expand' symbol on the chrome of the application in your user profile. If you log in as a different user you can “grab” the application from your profile, which will open the Install Page.

To delete the application from your profile, click on the 'x' symbol on the chrome. You may then install it again with the Canvas URL.

Your application is called directly by the Friendster platform using one of these methods:

Install URL - Called when the user adds your application.
Callback URL - Called when the user clicks on the 'expand' symbol on the chrome of the app content in the user profile, or from the Canvas URL.
Uninstall URL - Called when the user removes the app.

You can modify these urls at any time when you click on ‘Edit Settings’ and then ‘Optional Information’ in the ‘Manage Apps’ page: www.friendster.com/developer/widget_manage.php

Testing your API implementation

If an API call is not working or you wonder what format to expect in return, you may enter your API key and secret in the API Test Tool: http://api.friendster.com

After login you can build your API request and check the results.