back

Introducing the Adobe ActionScript 3 SDK for Facebook Platform

by Jeanette Stallons

The Flash Platform lets you build rich user experiences. The Facebook Platform lets you build rich social experiences. Put the two together, and you can build killer applications incorporating social capabilities in highly interactive, expressive, and responsive applications.

The development of combined Flash and Facebook Platform applications is made quicker and easier using the new Adobe ActionScript 3 SDK for Facebook Platform, a class library for facilitating the communication of Flash Platform applications with Facebook. The SDK has been completely rewritten (by gskinner.com for Adobe) to use the new Facebook Graph API, to use the OAuth 2.0 protocol for authentication and authorization, and to implement the Facebook SDK standard.

SDK overview

Using the Adobe ActionScript SDK for Facebook Platform, you can build three types of Flash and Facebook Platform applications: desktop applications, external web applications, and web applications on Facebook.com. The SDK contains two lightweight SWCs, FacebookGraphAPIDesktop.swc (11 classes, 33 KB) for building desktop applications and FacebookGraphAPI.swc (8 classes, 29 KB) for building both types of web applications. The main class for building AIR desktop applications is FacebookDesktop. The main class for building web applications is Facebook. Both have methods for creating and managing a user session and for making calls to the Facebook Graph API to retrieve and send data.

The SDK FacebookDesktop class

FacebookDesktop (com.facebook.graph.FacebookDesktop) extends AbstractFacebook (com.facebook.graph.core.AbstractFacebook) and is a singleton class with static methods for creating and managing a session and making Facebook API calls. You use the init() method to initialize the FacebookDesktop singleton with the application ID (assigned using the Facebook Developer application) and to check to see if a session already exists (the user is already logged in and the application has been authorized).

FacebookDesktop.init("THE APPLICATION ID",loginHandler);

