Flash Facebook Cookbook
Over 100 recipes for integrating the Flash Platform applications with the Graph API and Facebook.
Introduction
All third-party systems that work with data from Facebook do so through the Facebook API, which is a combination of REST-style techniques, OAuth 2.0, and an ever-evolving combination of web technologies, collectively titled by Facebook as the Graph API.
Facebook provides developers with a number of different code libraries through its developer portal, and of these the only one that’s completely client-side is the JavaScript SDK. But anything that JavaScript can do can be done by both ActionScript 3 and the Flash Platform, more or less.
You might think, having looked at the SDKs officially listed by Facebook in their developer portal, that you’d need to build a code library yourself but luckily for us, there’s already an existing, officially supported, ActionScript 3 library for working with the Graph API. This library, the Facebook ActionScript 3 SDK, is supported by both Adobe and Facebook, so you can be assured that it will be kept up-to-date and fully functional, even if there is a significant overhaul of the Facebook APIs—after all, who better to support this SDK than Adobe and Facebook themselves?
There’s no sense in recreating the wheel, as they say, so the examples in this article will be using the existing Facebook ActionScript 3 SDK almost exclusively for its recipes. We’ll also be using the Flex SDK 4.0 for our examples, as it’s a quick and easy way to construct user interfaces and put together working prototypes for our recipes. However, using Flex isn’t a requirement for the Facebook ActionScript 3 SDK to work—it’s just for the examples in this article. Integrating the Facebook SDK with a normal ActionScript-only project or a Flash Professional-based project is entirely possible—it will just inevitably require a little more time creating the interface, but the ActionScript 3 code behind it all will work pretty much the same.
Setting up a new application on Facebook
To access the full range of data available from the Facebook API, you need an API key, and for that, you need to set up an application on Facebook itself. To do this you need to set up an account on Facebook, and use that account to join the Facebook developer program.
Every Facebook application, whether it’s based on server-side languages (like PHP), or client-side technologies (like JavaScript or ActionScript), needs an API key to send and receive data through the Facebook API. Alongside the API key, the application also gets a unique Application ID that makes it possible for Facebook to keep track of what actions a user has allowed your application to perform with their data, and an Application Secret, which is used for authentication.
As well as giving you the ability to use more features of the API, setting up your Flash project as an application and promoting it through Facebook greatly improves the chance that users will discover your application organically through the social network. For example, status updates created by your application will all link back to the application’s Fan Page.
In this section, we’re going to go through the necessary steps to register a new application on Facebook, and what we actually need is the API Key, Application ID, and an Application Secret for Flash.
Getting ready
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.
How to do it…
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.
Your application name does not need to be unique—even for yourself. It’s acceptable to name two (or more!) of your applications exactly the same, as Facebook assigns every application its own unique Application ID. Good thing to, really—otherwise all the good names would likely be taken in a frantic bout of application name-squatting.
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 article.
How it works…
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.
There’s more…
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.
Downloading the Facebook ActionScript 3 SDK
There are two ways to get the source code for the Facebook ActionScript SDK—one is simply download a precompiled version of the source code, and for that all you need is an Internet connection.
The other way to obtain the source code is to download the very latest version directly from a source control repository.
There are in fact two main versions of the Facebook ActionScript 3 SDK. One is the ‘Official’ version of the SDK, hosted in a Subversion repository on Google code, maintained and updated by teams associated with Adobe and Facebook; and the other is more of a community-driven effort, stored in a Git repository and hosted on GitHub.
In this recipe and all of the recipes in this article, we will be working with a branch of the community-driven version of the Facebook ActionScript 3 SDK, rather than the ‘Official’ version of the SDK.
Getting ready
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/.
How to do it…
- If you have no desire to work with code which includes version-control information, both the precompiled SWC files and the raw ActionScript source code for the Facebook ActionScript 3 SDK can be downloaded from the following URLs:
- Within the pages at these URLs, select the Downloads button that appears in the top-left of the page, and you’ll get popup containing the download options:
- To download the raw ActionScript files, select the Download .zip option—listed under the DOWNLOAD SOURCE heading—or to download the precompiled SWC file, select the Facebook Web SDK.swc (or the Facebook Desktop SDK.swc) file—listed under the DOWNLOAD PACKAGES heading.
- Alternatively, if you have Git installed, you can clone the entire repository, including its past history and references to its original source location, with the following command-line statement:git clone [email protected]:psyked/facebook-actionscript-api.git
or
git clone [email protected]:psyked/facebook-air-api.git
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.
How it works…
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.
There’s more…
Not sure which version of the SDK is best for your project?
The Flash Player version, or the AIR version of the SDK?
In addition to the different download options, there are also two different versions of the Facebook ActionScript 3 SDK, and the one which we will use depends on whether we’re building desktop applications that run in Adobe AIR, or browser-based applications that use the Flash Player.
Both versions of the SDK are available for download from GitHub, but you can only use the Adobe AIR libraries with an Adobe AIR project, and the web-based libraries will only work properly with a web-based Flash Builder project that has the Facebook JavaScript SDK included in the HTML template, which is what we’ll look at in the next article, Preparing your Flash Player application’s HTML template for Facebook integration.
What if I want to build my own Facebook library?
There’s nothing ‘magical’ about this Facebook ActionScript API—everything it can do is built on standard capabilities of ActionScript 3 and the Flash Player. If you wanted to, it’s entirely possible to write your own code that works with Facebook without using this library, but why, as mentioned in the introduction, should you re-invent the wheel?
That doesn’t mean that the official API isn’t subject to an occasional change—the move by Facebook to the ‘Open Graph’ in 2010 is evidence of that—but it does mean that there’s always going to be someone maintaining the project and making sure it works with the latest version of the Facebook API.
