Our book, Essential Facebook Development, is now available.

The synopsis:
With more than 300 million active users, Facebook is the world’s #1 social networking platform. But developing successful Facebook applications presents unique challenges, both technical and nontechnical. Now, two of the world’s most experienced Facebook developers show you exactly how to meet those challenges. Essential Facebook Development offers insider guidance and up-to-the-minute best practices for the entire application lifecycle: design, coding, testing, distribution, post-launch monitoring, metrics, and even application marketing.

Using extensive real-world examples, John Maver and Cappy Popp reveal why some Facebook applications succeed brilliantly while others fail. Next, they walk through building a complete application using every major component of the Facebook platform. Maver and Popp thoroughly cover Facebook’s most important new features, including Facebook Connect, and provide extensive information available nowhere else–from measuring application success to monetization. Coverage includes

• Thorough introductions to Facebook’s current architecture, integration points, and development technologies
• Discussion of successful Facebook applications–and what makes them successful
• What every developer must know about Facebook’s Terms of Service
• Creating an effective application infrastructure
• Creating canvas pages with FBML and IFrames
• Adding support for profiles, application tabs, and messaging
• Incorporating JavaScript into Facebook applications with FBJS
• Integrating Facebook into external sites with Facebook Connect and the Facebook JavaScript Client Library
• Debugging techniques for Facebook applications
• Spreading, monitoring, and tuning applications

You can purchase the book from the following sellers and more:

Stay up to date on what is happening with Facebook development and the book by becoming a Fan on its Facebook Public Profile, subscribing to the blog on the book’s website, or following the book’s updates on Twitter.

Today Facebook presented a 6-month developer roadmap. Finally – it’s been frustrating as hell writing a book about Facebook and not knowing what was coming from them and when, not to mention staying abreast of all the changes for our clients. In their presentation Facebook said that there were not many or big changes being announced, but I beg to differ. Some of them are quite significant. I’ll be covering those changes over the coming weeks and how they will affect your business, personal, and application presences on Facebook. What’s great is that Facebook is actually giving developers a heads-up for the next six months, and making that information public to all. That’s fantastic. If only I had this before I started writing the book.

Let’s get to the meat of it.

What’s chopped? What’s not? The first  big change, for both developers and users, center around the Facebook Stream and communication channels. Facebook is offering a new one, which is big news, and taking away some old ones, which is, perhaps, bigger news…

The Stream

Notifications are dead. Both application-to-user and user-to-user. At least the way they work today. Ouch.

For those applications or companies that depend on these for growth this is a blow. What are notifications? They are the little lightweight messages that pop up in the Facebook user interface to let you know of some event happening in an application. They can be sent currently by applications on behalf of their users to their friends or other application users (in the case of user-to-user notifications) or from an application to its users directly (for application-to-user ones.) Facebook collects the recent ones in the bottom right of the Facebook window, as shown in the image on the left (usually filled with messages from Facebook, Living Social, or Mafia Wars.) All user-to-user notifications will be routed to the Inbox; however, there will be no way for applications to send anything on behalf of their users anymore without their consent.  Invitations/requests will also be routed ’somewhere’ into the Inbox. Which is fine since I cannot remember the last time time I have even looked at my requests. When they hit the 300-or-so mark I simply delete them all.  Those are all being routed to the Inbox in the near future.

Why kill notifications, one of the only ways left for apps to communicate with users without their consent? Simply put, they don’t work, except in very specific circumstances. Most of the time they are noise. A LOT of noise. Additionally, most people have no clue they even exist or where they live. Currently users have to keep track of five different communication channels in Facebook: invites/requests, messages (Facebook Inbox today), notifications, Feed stories (the stuff on your Wall and News Feed), and IM/Chat. They say it’s too much and no one is clear where to look for them. They’re right.

So basically one-to-one communications of all types Facebook wants to route to the Inbox: one spot for users to check messages targeted directly at them. Makes sense. Unclear how/if Chat will be affected if at all.