The FacebookDesktop class uses a shared object (Flash Player's version of a cookie) with accessToken and expireDate properties to persist session information. The init() method checks to see if a shared object exists. If it does not exist, it is created. If it does exist and has an access token that has not expired, a call is made to the Facebook Graph API to retrieve the user data associated with the access token. A FacebookSession instance (com.facebook.graph.data.FacebookSession) is created and populated with the user information.

The first time a user accesses the application, a shared object and an access token do not exist and the user will need to log in to Facebook and/or authorize the application. To accomplish this, you use the login() method:

FacebookDesktop.login(loginHandler);

The login() method creates a new operating system window that displays the Facebook login page (see Figure 1). A popup window is necessary for security reasons so the user knows they are logging in to Facebook.

Pop-up login window for a desktop application.

Figure 1. Pop-up login window for a desktop application.

The login() method creates an instance of the LoginWindow class (com.facebook.graph.windows.LoginWindow) which extends the AbstractWindow class (com.facebook.graph.windows.AbstractWindow), which extends the Sprite (flash.display.Sprite) class and uses the HTMLLoader class (flash.HTML.HTMLLoader) to display the Facebook login and/or authorization page in a new operating system window. The LoginWindow class also uses the FacebookURLDefaults class (com.facebook.graph.core.FacebookURLDefaults) which stores all the URLs for communicating with Facebook including the OAuth URL, https://graph.facebook.com/oauth/authorize, that is loaded in this window.

If this is the first time the user is accessing this application, she must also authorize it to access her public data. The redirect is handled automatically as part of the Facebook authentication/authorization process and the popup window redirects to a Facebook authorization page (see Figure 2).

Pop-up authorization window for a desktop application.

Figure 2. Pop-up authorization window for a desktop application.

Once the session is successfully created, the shared object is created or updated, a call is made to the Facebook Graph API to retrieve the user data associated with this session's access token, and a FacebookSession instance is created and populated with the user information

When a Facebook user authorizes an application, the application can access the basic information in a user's profile including her name, profile picture, gender, and friend list. If the application needs to access other parts of the user's profile that may be private (even if they aren't necessarily), the application can request extended permissions by passing an array of the permissions to the login() method:

FacebookDesktop.login(loginHandler,["user_birthday","read_stream","publish_stream"]);

In this case, the authorization page now requests multiple permissions (see Figure 3). Extended permissions can also be requested after login using the requestPermission() method.

Pop-up authorization window for a desktop application with extended permissions.

Figure 3. Pop-up authorization window for a desktop application with extended permissions.

Once a session has been created, you use the api() method to make calls to the Facebook Graph API. Here is a call for retrieving a user's status messages:

FacebookDesktop.api("/me/statuses",getStatusHandler);

and one to post a new status message:

FacebookDesktop.api("/me/feed",submitPostHandler,{message:statusInput.text}, "POST");

The api() method uses the FacebookRequest class (com.facebook.graph.net.FacebookRequest) to instantiate new requests. If the API call only involves the exchange of text, the FacebookRequest class uses the URLLoader class (flash.net.URLLoader) and associated classes to make the Facebook API call. If files need to be uploaded or downloaded, it uses the FileReference class (flash.net.FileReference) and for uploading Bitmaps or ByteArrays, the PostRequest class (com.facebook.graph.utils.PostRequest) to format the files, and possibly the PNGEncoder class (com.adobe.images.PNGEncoder) to create a PNG image from BitmapData. Because all Facebook Graph API responses are JSON objects, the Facebook ActionScript SDK also includes a package of classes (com. adobe.serialization.json) for decoding and encoding JSON.

The FacebookDesktop class contains additional methods to retrieve the current user's session and to make calls to the old Facebook REST API as well as shortcut methods to load and format Facebook profile pictures, to delete Facebook objects, and to execute FQL queries.

The SDK Facebook class

Facebook (com.facebook.graph.Facebook) is the main class for building web applications. It is also a singleton class that extends the AbstractFacebook class (com.facebook.graph.core.AbstractFacebook) and has static methods for creating and managing sessions and making Facebook API calls.

The process for adding Facebook connectivity to an application using the Facebook class is very similar to that of using the FacebookDesktop class: you use the init(), the login(), and the api() methods. For web applications, though, the underlying login and authorization functionality is provided by a different mechanism. In desktop applications, the login() method simply opened the Facebook login page in a new operating system window and then closed the window and established the session after the user logged in and/or authorized the application. The corresponding action in a web application would result in a new browser window (or tab) opening, so the application would be in one browser window and the login page in another. After logging in in one browser window, the user would then need to complete an action back in the application (like clicking a button) to establish the session - not a very good user experience.

Instead of opening the Facebook login page in a new browser window, the Adobe ActionScript 3 SDK for Facebook Platform provides a seamless login process for the user by using JavaScript and the Facebook JavaScript SDK to create and display the Facebook login in a browser popup window (see Figure 4). This is similar to how external web applications were created using the previous version of the Facebook ActionScript API and Facebook Connect (which was the old brand name used for the user login experience achieved using the Facebook JavaScript SDK).

Pop-up login window for an external web application.

Figure 4. Pop-up login window for an external web application.

Wrapper pages for Flash Platform web applications must contain code to check for the correct version of Flash Player needed to run the application and embed the application. Typically, this functionality is provided using the open-source SWFObject JavaScript file. For applications using the Adobe ActionScript 3 SDK for Facebook Platform, the wrapper page must also include the JavaScript file, FBJSBridge.js (which contains a collection of JavaScript called by methods of the Facebook ActionScript API) and the Facebook JavaScript SDK (whose methods are called by the JavaScript methods in the FBJSBridge file). The FBJSBridge file is included in the SDK source, which you can download from the Google code repository.

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js">
</script>
<script type="text/javascript" src="http://connect.facebook.net/en_US/all.js"></script>
<script type="text/javascript" src="FBJSBridge.js"></script>

For external web applications, user login and application authorization are provided using the Facebook init() and login() methods just as for the FacebookDesktop class. You initialize the application with the Facebook singleton:

Facebook.init("YOUR APPLICATION ID",loginHandler);

and then call the login() method:

Facebook.login(loginHandler);

The Facebook methods call methods of the wrapper page that in turn call methods of the Facebook JavaScript SDK.

To add extended permissions, you pass a second argument to the login() method equal to an object containing information for modifying the login window (as opposed to the array of extended permissions you pass to the FacebookDesktop login() method):

Facebook.login(loginHandler,{perms:"user_birthday,read_stream,publish_stream"});

For web applications on Facebook.com, you can still include login and logout buttons if you want or you can remove them (and the calls to the login() and logout() methods) and let the user use the Facebook chrome to log in and out. Whether you include the buttons or not, the login flow is a bit different than for external web applications. If the user is not logged in or the application has not yet been authorized, you need to redirect the browser window to the Facebook authentication page instead of displaying it in a pop-up window. You can redirect the browser using the ExternalInterface class (flash.external.ExternalInterface) to call a JavaScript method:

ExternalInterface.call("redirect","THE APPLICATION ID", "user_birthday,read_stream,publish_stream","http://apps.facebook.com/THE CANVAS PAGE/");

The JavaScript method is included in the wrapper page:

function redirect(id,perms,uri) {
     var params = window.location.toString().slice(window.location.toString().indexOf('?'));
     top.location = 'https://graph.facebook.com/oauth/authorize?client_id='+id+'&scope='+perms+'&redirect_uri='+uri+params;				 
}

If you want the application to be accessible either as an external web application or on Facebook.com, both login schemes must be included and the proper one used for each case. One way to determine where the application is being accessed is to use JavaScript to check the URL of the top browser window. Applications accessed on the Facebook website are loaded into an iFrame and will have a different URL then when accessing the application on a non-Facebook server:

protected var topURL:String=ExternalInterface.call('top.location.toString');

Just as for desktop applications, once a session has been created, you use the api() method to make calls to the Facebook Graph API. The Facebook class, however, does not automatically make a call to retrieve user data once a session has been established; you must add the code to get the user data:

FacebookDesktop.api("/me/statuses",getStatusHandler);

The Facebook api() method uses the same underlying Flash Player and Facebook ActionScript SDK classes to make calls to the Facebook API as the FacebookDesktop class. The Facebook class also has the same additional methods: methods to retrieve the current user's session, to make calls to the old Facebook REST API, to load and format Facebook profile pictures, to delete Facebook objects, and to execute FQL queries. It also has additional methods to add, check for, and remove JavaScript event listeners for JavaScript events in the underlying Facebook library and to change the canvas size of applications on Facebook.com.

SDK controls

The SDK contains one control, Distractor (com.facebook.graph.controls.Distractor) that extends Sprite and creates an animated distractor that matches what Facebook uses (see Figure 5).

The Facebook Distractor control.

Figure 5. The Facebook Distractor control.

At this time, the SDK does not include any components for interacting with Facebook (like login or logout buttons). You need to create your own components and implement their functionality using the SDK and skin them yourself.

Development process using the SDK

To build a Flash and Facebook Platform application, you need to download and add the appropriate SDK SWC to your project and get an application ID using the Facebook Developer application. For desktop applications, you can then build, debug, test, and deploy the application just as you would any other application. For web applications, though, the process is a bit more complex. You need to specify additional application info in the Facebook Developer application and then post the application to a publicly available web server before you can test it.

For external web applications, you need to use specify a Site URL that corresponds to the folder containing the application SWF on your web server (see Figure 6).

Specify a Site URL for external web applications.

Figure 6. Specify a Site URL for external web applications.

For web applications deployed on Facebook.com, you need to assign a Canvas Page URL, the URL a user will enter to browse the application on Facebook.com, and a Canvas URL, the URL for the application on the external web server (see Figure 7). When the user requests the Canvas Page URL, the application will be downloaded from the Canavas URL and loaded into an iFrame in a Facebook web page.

Specify a Canvas Page and Canvas URL for web applications on Facebook.com.

Figure 7. Specify a Canvas Page and Canvas URL for web applications on Facebook.com.

Although you can currently specify the application to be either an iFrame or an FBML application, you should only use iFrame because Facebook is phasing out the use of FBML applications and is going to discontinue the ability to create them by the end of 2010. This streamlining of the application creation process is part of Facebook's effort to eliminate the differences between developing an application on and off Facebook.com.

Because you have to specify an application URL when registering the application (either a website URL or a canvas URL), the application must live at this location when you test it. With this version of the Facebook ActionScript SDK (unlike in previous versions which had the option of using the clunky login in a separate browser window), you cannot test the application locally. Because the code to work with the Facebook and FacebookDesktop classes is so similar, one development process is to first build a desktop application using the FacebookDesktop class and then once its working, to modify the code to use the Facebook class, to deploy the application to the server, and then to test it at that URL (either on Facebook.com or an external website). Whether you build the application first as a desktop application or not, to test the web application you must FTP the application and supporting files to a web server after every code change so it can be tested at the required URL.

Common techniques used to debug remote applications (since you cannot use your local debugger) include adding a TextArea control and adding text to it to trace values, to use popup boxes (like Flex Alert controls) to examine property values or display messages, or calling out to JavaScript and displaying Alert boxes or HTML text. A tool to examine the network responses from Facebook (like Firebug for Firefox) is also very useful so you can look at the properties and values of the objects returned by Facebook API calls.

Implementation of the Facebook SDK standard

One of Facebook's requirements to approve this ActionScript SDK was that it implement the Facebook SDK standard and match as closely as possible the Facebook JavaScript API. The upside of this, of course, is the syntactical consistency provided across the various API interfaces. The cost for this consistency, however, is that the ActionScript development differs slightly from what you typically use.

Specifically, the Facebook ActionScript SDK does not use the normal event-based model. Instead of explicitly registering to listen for events, you specify callback functions when invoking one of the API's asynchronous methods:

FacebookDesktop.api("/me/statuses",getStatusHandler);

The callback functions don't receive event objects, but instead usually receive two untyped objects, one if the method call succeeds and one if it fails:

protected function getStatusHandler(result:Object, fail:Object):void
{
    statusLbl.text=result[0].message;
}

Because the parameters of the callback functions are not strongly typed event objects as for typical ActionScript event handlers, you don't get the benefits of code-hinting and compile-time error checking for the arguments like you normally would.

Similarly, the ActionScript SDK also does not include value object classes for the different types of objects returned by Facebook (users, friends, photos, and so on). Thus to work with these objects, you need to look them up in the Facebook documentation (for example, see User or Photo) and/or use an HTTP monitor to look at the JSON data passed back and forth. For desktop applications, you can also use breakpoints and your IDE's debugger to look at properties of the returned objects.

An upside of not using strongly typed objects, however, is that it keeps the Facebook ActionScript SDK more general and therefore more easily able to absorb Facebook API changes – which are constant. The decision to not use strongly typed objects in the SDK was made for two reasons: so that it implemented the Facebook SDK standard and so that it would be easier to support future modifications and expansions of the Facebook Graph API.

Sample applications

Two Flash Platform applications deployed on Facebook.com that use the new Adobe ActionScript 3 SDK for Facebook Platform are FIFA Superstars and Glee Your Life.

FIFA Superstars is a social sports game that enables players to build and manage a team of the world's best soccer players and play against their friends (see Figure 8). Playfish, a leading developer of social games, developed the application using Flash Builder 4, Flash CS5 Professional, and the new Facebook ActionScript SDK.

Playfish's FIFA Superstars game.

Figure 8. Playfish's FIFA Superstars game.

Glee Your Life is an interactive application to promote the release of "Glee: The Complete First Season" on Blu-ray and DVD (see Figure 9). The application assigns a user a "Glee Theme Song" (either by having the user complete an interactive quiz or by retrieving the user's Facebook profile and using an algorithm to determine the best song) that she can post and have play in her news feed. Trailer Park, Inc. developed the application for FOX Home Entertainment using Adobe CS4 and FlashDevelop, an open-source code editor.

Fox's Glee Your Life promotional application.

Figure 9. Fox's Glee Your Life promotional application.

Examples of external web applications using the Flash and Facebook Platforms include Ben and Jerry's, RedBull Connect, and City Search. Examples of desktop applications include Seesmic for Facebook and Nomee.

Resources to get started

To get started using the new Adobe ActionScript 3 SDK for Facebook Platform, download the SDK and check out its sample applications and/or step through the tutorials on the Flex and Facebook Developer Center:

‹ Back