How to create a Bebo application using PHP 5

by on May 8, 2008

in Bebo, Programming

Introduction

I have been answering a lot of email requests for how to get started with a Bebo application. Since applications can be written in any language that supports interaction with the Bebo REST API, developers have a lot of choices in how they build their application. The focus of this article will be on the "officially supported language" - PHP. I saw officially supported, because the Bebo Platform Team has released a simple PHP wrapper that makes using the REST API very simple, and they update this from time to time.

Before creating an application, you need to understand the parts of an application and how they interact with Bebo. I will go over each part below, and then show an example of a very simple application that uses each part.

The parts of a Bebo Application

The Bebo URL - this is the URL that users go to on Bebo. It is in the format "http://apps.bebo.com/yourapp/"

The Callback URL - this is the URL on your server that Bebo redirects to. It is where the actual application lives.

The Canvas Page - this is the main page of a Bebo application. It takes up the entire web page, except for the Bebo top header and footer. User's going to your canvas page are using your server directly via the callback URL. Canvas pages can either be written in SNML, a markup language that is standardized across Facebook and Bebo and is fast to load, or in an iFrame. Javascript is only allowed in iFrame based applications, but they cannot use SNML.

The Profile Box - each application can create a presence on the installing user's Profile page. This contents of this box are set by the application, but when the user is seeing this Profile box, it is running a cached version on Bebo's servers. The user can click links or interact with Flash to go to the canvas page or call back to your server using simple AJAX. Since browsing other people's Profiles is one of the main activities on Bebo, creating a compelling Profile Box is a very important part of helping your application to spread.

Invitations - each application can provide a way for users to recommend it to their friends. Bebo provides a common dialog for selecting friends, and limits the total number of invitations that can be send per person per day. You can control some of the text that the inviter sees when selecting their friends, and some of the text in the actual invitation. Your application must give the user a reason to want to send an invitation, either by being innately good, or by some type of reward system for invited friends.

News Stories - applications can produce news stories based on how the users interact with the application. These stories appear on the user's Profile page in the news section. Bebo will also show the most interesting stories from a user's friends on their home page. News stories should be interesting and actionable in order to help your application spread and provide value to the user.