One-to-many communications will be handled solely by the Stream in the form of Feed stories published via the Open Stream API. And the automatically-published one-line stores that applications can publish to your Recent Activity section on your Wall? Also gone.

Honestly I think this is a great thing for users and for applications. Why? Because now more than ever developers and content providers are going to have to think about engagement first, before features, before copying the other guy, before writing a line of code. The only way for apps to really spread through the Stream is for users to interact with the stories that applications post there – meaning stories that application users *allow* them to post to begin with – either via the Like or Comment features.

The other big news on the communcation front is that Facebook will provide a means for developers to prompt their users for, and grant the right to store users’ real e-mail addresses. Also the right to store their first and last names most likely, though at the time of this post the details have not been hashed out. You heard that right. Facebook will allow applications to contact users directly without having to use Facebook as the intermediary. This is HUGE. And a huge boon for Facebook Connect developers for sure.

What do you think?

UI Changes : Dashboards, Counters, and the Death of the Profile Box

Facebook is changing the look and feel of the Home Page, at least. A long, narrow bar will contain entries very similar to the way the Facebook Application menu looks today. The screen shot to the right, though blurry, gives you the idea. It will contain the friend lists like it  does today but will also incorporate Bookmarks. And they’re finally giving developers an FBML <fb:bookmark/> tag so they don’t have to jump through hoops to get users to do so. Finally. They are also introducing UI menus they call ‘Dashboards’ that originally will be of two types: Applications and Games. Recommendations might make the cut as well. These are all in early mock-up stages but will potentially be easier ways for users to find new apps and games. There are no distinctions at this time between them.

To allow users to see when applications have notified them of something they need to act on – the way notifications do today – Facebook is introducing Counters to the right of bookmarked (only?) applications in this new UI bar. You can see them in the image to the right. Counters show the number of things ‘you need to deal with’ in the item their associated with. Presumably this would be user-to-user or application-to-user messages in the Inbox, for example.

The Facebook chrome is going to change (again) as well – new top nav, cleaner layout.

And oh the poor Boxes tab is finally meeting its maker. As developers we called it ‘Siberia’. If an app had a presence there its engagement was dismal, so this should be of no big surprise to anyone. One other interesting change is the change to profile or application tabs – they are going to be given much less real estate width-wise. I assume this is to compensate for the new left nav idiom? Anwyay they are going from 760->560 pixels in width.

Ethan hinted at some other (seemingly very significant) changes to the Profile page as well. They want to allow more sharing of content that makes your Profile more unique. That’s great – right now everyone’s looks identical except for the profile pic and potentially the one application profile box below the friends widget. They could not elaborate on these changes but suggested that they would involve some work for developers.

Platform Policies and Programs

Highlights here included an entirely new Facebook Developer site with completely rewritten Platform documentation, more social features focused on community. That’s great: the existing wiki is weak at best, pathetic at worst. Many of the most important pages became woefully outdated yet were locked from public editing (<cough>FBJS</cough>). They will be providing comprehensive how-to guides and walkthroughs and will also provide all the content they covered in the demo today. One other interesting thing is that they will be providing a ‘Health of the Platform’ section that will show how all (?!) the APIs are currently working in the wild and the current top bugs they are working on fixing, and those they expect you to work around. This will undoubtedly lessen the massive forum threads that alternate between ‘it works’ and ‘it doesn’t’ posts.

The gargantuan 14-page opus that comprises the Facebook Platform policies have been shrunk to 3. With screenshots showing best practices and examples of flagrant violations of policy. Fantastic!

Application and Page Insights will be updated and accessible through APIs. Darn, just about finished the app to scrape them dynamically.

Open Graph API

This is the next evolution of Facebook Connect it sounds like. Basically it was pitched as a way for ‘any web page’ to become a Facebook Fan Page/Public Profile through the use of what I assume are custom widgets or code in the Facebook Connect or Facebook JavaScript Client Libraries.

