Self Debugging

As I went throught converting my application, Blog Networks, to the new profile design, I document the steps I went through hoping to help others who’re going through the same process. In this post I’ll cover the essential changes that you need to do, and in a futuer post I’ll describe how to utilize some of the new features the new profile brings.

1. Get the new Facebook client library

First, download the latest version of the PHP client library and overwrite the old one. Get the latest version here:

http://svn.facebook.com/svnroot/platform/clients/php/branches/redesign-changes/

2. Which version of the APIs to use?

During the transition period some users will be on the old profile and some on the new. However, the new client library points all API calls to the new URL, api.new.facebook.com. While this works, it has the side effect of switching your users to the new profile the moment they hit any of your pages that require the user to login because it’ll forward them to a www.new url to log in. I didn’t feel comfortable making my users feel that my application was responsible for changing their Facebook experience. I also wanted to utilize the fact that adding the profile box and the email opt-in are selected by default.

So, instead, I decide to let users on the old profile use the old APIs and users on the new profile use the new APIs. If you want an easier migration path, then skip this step. Otherwise, edit your facebook.php file as follows:



Change this:

  public static function get_facebook_url($subdomain=’www’) {
    return ‘http://’ . $subdomain . ‘.new.facebook.com’;
  }

To This:

  public static function get_facebook_url($subdomain=’www’) {
    global $NEWPROFILE;

    if ($NEWPROFILE)
        return ‘http://’ . $subdomain . ‘.new.facebook.com’;
    else
        return ‘http://’ . $subdomain . ‘.facebook.com’;
  }

3. Which profile are your users on?

If you chose to support both the old and new APIs in the previous step, then you’ll need to know on which profile a user is. Add this little code to a file that you include in every one of your PHP pages. A config file is a good place, or you can add it to the top of the facebook client library (facebook.php):

// New or old profile?
$NEWFACEBOOK = false;
if ($_REQUEST["fb_sig_in_new_facebook"] == "1"){
    // User is on the new profile.
    $NEWFACEBOOK = true;
}

 4. Switching from require_add to require_login

The new Facebook client library doesn’t have the require_add() and require_install() methods, so if you use any of these your code will break. If you chose to support only the new APIs in step 2 above, then simply change all calls to the above two methods to require_login().

However, if you choose to have users on the old profile continue to "add" your app rather than authorizing it, then add the following code to your facebook.php file, and you don’t need to change anything in your application code:

  // Used in the transition perdiod to accomodate both
 // old profile and the new one.
  public function require_install() {
    return $this->require_add();
  }

  // Used in the transition perdiod to accomodate both
  // users on the old profile and the new one.
  public function require_add() {
    global $NEWFACEBOOK;
    if ($NEWFACEBOOK) {
        return $this->require_login();
    }
     
      if ($user = $this->get_loggedin_user()) {
      if ($this->fb_params[’added’]) {
        return $user;
      }
    }
    $this->redirect($this->get_ add_url(self::current_url()));
  }

 

5. No post-add page

With the new profile, Facebook will no longer call your post-add page. On the old profile, Facebook redirects new users to this page after they add an app. Many developers, myself included, use the post-add page to do any initialization required for the new user, such as adding their user id to the database.

So, now that the postadd page is gone, you need to use a different approach. The solution I used is to include code in canvas pages that tests if the user who’s currently viewing the page is in my database, and if not, I add them and do any required initialization. This adds a little overhead to your pages, so you might want to do it only on a few strategically selected pages that you know users will have to pass by as they interact with your app.

Another thing I noticed recently, but never got the chance to try, is the Post-Authorize Redirect URL. This seems to replace the post-add page, so you might want to try it before updating your application.

6. No post-remove page, either

Since the concept of adding and removing an app no longer applies, then it’s clear why Facebook won’t call this page anymore.

7. Allow users to add a profile box

Read this first:
http://wiki.developers.facebook.com/index.php/New_Design_Narrow_Boxes


With the new profile you can use new FBML tags to display a button that allows users to add your box to their profiles. Here is a sample code that you can add in your canvas pages to do this.

<fb:if-section-not-added section=’profile’>
    Add a box on your profile:
    <fb:add-section-button section=’profile’ />
</fb:if-section-not-added>

8. Allow users to opt-in to receive emails

 This one is easy, here is an example:

<fb:prompt-permission perms="email">
    Opt-in to receive emails from us
</fb:prompt-permission>

If the user has already granted that permission, this tag will render nothing.

9. The new Profile Boxes

Read this first:
http://wiki.developers.facebook.com/index.php/New_Design_Narrow_Boxes

If you’re not interested in allowing users to add your profile box to their Wall tab, then you can skip this step. You’re profile box will continue to show in the Boxes tab as usual. However, if you want to give the user the option to put your box on their main tab, then do the following change:

In your code where you update the user profile, change this:

    $facebook->api_client->profile_setFBML($markup, $uid);

To this:

    $profile_main = "put FBML markup for new box here";
    $facebook->api_client->profile_setFBML($markup,
        $uid, null, null, null, $profile_main);

Notice that we added new markup for the narrow box that shows on the main profile tab. This new box is limited to a max height of 250px, so you’ll probably need a different markup than what you use in the default profile box. Also, note that the profile_main markup should not have the fb:wide and fb:narrow tags.

10. Bonus Tips: The ‘jsonwrapper’ include

The new library includes the file jsonwrapper.php, which is for backward compatibility. If you’re using PHP 5.2, then you don’t need this and can save a few CPU cycles. Remove this line from facebookapi_php5_restlib.php

     include_once ‘jsonwrapper/jsonwrapper.php’;

This should cover the critical changes you need to make. However, if you like to utilize the new features that the new profile brings, then you need to read more about application tabs, info sections, the publisher API, and more. I’ll cover some of those in the next post as I implement them.

Useful URLs:

• Access your app on the new profile:
  http://apps.new.facebook.com/yourappname/
• Remove app authorizations for testing purposes
  
  http://www.facebook.com/privacy/?view=platform

References:

• New Design Platform Changes
  http://wiki.developers.facebook.com/index.php/New_Design_Platform_Changes

• New Design Integration Guide
  http://wiki.developers.facebook.com/index.php/New_Design_Integration_Guide