Building a Bebo Application

  1. Get a Server - As I said above, we will focus on building an application using PHP. The first thing you need is a server to host your application files. Some likely candidates might be your home pc to start, Joyent or another hosting company, or the Amazon EC2 web server platform. As your application grows, your server needs will probably grow as well, so it good to think about how you will handle thousands of users early on. RightScale.com provides some automatic scaling services on top of the Amazon EC2 platform, that let you spin up and shut down servers to meet your demand, so that you only pay for what you use. You will need the information about this server to set up and deploy your application.
  2. Install the Bebo Developer Application - go to http://www.bebo.com/Profile.jsp?MemberId=5036051566 and install this application. It is written by Bebo, and is required to let you set up your application with Bebo. Once you have it installed, you can go to create a new application.
    1. Click the Create New Application link at the top right
    2. Enter the Application Name - this is the name you want people to see. Example: "Favorite Birds".
    3. Enter the Application URL - this is the Bebo URL that users will go to. This name doesn't have to match the Application Name, and in some cases cannot, because the name you pick might already be in use. Example: "favoritebirds".
    4. Pick a canvas style - If you want to use the Bebo SNML markup language, choose SNML. If you want to host an external site in an iframe or use javascript frameworks, then choose iFrame. For this example, we will choose SNML.
    5. Enter a description - Type something, but don't worry too much about this now, you can fill this out later.
    6. Enable on a profile - Check this box if you want to let users have your application on their profile. In almost every case, you will leave this checked.
    7. Callback URL - the location on your server that holds your files. I like to have the directory match the application url I set above, and I end it in a slash. Example: http://myserver.com/favoritebirds/
    8. Post Add URL - Leave this blank for now. I will go over how to handle this later.
    9. Remove Callback URL -Leave this blank for now. I will go over how to handle this later.
    10. Default SNML - this is a way to initially set the contents of all new user's profile boxes.
    11. Categories - pick one that fits your application. You can change it later.
    12. Icons - you can update this later, so leave it for now.
    13. Leave the Manage Test Group checkbox checked and set to Only Developers.
    14. Check the I have read the terms checkbox.
    15. Click Create Application.
    16. It should take you to the My Applications page and you should see your new application along with a bunch of other information. We will use this later, so leave the page up.
  3. Get the Bebo library - the Bebo platform team provides an updated wrapper library here http://developer.bebo.com/downloads/example-libs-php.php.
    1. Create a new source directory - c:\src\favoritebirds.
    2. Download this file and save it in your source directory. Call it something simple, like bebo.php.
  4. Set up your web host
    1. In Apache, edit your http.conf or create an .htaccess file so that your new callback url http://myserver.com/favoritebirds/ points to your source directory.
    2. In IIS, use the IISAdmin tool to create a new Virtual Directory so that your new callback url http://myserver.com/favoritebirds/ points to your source directory.
  5. Create your index.php file
    1. For this example, we will do all the work in this file. In a real application, you would want to split up your work into classes or modules or include files that make sense for your project.
    2. Include the bebo php library.
      1. require_once "bebo.php";
    3. Your file needs to have some globals that define the project.
      1. $appVisibleName = "Example App";
      2. $appApiKey = 'copy API Key from the developer application page';
      3. $appSecret = 'copy API Secret from the developer application page';
      4. $appCallback = 'put in your callback url. Ex - http://myserver.com/favoritebirds/ ';
      5. $appBeboURL = 'put in the Application URL above - http://apps.bebo.com/favoritebirds/';
    4. The easiest way to handle users is to force everyone to add right away. If they haven't Bebo will take then to the add page and then send them back. If they have already added your application, then you will just get their userid.
      1. $bebo = new Bebo( $appApiKey, $appSecret );
      2. $userID = $bebo->require_add();
    5. Now you can display the page to them using some SNML.
      1. displayPage($bebo);
      2. function displayPage($bebo) {
      3. $userID = $bebo->user;
      4. $output = "Welcome back, <sn:name uid='$userID' useyou='false' />.<br/>
      5. You have a nice picture:<sn:profile-pic uid='$userID' linked='false'/>";
      6. echo $output;
      7. }

    You now have a fully functional Bebo application. But, let's add some more features.

  6. Updating the user's profile
    1. It is simple to update a user's Profile Box each time they access your application. Just create a new updateProfile function and call it after your displayPage function.
      1. updateProfile($bebo);
      2. function updateProfile($bebo) {
      3. global $appVisibleName;
      4.  
      5. $userID = $bebo->user;
      6. $snml = "This is the $appVisibleName profile box of <sn:name uid='$userID' useyou='false' />
      7. <br/><sn:profile-pic uid='$userID' size='square' linked='false'/>";
      8. $bebo->api_client->profile_setSNML($snml);
      9. }
  7. Creating a News Story when the user accesses your page
    1. News stories are a great way to let a user's friends know about the great things the user is doing with your application. Just add a new publishStory function and call it when the user does something meaningful.
      1. publishStory($bebo);
      2. function publishStory($bebo) {
      3. global $appVisibleName;
      4. global $appBeboURL;
      5.  
      6. $actor = $bebo->user;
      7. $title_template = "{actor} used <a href='$appBeboURL'>$appVisibleName</a>";
      8. $title_data = null;
      9. $body_template = null;
      10. $body_data = null;
      11. $body_general = "Everyone should try $appVisibleName. <a href='$appBeboURL'>
      12. Install $appVisibleName today.</a>";
      13. $image1 = null;
      14. $image1Link = null;
      15.  
      16. try {
      17. $result = $bebo->api_client->feed_publishTemplatizedAction( $actor, $title_template,
      18. $title_data, $body_template, $body_data, $body_general,
      19. $image1, $image1Link,
      20. NULL, NULL,
      21. NULL, NULL,
      22. NULL, NULL,
      23. "");
      24. } catch( Exception $ex) {
      25. }
      26. }
  8. Allow users to share your application with Invites
    1. If your application is worthwhile, users will want to let their friends know about it. Use the standard Bebo Invite control to let them invite up to 20 friends/day. Just add a new getInvitePageURL function, and add a link somewhere on your page to that url.
      1. $invitePageURL = getInvitePageURL($bebo);
      2. echo "<a href='$invitePageURL'>Would you like to invite some friends?</a>";
      3.  
      4. function getInvitePageURL($bebo) {
      5. global $appApiKey;
      6. global $appBeboURL;
      7. global $appVisibleName;
      8.  
      9. $beboInvitePage = "http://www.bebo.com/multi_friend_selector.php";
      10. // What the inviter sees
      11. $actionText = urlencode("Which friends do you want to invite?");
      12. $action = $appBeboURL;
      13. $type = urlencode("Invite");
      14.  
      15. // What the recipient sees
      16. $acceptInviteButtonURL = $bebo->get_add_url($appBeboURL);
      17. $acceptInviteButtonLabel = "Add $appVisibleName";
      18. $acceptInviteButton = "<sn:req-choice url='$acceptInviteButtonURL' label='$acceptInviteButtonLabel' />";
      19. $content = urlencode("Hey, try out $appVisibleName. $acceptInviteButton");
      20.  
      21. $sig = 0; // update with the signature tool. This is a two step process. Generate the url for the invite page
      22. // Then go to http://www.bebo.com/AppToolSig.jsp and paste it in. At the bottom, you will get a signature. Update the value above.
      23. // If you change the invite text, you will have to regenerate the sig above
      24. $invitePageURL = "$beboInvitePage?sig=$sig&api_key=$appApiKey&content=$content&type=$type
      25. &action=$action&actiontext=$actionText&invite=true";
      26.  
      27. return $invitePageURL;
      28. }