For example, let’s say as a brand I don’t want a Facebook Page. I’ve spent a lot of time cultivating an audience on an external site that I control and don’t want to fragment them by investing in a Facebook presence as well. The Open Graph API will allow me to add Facebook widgets and access their entire API allowing my users to become Fans of my EXTERNAL page – and have that show up on their Profiles WITHIN Facebook. These external pages will also show up in Facebook Search from within Facebook, just like they were Pages within the site. Developers will be able to publish Streams targeted directly at these Fans on the external site(s) that use the API. This will undoubtedly be an interesting area of development in the coming months. Along with direct email communication this will probably jolt Facebook Connect implementations into the stratosphere.

Questions Asked By the Audience

Some of these were very good so I’ve included them to the best of my knowledge:

Q: As part of it’s new interactive developer site is Facebook going to give developers a ‘vote’ on features for Facebook to add?

A: Um, no.

Q: What’s up with Facebook’s currency system? Any news?

A: Facebook credits (used in past to purchase Facebook Gifts) are still in use, but they have no ‘real’ announcements. They are testing whether or not to allow developers to use or accept them as currency in their apps but that’s about it for now.

Q: How are apps going to prompt for user email addresses? Extended permissions are painful today.

A: They know, they are going to collapse them into a fewer number of them that allow users and developers a more clear view of how they work and what they grant.

Q: Will counters only show up for bookmarked applications?

A: Yes

Q: Will ‘Publish to a Friend’s Wall’ still work?

A: Not been addressed; only changes they’ve made to the Stream have been the Open Stream API and that’s just been a week ago – no changes planned.

Q: Is Facebook killing the verified applications program altogether?

A: Yes! They are going to spend a lot of time and expense making sure ALL applications are up to the same level of quality as verified ones were.

Q: Any idea in the new Stream of which messages will get more visibility or prioritization (popularity?)

A: Likes and Comments are key – make sure that people want to Comment and Like them. This will ensure their spread. He was unsure of how this affects search rankings within Facebook search.

That’s about it, in a nutshell.

Thoughts? Questions?

Our publisher,  Addison-Wesley Professional, has graciously published ‘Rough Cuts’ -  that means they still need final edits – of the first five chapters of our upcoming book, Facebook Development: A Complete Guide to Smart Application Development for the Facebook Platform, on InformIT’s Safari Books Online. Rough Cuts allow readers to get access to the book before it’s published or purchase advance copies.

Here’s an excerpt:

Currently Facebook has over  250 million active users and offers well beyond 52,000 applications — and the rate at which new applications are launching is staggering. But there is a lack of up-to-date information about developing those applications effectively — particularly in the light of platform  modifications that have rendered many applications obsolete. This book provides instruction on using the latest Facebook platform features and  helps developers create and deploy successful Facebook apps, revealing what makes them successful, how to measure progress, and how to deploy changes that will maximize the application’s value…

Please give it a read and let us know if you have any thoughts, questions, or ideas about the book or the chapters.

Quick Transitions

Today Facebook launched a beta feature it calls ‘Quick Transitions.’ This feature supposedly results in faster load times for Facebook Platform Application canvas pages. It somehow uses Ajax to load them which keeps the browser from having to do a full page refresh to render the Facebook UI elements that surround every canvas page (like the Chat and Application menu, navigation bar, and ads, etc.)

I wanted to see what effect, if any, enabling this feature had on one of our popular Facebook applications, Doorbell. Since this application has over 300k active users a free speed boost sounded just fine with me!

First, to enable the feature go to the Application Settings for your app and click on the Canvas tab. You’ll see a set of two radio buttons at the bottom of the page labeled ‘Quick Transitions.’ Click the ‘On’ button. That’s it. If your application is iframe-based you have to also edit the URLs that govern page transitions. Here’s a shot showing where to turn it on:

Enabling Quick Transitions for a Facebook Application

Yes, But Does it Work?

