Flash Facebook Cookbook: Over 60 recipes for integrating the Flash Platform applications with the Graph API and Facebook.

You can set up your application as soon as you're registered as a developer with Facebook. To register as a developer you first need a Facebook profile. You've probably already got one, but you'll probably want to create at least one other Facebook account for development or testing purposes. I'm sure your existing Facebook friends won't appreciate a wave of "test message" spam in the near future.

Once you've logged in with the Facebook account you want to use for development, go to URL: http://www.facebook.com/developers/ to add the Facebook Developer application to your profile.

From the Facebook Developer center you can see the latest news from the Facebook developer blog, as well as useful links for developers (Documentation, Privacy Polices, Rules, and so on).

Click on the link + Set Up New App or go to the following website address: http://www.facebook.com/developers/createapp.php to start the application setup process.

If you just want to get up and run as fast as possible, the minimal amount of data that's needed to register a new application is its name.

There's far more information you can add, such as application icons, description, contact e-mail addresses, and support URLs—all pretty simple stuff, and you can always return to the settings screen to change or update things later on.

Once you've entered your application name (and any other information you wish) save your changes and you'll get a screen containing the following information:

Now that we've got ourselves an API Key, we can start using it in requests to the Facebook Graph API. We'll also need the Application ID, so make a note of that, but the Application Secret is something we don't actually need for any of the recipes covered in this cookbook.

All applications that integrate with Facebook aren't actually part of Facebook; they're an external application, and that's true for every third-party application that you might have seen appear within the Facebook interface (these are known as Canvas or Tab applications, depending on whether they're on their own page, or a Tab on another page). Technically, they are external websites that are loaded into the Facebook interface using an iframe element in HTML.

Without the API Key an application can't do anything other than retrieve the information that is publicly available. All other actions—such as requesting news feeds or publishing information to Facebook require—the end user to give your application the explicit permission to perform that action, with the API Key being what the Graph API relies upon when generating access tokens and authorizing requests.

Our application can request new permissions at any point, and similarly the end user can modify or reject our application permissions at any point, so generating an access token and passing it in all data requests is an easy way for Facebook to maintain the user's control over their data access.

To get a broader overview of the settings that can be changed for a Facebook application, the best place to look is the Developer Documentation, which is available online on the Facebook Developer center: http://developers.facebook.com/docs/.

There's no single page which gives a description of the settings, but rather the information is distributed around the pages where it's actually relevant.

When we set up an application on Facebook, it also sets up a Profile Page specifically for that application—similar to a Facebook page (but not exactly the same)—and devoted to our new application.

To download the SDK from Git, we need to have Git installed on your computer, which can be downloaded and installed from the URL: http://git-scm.com/.

This command will create a new folder with the name 'facebook-actionscript-api' and within that, create three key folders—docs, examples, and src. Unsurprisingly, these folders contain the source code for the library, the documentation for the library, and several sample applications, respectively.

The download locations for this recipe, and the source code for the Facebook SDKs which form the backbone of the recipes in this cookbook, point to Git repositories which are hosted by GitHub.