Here is the completed sample:

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  2. <?php
  3. date_default_timezone_set("America/New_York");
  4.  
  5. require_once "bebo.php";
  6.  
  7. // Global definitions for your app
  8. $appVisibleName = "Favorite Birds";
  9. $appApiKey = "copy API Key from the developer application page";
  10. $appSecret = "copy API Secret from the developer application page";
  11. $appCallback = "http://myserver.com/favoritebirds ";
  12. $appBeboURL = "http://apps.bebo.com/favoritebirds/";
  13.  
  14. ///Main Entry Point ///
  15. // Force everyone to add the application.
  16. // If they have already added it, then display the page
  17. $bebo = new Bebo( $appApiKey, $appSecret );
  18. $userID = $bebo->require_add();
  19. displayPage($bebo);
  20.  
  21. // Update the user's profile
  22. updateProfile($bebo);
  23.  
  24. // Publish a news story
  25. publishStory($bebo);
  26. ///End Main Entry Point ///
  27.  
  28. function displayPage($bebo) {
  29. $userID = $bebo->user;
  30. $output = "Welcome back, <sn:name uid='$userID' useyou='false' />.<br/>
  31. You have a nice picture:<sn:profile-pic uid='$userID' linked='false'/>";
  32.  
  33. // Add the link to the invite page
  34. $invitePageURL = getInvitePageURL($bebo);
  35. $output .= "<br/><a href='$invitePageURL'>Would you like to invite some friends?</a>";
  36. echo $output;
  37. }
  38.  
  39. // returns the url for the Bebo standard invite page
  40. function getInvitePageURL($bebo) {
  41. global $appApiKey;
  42. global $appBeboURL;
  43. global $appVisibleName;
  44.  
  45. $beboInvitePage = "http://www.bebo.com/multi_friend_selector.php";
  46. // What the inviter sees
  47. $actionText = urlencode("Which friends do you want to invite?");
  48. $action = $appBeboURL;
  49. $type = urlencode("Invite");
  50.  
  51. // What the recipient sees
  52. $acceptInviteButtonURL = $bebo->get_add_url($appBeboURL);
  53. $acceptInviteButtonLabel = "Add $appVisibleName";
  54. $acceptInviteButton = "<sn:req-choice url='$acceptInviteButtonURL' label='$acceptInviteButtonLabel' />";
  55. $content = urlencode("Hey, try out $appVisibleName. $acceptInviteButton");
  56.  
  57. $sig = 0; // update with the signature tool. This is a two step process. Generate the url for the invite page
  58. // Then go to http://www.bebo.com/AppToolSig.jsp and paste it in. At the bottom, you will get a signature. Update the value above.
  59. // If you change the invite text, you will have to regenerate the sig above
  60. $invitePageURL = "$beboInvitePage?sig=$sig&api_key=$appApiKey&content=$content&type=$type&action=$action&actiontext=$actionText&invite=true";
  61.  
  62. return $invitePageURL;
  63. }
  64.  
  65. function updateProfile($bebo) {
  66. global $appVisibleName;
  67.  
  68. $userID = $bebo->user;
  69. $snml = "This is the $appVisibleName profile box of <sn:name uid='$userID' useyou='false' />
  70. <br/><sn:profile-pic uid='$userID' size='square' linked='false'/>";
  71. $bebo->api_client->profile_setSNML($snml);
  72. }
  73.  
  74. function publishStory($bebo) {
  75. global $appVisibleName;
  76. global $appBeboURL;
  77.  
  78. $actor = $bebo->user;
  79. $title_template = "{actor} used <a href='$appBeboURL'>$appVisibleName</a>";
  80. $title_data = null;
  81. $body_template = null;
  82. $body_data = null;
  83. $body_general = "Everyone should try $appVisibleName. <a href='$appBeboURL'>Install $appVisibleName today.</a>";
  84. $image1 = null;
  85. $image1Link = null;
  86.  
  87. try {
  88. $result = $bebo->api_client->feed_publishTemplatizedAction( $actor, $title_template,
  89. $title_data, $body_template, $body_data, $body_general,
  90. $image1, $image1Link,
  91. NULL, NULL,
  92. NULL, NULL,
  93. NULL, NULL,
  94. "");
  95. } catch( Exception $ex) {
  96. }
  97. }
  98. ?>