In a word, no, at least not for me. Could it be the code? Perhaps. We use Facebook’s tab control to navigate between the canvas pages in our application currently. This could be the issue.

Server access logs show that the correct pages are being loaded;  however, the tab for the page never changes nor does its content load. The browser (Firefox, latest) simply sits there with an hourglass. It’s still responsive, but the canvas page content never shows. Noticed that Facebook passed along a few new GET variables as well, but they also appear to be modifying the URL for each tab’s link.

For example, here’s the link to our rankings page:

http://apps.facebook.com/myapp/?page=rankings&_fb_fromhash=xxxxx

The link changes after quick transitions are enabled. Here’s what my server’s access log shows (and it’s serving the content up perfectly: I get a 200/OK status code for it):

myapp/#/myapp/?page=rankings&_fb_fromhash=xxxxx&quickling[version]=xxxxx%3B0&nectar_impid=xxxxxx&nctrct=xxxxx

…and here’s the link that shows up in the browser’s address bar:

http://apps.facebook.com/myapp/#/myapp?page=rankings&_fb_fromhash=xxxxx&_fb_q=1&_fb_qsub=apps.facebook.com

I’d like to get this working to test how big a speed improvement you can expect to see on your canvas page loads. I know the feature is in beta so I’ll keep this post updated with my findings as I get them…

The new (as of March 2009 – who knows what next week holds) Facebook Pages have become more like regular Facebook profiles. The important thing to note for the purpose of this post is that they now have a Publisher that allows Page admins to set status messages for the page. And make no mistake  – these are status updates just like you would set on your own personal profiles. Why is this important? First, it allows you to handle Pages as just another source for status messages, secondly, it integrates Pages more fully into the Facebook Feed model, and finally it’s important to realize that it has created problems for some (see this for example.) Now that Pages are part of News Feed any status updates or posts made by a Page or will show up in your personal Feed. Obviously it makes sense to syndicate these status messages in as many ways as possible. But, the question is, how?

This post, first of a series on Facebook Pages, will begin the discussion by first talking about how you can get a Page’s status from the API.

How do you get the status for a Page via the API?

You can get the Page’s status by using one of the same API methods you do to get a normal user’s status – you just use the PageID as the UserID parameter in the call. You will need a valid Facebook Session key to do this, however! I’ll discuss what that means in my next post. Just remember that a Page cannot login to Facebook to get its own session key. To get that PageID you either snag it from Facebook’s POST variables (’fb_sig_page_id‘) that are sent to a Page app’s canvas page or copy it from the Page’s URL (if you are going to be using it in places that may not have access to the POST variable or need to store it.)

Here’s an overview of three ways of getting a Page’s status:

So which way is ‘best’?

It depends on what you need out of the status itself. For example, the first method above, using users_getInfo, only allows you to get the LAST status message for a given Page (or user.) For example it returns the following (PHP):

Array
(
    [0] => Array
        (
            [uid] => 714497440
            [status] => Array
                (
                    [message] => is writing a blog post about Facebook Fan Pages
                    [time] => 1237687152
                    [status_id] => 7066343802
                )
        )
)

The second method, status_get, returns more information about each status message. Additionally, it lets you return more than one.
For example, either of these would return the last 2 status messages for user 714497440

$facebook->api_client->status_get('714497440','2');
$facebook->api_client->call_method("facebook.status.get",
                                                   array(  'uid'=>'714497440',
                                                             'limit'=>'2')
);

The results are shown below in JSON format since the PHP client return value does not offer associative names for the data:

[
   {
      "uid":714497440,
      "status_id":70669311802,
      "time":1237687152,
      "source":6628568379,
      "message":"status message 0"
   },

   {
      "uid":714497440,
      "status_id":70669311802,
      "time":1237687152,
      "source":0,
      "message":"status message 1"
   }
]

Finally, using FQL allows you to filter down to only the relevant bit of information you need. For example, if you just want the ids of the last 5 statuses messages for a Page you can simply use this FQL query:

SELECT status_id FROM status WHERE uid = $pageID LIMIT 5

The beauty of the final approach is that it not only allows you to minimize the size of the return data from Facebook but it also can be used as part of the FQL preloading process that performs FQL queries before calling your canvas page. You still take the hit for the FQL call, but it save a round trip, and additionally removes the automatic sending of the currently-logged in user’s entire friend list as part of the Facebook POST variables sent to your page! This can cut down on traffic if your app users have large numbers of friends. Since the average friend count on Facebook now stands at 120 this could be significant for long-term bandwidth costs. NOTE: the status_get API call basically returns the same result as this FQL query:

SELECT * FROM status where uid = $pageID ...

Hopefully this gives you some insight into the basic involved with getting a Facebook Page’s status. In the next post I’ll talk about how you handle this because Facebook requires a valid session key from a logged-in user to call any of these APIs. This can cause problems, for example, when you have code that runs without user interaction (via a cron job to update a Page profile tab for example.)

Stay tuned…

This is a very handy feature, especially if you have to write your code in Actionscript 2 for which the Flash CS4 debugger is terrible, terrible, terrible. Trace messages are great but when your Flash .swf is running in a browser, and needs to (for instance if it is running on a Facebook application and needs to interact with Facebook real-time) but without using a tool – there are a few – or a custom Flash listener how can you see your trace messages?

Here’s how to log them to a file. Note that these instructions are different from what Adobe recommended for Flash CS3/ Flash Player 9. They have changed the rules a bit. Here’s how to get this working for Adobe Flash CS4 and the latest Flash Player (version 10.0.12.36 as of this post date.)

Uninstall your current Flash players

Go here and get Adobe’s Flash Player uninstaller. Do not try to uninstall your Flash players any other way unless you know exactly what you are doing. You will just screw things up. Close your browsers and run the uninstaller you downloaded.

Download and install the latest Debug Flash Players

Go here to get them. Close all of your browser windows first, then install the plugin version (for FF and plugin-based browsers) and the the ActiveX version for IE. This assumes you are running Windows. Follow instructions in previous link if you are running OSX or Linux.

Create the mm.cfg file

Again, this assumes you are running Windows. Open Explorer and go to the C:\Documents and Settings\[your username] directory. If you don’t have this directory check what your HOMEPATH environment variable is set to and browse to that directory instead. Create a text file in this directory named mm.cfg. Paste the following 2 lines of text into the file:

ErrorReportingEnable=1
TraceOutputFileEnable=1

Save the file.

The first line allows the Flash Debug player to write error and warning messages to the file, the second writes trace messages.

Create the flashlog.txt file

Well, let Flash do it for you.

• If you have Flash installed:

Go to wherever you installed Flash (usually C:\Program Files\Adobe\Flash CS4) and open the Players\Debug directory. Run the FlashPlayer.exe file. That’s it.

• If you don’t have Flash installed:

Run the flashplayer_10_sa_debug.exe file you downloaded above. Again, that’s it.

This step is required because the Debug Standalone Player is what initially creates the flashlog.txt file where all of your trace() messages will end up. To verify that it’s been created, look for it (in Windows) in C:\Documents and Settings\[username]\Application Data\Macromedia\Flash Player\Logs or the equivalent if you have some different install scheme.

Load your Flash file in a browser

You should see your trace messages output in all their glory in your flashlog.txt file. Ensure that you don’t have trace messages being stripped from your Flash file in your Publish Settings!

Notes and Gotchas

• By default ALL trace, warning, and error messages from ALL running Flash files in the current browser session are written to this file. It’s best, therefore to preface all of your trace messages with some tag or indicator that they are yours, and from a specific application. I usually use a constant that I preface all of my trace messages with for easy identification.
• Warnings and errors are very common in the file, you may want to set ErrorReportingEnable=0 in the mm.cfg file if you are just interested in trace messages.
• DO NOT RUN ANY ADOBE AIR APPLICATIONS WHILE YOU ARE TRYING TO GENERATE TRACE OUTPUT! This one nearly drove me mad! The Flash Debug Player WILL NOT write flashlog.txt file if an Air file is running so you won’t see any of your trace messages. Air files lock the flashlog.txt file when they run, effectively disabling all tracing. So, no matter how much you cannot live without it, make sure TweetDeck is not running (Twitter will wait, believe me) or you won’t see squat. =)
• If you want to monitor the file real-time without having to keep it open in an editor you can use cygwin’s TAIL command to follow the file in a console window. First, install cygwin, then open a console window (Start | Run | cmd.exe) and type:

          tail /F /N50 [your path to flashlog.txt]

The console window will scroll and fill with your trace messages as they happen. If you use Aptana for web development its TailView feature is really handy for this as well. If you don’t want to install cygwin or don’t have Aptana installed this post describes how to get the same effect.

I found flashlog.txt to be a lifesaver. If anyone has any questions, just let me know.

Here are my slides from my presentation this morning at GSP East. Please let me know if you have any questions.

You can also get them on slideshare here.

Here is my slide deck from GSP East workshop on creating a Bebo Application.
Link to Slideshare.com. The notes for each slide contain additional information useful in building your first application.
Post any questions below or on the Bebo Forums.

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.

          require_once "bebo.php";

   3. Your file needs to have some globals that define the project.

          $appVisibleName = "Example App";
          $appApiKey = 'copy API Key from the developer application page';
          $appSecret = 'copy API Secret from the developer application page';
          $appCallback = 'put in your callback url. Ex - http://myserver.com/favoritebirds/ ';
          $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.

          $bebo = new Bebo( $appApiKey, $appSecret );
          $userID = $bebo->require_add();

   5. Now you can display the page to them using some SNML.

       displayPage($bebo);
       function displayPage($bebo) {
           $userID = $bebo->user;
           $output = "Welcome back, <sn:name uid='$userID' useyou='false' />.<br/>
               You have a nice picture:<sn:profile-pic uid='$userID' linked='false'/>";
           echo $output;
       }

   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.

          updateProfile($bebo);
          function updateProfile($bebo) {
              global $appVisibleName;
       
              $userID = $bebo->user;
              $snml = "This is the $appVisibleName profile box of <sn:name uid='$userID' useyou='false' />
      			<br/><sn:profile-pic uid='$userID' size='square' linked='false'/>";
              $bebo->api_client->profile_setSNML($snml);
          }

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.

          publishStory($bebo);
          function publishStory($bebo) {
              global $appVisibleName;
              global $appBeboURL;
       
              $actor = $bebo->user;
              $title_template = "{actor} used <a href='$appBeboURL'>$appVisibleName</a>";
              $title_data = null;
              $body_template = null;
              $body_data = null;
              $body_general = "Everyone should try $appVisibleName. <a href='$appBeboURL'>
      			Install $appVisibleName today.</a>";
              $image1 = null;
              $image1Link = null;
       
              try {
                  $result = $bebo->api_client->feed_publishTemplatizedAction( $actor, $title_template,
      			$title_data, $body_template, $body_data, $body_general,
                  $image1, $image1Link,
                  NULL, NULL,
                  NULL, NULL,
                  NULL, NULL,
                  "");
              } catch( Exception $ex) {
              }
          }

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.

          $invitePageURL = getInvitePageURL($bebo);
          echo "<a href='$invitePageURL'>Would you like to invite some friends?</a>";
       
          function getInvitePageURL($bebo) {
              global $appApiKey;
              global $appBeboURL;
              global $appVisibleName;
       
              $beboInvitePage = "http://www.bebo.com/multi_friend_selector.php";
              // What the inviter sees
              $actionText = urlencode("Which friends do you want to invite?");
              $action = $appBeboURL;
              $type = urlencode("Invite");
       
              // What the recipient sees
              $acceptInviteButtonURL = $bebo->get_add_url($appBeboURL);
              $acceptInviteButtonLabel = "Add $appVisibleName";
              $acceptInviteButton = "<sn:req-choice url='$acceptInviteButtonURL' label='$acceptInviteButtonLabel' />";
              $content = urlencode("Hey, try out $appVisibleName. $acceptInviteButton");
       
              $sig = 0; // update with the signature tool. 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.
              // If you change the invite text, you will have to regenerate the sig above
              $invitePageURL = "$beboInvitePage?sig=$sig&#038;api_key=$appApiKey&#038;content=$content&#038;type=$type
      			&#038;action=$action&#038;actiontext=$actionText&#038;invite=true";
       
              return $invitePageURL;
          }

Here is the completed sample:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <?php
    date_default_timezone_set("America/New_York");
 
    require_once "bebo.php";
 
    // Global definitions for your app
    $appVisibleName = "Favorite Birds";
    $appApiKey = "copy API Key from the developer application page";
    $appSecret = "copy API Secret from the developer application page";
    $appCallback = "http://myserver.com/favoritebirds ";
    $appBeboURL = "http://apps.bebo.com/favoritebirds/";
 
    ///Main Entry Point ///
    // Force everyone to add the application.
    // If they have already added it, then display the page
    $bebo = new Bebo( $appApiKey, $appSecret );
    $userID = $bebo->require_add();
    displayPage($bebo);
 
    // Update the user's profile
    updateProfile($bebo);
 
    // Publish a news story
    publishStory($bebo);
    ///End Main Entry Point ///
 
    function displayPage($bebo) {
        $userID = $bebo->user;
        $output = "Welcome back, <sn:name uid='$userID' useyou='false' />.<br/>
            You have a nice picture:<sn:profile-pic uid='$userID' linked='false'/>";
 
        // Add the link to the invite page
        $invitePageURL = getInvitePageURL($bebo);
        $output .= "<br/><a href='$invitePageURL'>Would you like to invite some friends?</a>";
        echo $output;
    }
 
    // returns the url for the Bebo standard invite page
    function getInvitePageURL($bebo) {
        global $appApiKey;
        global $appBeboURL;
        global $appVisibleName;
 
        $beboInvitePage = "http://www.bebo.com/multi_friend_selector.php";
        // What the inviter sees
        $actionText = urlencode("Which friends do you want to invite?");
        $action = $appBeboURL;
        $type = urlencode("Invite");
 
        // What the recipient sees
        $acceptInviteButtonURL = $bebo->get_add_url($appBeboURL);
        $acceptInviteButtonLabel = "Add $appVisibleName";
        $acceptInviteButton = "<sn:req-choice url='$acceptInviteButtonURL' label='$acceptInviteButtonLabel' />";
        $content = urlencode("Hey, try out $appVisibleName. $acceptInviteButton");
 
        $sig = 0; // update with the signature tool. 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.
        // If you change the invite text, you will have to regenerate the sig above
        $invitePageURL = "$beboInvitePage?sig=$sig&#038;api_key=$appApiKey&#038;content=$content&#038;type=$type&#038;action=$action&#038;actiontext=$actionText&#038;invite=true";
 
        return $invitePageURL;
    }	
 
    function updateProfile($bebo) {
        global $appVisibleName;
 
        $userID = $bebo->user;
        $snml = "This is the $appVisibleName profile box of <sn:name uid='$userID' useyou='false' />
			<br/><sn:profile-pic uid='$userID' size='square' linked='false'/>";
        $bebo->api_client->profile_setSNML($snml);
    }
 
    function publishStory($bebo) {
        global $appVisibleName;
        global $appBeboURL;
 
        $actor = $bebo->user;
        $title_template = "{actor} used <a href='$appBeboURL'>$appVisibleName</a>";
        $title_data = null;
        $body_template = null;
        $body_data = null;
        $body_general = "Everyone should try $appVisibleName. <a href='$appBeboURL'>Install $appVisibleName today.</a>";
        $image1 = null;
        $image1Link = null;
 
        try {
            $result = $bebo->api_client->feed_publishTemplatizedAction( $actor, $title_template,
			$title_data, $body_template, $body_data, $body_general,
            $image1, $image1Link,
            NULL, NULL,
            NULL, NULL,
            NULL, NULL,
            "");
        } catch( Exception $ex) {
        }
    }
    ?>

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

    ///Main Entry Point ///
    // An existing user will have the fb_sig_in_canvas variable set, unless they are removing
    if (isSet($_POST) && isSet($_POST['fb_sig_in_canvas'])) {    
 
        //  Bebo will pass their user id and that they have added the application
        if ( isSet($_POST['fb_sig_user']) && $_POST['fb_sig_added'] == 1 ) {
            $userID = $_POST['fb_sig_user'];
 
            // If the user has just installed, Bebo will pass installed as a GET parameter
            if ( isSet($_GET) && isSet($_GET['installed']) ) {
                newInstall($userID);
            }
 
            // Normal users will go through here, so display the page
            $bebo = new Bebo( $appApiKey, $appSecret );
            displayPage($bebo);
 
            // Update the user's profile
            updateProfile($bebo);
 
            // Publish a news story
            publishStory($bebo);
        }
    }
 
    // If you set up your own post add handler, then you must handle the add request the way you want,
    // and then redirect back to your Bebo URL. If you don't specify a post add handler, Bebo does this for you.
    else if ( isSet($_GET) && isSet($_GET['installed']) ) {
          $bebo = new Bebo( $appApiKey, $appSecret );
          newInstall($bebo );
          $bebo->redirect($appBeboURL);
    }
    // If you specify a post remove URL, then Bebo will call it with this POST variable.
    // After this call, you won't get anything else from this user unless they re-add your application
     else if ( isSet($_POST) && isSet($_POST['fb_sig_uninstall']) ) {
        $userID = $_POST['fb_sig_user'];
        uninstallUser( $userID);
    }
 
    // 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
    // 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
    // the existing user path above
    else {
        $bebo = new Bebo( $appApiKey, $appSecret );
        $bebo->require_add();
    }
 
    // Handle a new user installation
    function newInstall($userID) {
        // We can use the SNML to say hello to the user
        $output = "Hello, <sn:name uid='$userID' useyou='false' />. Thanks for adding the application!";
        echo $output;
    }
    function uninstallUser($userID) {
        // You can't actually display anything to the user, or redirect them.
        // All you can do is clean up inside your application.
 
    }	
 
    ///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.

I came across this issue today where I was getting an error when trying to add the <Fb:page-admin-edit-header/> to a canvas page of a page-only app.
The app was installed on a Facebook Page of which I was an admin.

Basically I had the following situation:

[0] canvas page that had <Fb:page-admin-edit-header/> rendered correctly at top when the canvas page was first hit

[1] canvas page had a simple non-Ajax form that submitted back to itself via POST

[2] POST url just contained URL of page

When I submitted the form, I kept getting the following error:

———————
Errors while loading page from application
Runtime errors:
fb:page-admin-edit-header can only display on a fbpage application.
There are still a few kinks Facebook and the makers of Accountability Journal-cp are trying to iron out. We appreciate your patience as we try to fix these issues. Your problem has been logged – if it persists, please come back in a few days. Thanks!
———————

I verified that the app was indeed a ‘page-only’ app, and that I had admin rights to the Facebook Page on which it was installed.

It seemed to me that this app was working perfectly until today, though I may be wrong about that…

It turns out that you MUST add the ‘fb_page_id=[pageID]‘ URL param to the POST URL. Even though all of the FB variables were present in the original POST (fb_sig_page_id, fb_sig_is_admin=1, etc.) it appears that you must still provide the URL param in order for the FBML processing to insert the <Fb:page-admin-edit-header/> correctly.