The source code for this repository is itself originally based on the official version of the SDK which is hosted on Google code, but it has been extended and expanded by other developers, (primarily Mark Walters, of http://yourpalmark.com/). The advantage of using our community-driven version of the SDK over the official one is that the source code is traditionally updated much more frequently, and includes a wide array of value-object classes, which the official version of the SDK does not yet include.

Not sure which version of the SDK is best for your project?

Within your project structure you will, by default, have a libs folder. Copy your downloaded SWC file into that folder, and at a basic level, that's all there is to it.

The classes from the Facebook ActionScript 3 SDK will now be available to your project—you should get auto-complete code suggestions as you type, and more importantly, be able to compile your code!

An SWC file is a compiled set of source files—which could be ActionScript source code or symbols and images—and is a useful way of making your source code available for others to use, while still protecting the actual original code. Anyone with the SWC can get access to the classes it contains and all their properties and methods, but can't actually see the code behind those methods. Of course, protecting the code isn't a huge concern for the Facebook ActionScript 3 SDK, as we can get all of the source code from other sources anyway.

The great thing about using a SWC file is that it minimizes the clutter of source files in your project—you don't need to include anything more than the SWC, whereas if you wanted to use the actual source files, you'd need to add 20-odd additional ActionScript files. That might not sound bad, but when you start using the source-code versions of multiple ActionScript libraries, you can easily end up with 10, 20, 50, or more ActionScript files that aren't actually written by you for this project.

Another little plus with SWC files are that they're precompiled, which theoretically means lower compile times for your project. I don't think it actually makes much of a difference for this SDK, but every little bit helps I guess!

What about the downsides of SWC files? Well, the main downside of a SWC file is also partially the reason it exists—that you can't see the actual source code. If you want to browse through the source code, but still get the advantages of using a SWC file in your project, follow the next recipe Including the Facebook ActionScript 3 SDK as a Flash Builder library project.

If you're using a SWC exclusively then you'll be flying blind if you should trigger errors on the classes you don't have the source code for, and will be presented with a dialog similar to this:

Informative, but really not helpful when you're trying to find out where your code is breaking down. Luckily there's a solution for that, and it is by linking source files to an included SWC.

Of course, when it comes to Runtime Errors, it's more likely that the error is in your code, rather than the Facebook ActionScript 3 SDK. Linking to the source is more about helping you find and debug your own errors, rather than searching for errors in the SWC.

Linking source files to an included SWC

Before we start out, it's important to note that linking source files to an included SWC file doesn't actually have any effect on the SWC itself. Instead, what we're doing is giving Flash Builder the location of the SWC's source files.

When Flash Builder tries to open your project in debug mode it will use this information, but it won't magically enable Flash Builder to recreate the SWC file for you—for that you need to set up the code as a Flash Builder library project (which is, coincidentally, the subject of the next recipe).

Once you've downloaded the Facebook ActionScript 3 SDK source files, place them in a sensible location somewhere on your computer—it doesn't matter where exactly, only that you remember the location.

Open your project preferences screen, and switch to the tab Flex Build Path and within that, Library path:

In the preceding screenshot, you can see the GraphAPI_Web_1_0.swc file, and underneath that you can see there is a Source attachment option—double-click on that to open a new window, labeled Edit Folder Path:

From this dialog you can select the location of the source files for the SWC. There won't be any visual confirmation whether the location you've selected is correct or not, but when you start coding or debugging, you should be able to explore the source code of the classes in the SWC, and see far less of the Code Navigation Error dialog.

Once the web project is added as a library for the desktop library project, both of those projects should be able to compile, and that's it for this recipe.

The complexity in this setup is just realizing that the Desktop version of the SDK is not a standalone library, and does, in fact, require all of the code from the web version. The source code files aren't duplicated for both versions because that would make things more complex to manage, and rather than merging the two sets into a single library project, we have to set things up in a way that keeps all of the AIR-specific source code in its own project.

Both versions of the Facebook ActionScript 3 SDK—Web and Desktop—rely on a core set of classes. The source code for the web version of the library contains all of these classes, whereas the desktop version of the library contains only the classes that require the AIR libraries, which is why it needs to be set up like this—to inherit those core files from the web project.

The original release version of the Graph API—version 1.0—included an additional JavaScript file—the FBJSBridge.js file. Since version 1.5 of the SDK there's no need for this additional JavaScript file—the Facebook ActionScript 3 SDK works to inject the original contents of that file into the containing HTML page, removing the necessity for those additional files, leaving only the ActionScript SDK as a requirement.

For our Flash Player application to integrate with Facebook, we will need some form of HTTP server, so that we can run our application from an http://-based URL, rather than simply launching a file from a local folder on your computer. Ideally we need a live, publicly-accessible domain under our control, and we'll configure our Facebook Application to use pages on that domain as the basis for our Canvas and Tab applications.

In addition, if we can, it would be most efficient (but not essential) to have an HTTP server set up on our local machine—allowing us to test and debug our Flash Player applications locally, without having to re-upload files to a remote site every time we need to test new functionality.

The web-based version of the Facebook ActionScript 3 SDK has been developed with a reliance on the Facebook JavaScript SDK being included in the containing HTML page—hence the requirement for us to extend our HTML template to incorporate this SDK.

When we add the script tag to our HTML template—using the URL http://connect.facebook.net/en_US/all.js as the source location—we are importing the Facebook JavaScript SDK from the Facebook.com servers. There are a few fringe benefits to loading the JavaScript SDK in this way—it keeps the SDK up-to-date and it helps with caching resources, but the primary reason for loading the SDK from the Facebook.com domain, rather than downloading it and packaging it alongside the HTML and SWF files on our own servers, is that this avoids a lot of potential for cross-domain scripting issues, and makes domain-restricted information such as cookies available to our application.

The addition of an HTML element with an ID of fb-root is part of the basic requirements for the JavaScript SDK, which are also discussed in more detail in the Facebook Developer documentation:

http://developers.facebook.com/docs/reference/javascript/

In short, the JavaScript SDK needs an actual element on the HTML page to hook into, and that element is one with an ID of fb-root—which is hardcoded into the SDK itself.

What we've done is in this recipe is simply to set up our project so that it will be able to work with the Facebook APIs, when it's uploaded to the domain that we've specified for our application, in the applications' settings, in the Facebook Developer center.