Advanced user state management

The example above just forces everyone to add, but isn't able to specially handle new installs or removals. You can handle those by looking at the $_REQUEST parameters that Bebo passes your application. These parameters show that users come to your application in 1 of 3 states:

  1. Just installed the application
  2. A normal user of the application
  3. Just removed the application

By changing the block marked ///Main Entry Point /// above to one that detects the state, you can handle each one differently. You will need to add new functions to handle new user installs and uninstalls

  1. ///Main Entry Point ///
  2. // An existing user will have the fb_sig_in_canvas variable set, unless they are removing
  3. if (isSet($_POST) && isSet($_POST['fb_sig_in_canvas'])) {
  4.  
  5. // Bebo will pass their user id and that they have added the application
  6. if ( isSet($_POST['fb_sig_user']) && $_POST['fb_sig_added'] == 1 ) {
  7. $userID = $_POST['fb_sig_user'];
  8.  
  9. // If the user has just installed, Bebo will pass installed as a GET parameter
  10. if ( isSet($_GET) && isSet($_GET['installed']) ) {
  11. newInstall($userID);
  12. }
  13.  
  14. // Normal users will go through here, so display the page
  15. $bebo = new Bebo( $appApiKey, $appSecret );
  16. displayPage($bebo);
  17.  
  18. // Update the user's profile
  19. updateProfile($bebo);
  20.  
  21. // Publish a news story
  22. publishStory($bebo);
  23. }
  24. }
  25.  
  26. // If you set up your own post add handler, then you must handle the add request the way you want,
  27. // and then redirect back to your Bebo URL. If you don't specify a post add handler, Bebo does this for you.
  28. else if ( isSet($_GET) && isSet($_GET['installed']) ) {
  29. $bebo = new Bebo( $appApiKey, $appSecret );
  30. newInstall($bebo );
  31. $bebo->redirect($appBeboURL);
  32. }
  33. // If you specify a post remove URL, then Bebo will call it with this POST variable.
  34. // After this call, you won't get anything else from this user unless they re-add your application
  35. else if ( isSet($_POST) && isSet($_POST['fb_sig_uninstall']) ) {
  36. $userID = $_POST['fb_sig_user'];
  37. uninstallUser( $userID);
  38. }
  39.  
  40. // If the user goes to your callback URL directly, they didn't come in from Bebo, and you will have no information about the user
  41. // In most cases, you will just want to force the user to add the application by using require_add. This will force them back through
  42. // the existing user path above
  43. else {
  44. $bebo = new Bebo( $appApiKey, $appSecret );
  45. $bebo->require_add();
  46. }
  47.  
  48. // Handle a new user installation
  49. function newInstall($userID) {
  50. // We can use the SNML to say hello to the user
  51. $output = "Hello, <sn:name uid='$userID' useyou='false' />. Thanks for adding the application!";
  52. echo $output;
  53. }
  54. function uninstallUser($userID) {
  55. // You can't actually display anything to the user, or redirect them.
  56. // All you can do is clean up inside your application.
  57.  
  58. }
  59.  
  60. ///End Main Entry Point ///

About Thought Labs

Thought Labs provides custom software development and consulting services with a specialization in Social Network technologies. We build branded Facebook Pages for your company or multiple Pages for your various products. In addition, we create rich interactive applications on your Page to help users find your products and services. Thought Labs can also create custom Facebook, Bebo or OpenSocial applications carrying your message and your brand with them.

We pride ourselves on the quality of our work. We employ top application developers who are creative, highly skilled, up-to-date on the Social Networks' constantly changing APIs, and excellent at project management. We set high standards for ourselves and we meet them. In this new world of social marketing, Thought Labs delivers extremely innovative, high-quality work on time and on budget. Find out more at http://www.thoughtlabs.com.

Comments

  1. excel says:

    [...] coherent post on how to create a Bebo application from end-to-end using PHP. Really well done.http://www.thoughtlabs.com/blogs/2008/05/08/how-to-create-a-bebo-application-using-php-5/Excel TutorialThis is a basic tutorial of Excel. START HERE Specific examples may refer to excel but [...]

  2. Hubs of How to create a Bebo application using PHP 5…

    hubs about Directory Servers to In almost every case, you will leave this checked. Callback URL – the location on your server that holds your files. I like to have the directory match the application url I set above, and I end it in a slash. ……

  3. [...] this new post on his blog, John Maver gives a step-by-step guide for creating a PHP5 application for the popular [...]

  4. eddieh says:

    Cheers for this useful code. I’m confused with a certain part of the code comments though.

    This is a two step process. Generate the url for the invite page
    // Then go to http://www.bebo.com/AppToolSig.jsp and paste it in. At the bottom, you will get a signature. Update the value above.

    How do I generate the url for the invite page and where should I paste it in the php code?

  5. John Maver says:

    Get the current value of the URL when sig =0. Paste that into the signature tool. It will give you a new value for sig. Replace sig=0 with the new value and it should work.

    You paste something like this(replacing the **** sections ) into the sig tool

    http://www.bebo.com/multi_friend_selector.php?sig=0&api_key=*****yourapikey*****&content=Hey, try out my app. &type=Invite&action=http://apps.bebo.com/*****yourappname****/&actiontext=Which friends do you want to invite?&invite=true

    and get
    Final Signature (md5 of above)
    Bc9e9999c9999999d99ac9b9defafb99

    Then replace sig=0 with the Bc9e9999c9999999d99ac9b9defafb99 in your code.

  6. eddieh says:

    Cheers – I try this out. :)

  7. y2kprawn says:

    Hi there,

    cheers for the coherent and easy to follow introduction to this topic.

    I am trying to make an application to allow users to post their XBOX tags on their profile page, as a social networking site I should be able to do this to increase my usage and have a nice thing for my rep.

    So I have all my app hooked up to discover to my shock that the profile part of the app does not support iframes.

    What…

    I mean , please , come on !!

    I am trying to get content from XBOX , this is in the form of

    I need another way of rendering this content into the Profile page , as this is the only place where this would be of any use.

    Do you have any suggestions for me, this would be an excellent community tool and would be a really top kudos to Bebo,

    Rob

  8. John Maver says:

    y2kprawn,

    The sentence where you describe the format of the xbox data is cut off.

    There are only two things you can do on the profile – FBML and flash. So, if getting the data on the application canvas page and then writing an FBML representation of it on the profile doesn’t meet your needs, then you can write a quick flash application that provides a richer experience.

    John

  9. [...] tutorial for creating bebo application with php, step by step and code example.   [...]

  10. melvin chand says:

    I created an application whats an default snml because I didnt put it in is it importent to put it in and when I finished with the application I click create app then after that it says settiings for switch-in because thats my application now what please help

  11. Farhan Memon says:

    If I create an application with an iFrame is there a way to create the invite and news story functionality?

  12. David says:

    I know this is an old entry, but I was hoping you may be able to help me. I am working on an application for Bebo and have been trying to use an iFrame approach. I’m having trouble maintaining a session this way, do you have any advice? It’s my AJAX queries that are having problems.

    Thanks,
    David

  13. John Maver says:

    David,
    All the Bebo session variable are passed as POSTs to the iframe. You can pass these to the ajax call or you could store the user’s session key in the database and look it up in your ajax handler.

  14. John Maver says:

    Farhan,
    Yes – for invites, you can use the Bebo invite page instead of the snml control. Just have your link go to it as I do in the example above. For news stories, it is just the API call, so it doesn’t matter if it is from an iframe or fbml page.

  15. David says:

    Thanks for the quick reply John,
    Appreciated :)

  16. Ben Chapman says:

    I am writing an application that displays quotes and wanted to know how I can make it fetch a random quote every time the profile is accessed instead of every time the displayPage() is viewed?

    http://stikked.com/view/4457d41e is the code

  17. Mark says:

    Hello John,

    Following the format of your script, I've created an app using Iframe. Everything works fine till the canvas page i.e. i see the intended output on the canvas page.

    However when I go on my profile, I see the module for the app there and the one line I have in the function updateProfile i.e in the $snml variable. But i don't see the very app itself, the very thing that should come from my iframe or anything that was on the canvas. I've used both the api_client->profile_setSNML and api_client->profile_setFBML functions but still no good. What I'm I doing wrong?

  18. Mark says:

    additional question: the page being embedded in iframe…can it be in html or has to be in fbml? Sorry I'm a total newbie

  19. Romance says:

    HeyItIsRomance

  20. trishaas says:

    I asked someone how to make an app and they said i used text place to application face..what do they mean by that? and how do you do it?

  21. trishaas says:

    Do you use rightscale or apache to create the app? you said for apache ' Apache, edit your http.conf or create an .htaccess file so that your new callback url http://myserver.com/favoritebirds/ points to your source directory.' and you said

    Get a Server – As I said above, we will focus on building an application using PHP. The first thing you need is a server to host your application files. Some likely candidates might be your home pc to start, Joyent or another hosting company, or the Amazon EC2 web server platform. As your application grows, your server needs will probably grow as well, so it good to think about how you will handle thousands of users early on. RightScale.com provides some automatic scaling services on top of the Amazon EC2 platform, that let you spin up and shut down servers to meet your demand, so that you only pay for what you use. You will need the information about this server to set up and deploy your application.

  22. LGlosi says:

    Can anyone help me to proceed on from the part get the Bebo Library i don't know where to find the library……..can any one help plizz

  23. Great post and very useful information. I'm learning more about Facebook pages and doing a post soon about how nonprofits running events can leverage social media tools.

  24. Great post and very useful information. I'm learning more about Facebook pages and doing a post soon about how nonprofits running events can leverage social media tools.

Previous post:

Next post: