Create your first Flex and Facebook application – Part 2: Package and deploy as a desktop application

Note: This tutorial series was updated September 2011 to use the Adobe ActionScript 3 SDK for Facebook Platform, which uses OAuth 2.0. Facebook is requiring all applications to use OAuth 2.0 by October 1, 2011.

This tutorial series steps you through the process of building and deploying either a desktop or web application that retrieves, displays, and posts Facebook data. In Part 1, you built a local Flex and Facebook desktop application with Flash Builder and the Adobe ActionScript 3 SDK for Facebook Platform. In Part 2, you package and deploy this application as an AIR desktop application. In the process you will:

• Create and digitally sign an AIR file using Flash Builder.
• Use the AIR runtime to install the application as a desktop application.
• Create a native installer for a seamless desktop installation experience for the user.
• Post the application to a web server.
• Create a badge installer for seamless installation from a web page.
• Add the ability for the application to be updated using the Adobe update framework.
• Post an XML configuration file and an updated version of the application on a web server and then step through the end user process of updating the application.

Note: Facebook frequently changes to the site's user interface and API. This makes it difficult to keep this tutorial 100% up-to-date. Please be sure to add and read the comments at the end of this tutorial for any user interface or API modifications that might have occurred.

Start by modifying some of the application properties and then packaging it as an AIR file.

Open Flash Builder.

If you did not complete Part 1 of the tutorial series, you need to do the following:

• Complete the Register an application with Facebook section of Part 1.
• Download and unzip flex45_fbgraph_pt1_endproject.zip.
• Import the FXP this ZIP contains into Flash Builder. In Flash Builder, select File > Import Flash Builder Project, browse to the FXP file, and then Click Finish.
• In FacebookUserStatusAIR.mxml, replace the string YOUR APPLICATION ID HERE with the ID Facebook assigned to your application.

Modify application properties

Change the application ID used by the AIR runtime to uniquely identity the application and specify an application icon.

1. Right-click FacebookUserStatusAIR-app.xml in the Package Explorer and select Open With > Text Editor.

   Every AIR application contains an application descriptor file which is used by the AIR runtime when installing and launching the application. It contains information about the application (like its name, id, description, file icons, and so on) and information about the initial operating system window to load the application SWF into when the application is launched (its size, position, and so on). See the AIR documentation for more details about the application descriptor file.

2. Locate the id element and change it from FacebookUserStatusAIR to com.adobe.samples.FacebookUserStatusAIR. This ID is used by the AIR runtime to uniquely identify the AIR application. To guarantee a unique name, use reverse domain name notation as done here.

3. Locate the name and filename elements and change them to Facebook User Status.
4. Locate the icon element and uncomment it.
5. Set each image subelement to the corresponding PNG file in the images folder.

6. Save the file.

Create an AIR file

Next, use the Flash Builder ADT (AIR Developer Tool) to package and sign the desktop application.

1. Select Project > Export Release Build.
2. In the Export Release Build dialog box, set the Project to FacebookUserStatusAIR, the Application to FacebookUserStatusAIR.mxml, the Export to AIR folder blank, the Base filename to FacebookUserStatusAIR, and export as a signed AIR package (see Figure 1).

3. Click the Next button.
4. In the Digital Signature screen of the Export Release Build dialog box, click the Create button (see Figure 2).

You cannot package and distribute an AIR application withouta digital signature. The digital signature has two main purposes: to providesignificant assurance to your users that you are a trusted signer whose codewill not do anything malicious to their computers and that the application theyare installing has not been accidentally or maliciously altered since it waspackaged.

AIR code-signing certificates are sold by a number ofcompanies, including ChosenSecurity, GlobalSign, Thawte, and Verisign;certificates are typically only sold to registered companies and the processincludes submittal and verification of multiple company documents. When youinstall an AIR application, the name of the publisher associated with a trustedcertificate is displayed in the installation dialog box. If you create your owncertificate as you are doing here, the publisher name is displayed as Unknown.In general, you should never install applications that have a publisher ofunknown (although many people do). Creating your own certificate is useful fordeveloping applications. As well, AIR still uses this self-signed certificate toverify that the AIR package has not been altered since it was signed. Refer tothe AIR documentation for more information about digitallysigning AIR applications.

5. In the Create Self-Signed Digital Certificate dialog box, enter your name as the Publisher name, enter a password, confirm the password, set the type to 2048-RSA,v and then click Browse to navigate to a location to save the file and save it as YourLastName.p12 on your computer (see Figure 3).

6. In the Create Self-Signed Digital Certificate dialog box, click OK.
7. Back in the Digital Signature screen of the Export Release Build dialog box, select Remember password for this session, and uncheck Timestamp.
8. Click the Package Contents button.
9. On the Packaging Settings page, see that the AIR package will contain the SWF, the application descriptor file, and the icon images.
10. Click Finish.
11. Locate the AIR file in the Package Explorer (see Figure 4).

One way to distribute your application is to simply distribute this AIR file you just created. In order to install the application, however, the user must have the AIR runtime already installed and have the proper version needed to install this application. You are going to install the application using the AIR file right now as it is the simplest install process, but you will learn a better way to distribute the application using native installers and installation badges in the following sections.

1. Unless you have done so already, download and install Adobe AIR. You need to have the AIR runtime installed before you install an AIR application.
2. In Flash Builder, double-click the FacebookUserStatusAIR.air file in the Package Explorer to install it.
3. In the Application Install dialog box, click Install (see Figure 5). Note that the Publisher says UNKNOWN because you self-signed the application and did not use a certificate purchased and verified by a company that issues code-signing certificates.

4. On the Installation Preferences screen, click Continue. The application should be installed in the location you selected and should launch.
5. Look at your task bar or dock; you should see the icon you specified for the application (see Figure 6).

6. Navigate to your Application or Program Files directory. You should see your AIR application. On Windows, you can also find your application in the control panel and the Start menu.
7. In the application window, click the login button and log in to Facebook. You should see your user information displayed as before (see Figure 7).

8. Close the application.

To make sure the user has the right version of the AIR runtime installed before installing the application, you can create native or badge installers. Both check to make sure the correct version of the AIR runtime needed to run the application is installed before installing the application. If it is not, the required version of the AIR runtime is first downloaded and installed. In this section, you make a native installer to install from the desktop. In the next, you make a badge installer to install from a web page.

To create a native installer, you use the same ADT tool in Flash Builder that you just used to create the AIR file. You can only create a native installer for the operating system you are using. To create native installers for other operating systems, you need to install and use Flash Builder on each of those other operating systems.

1. Select Project > Export Release Build.
2. In the Export Release Build dialog box, set the Project to FacebookUserStatusAIR, the Application to FacebookUserStatusAIR.mxml, and select Signed native installer (see Figure 8).

3. Click the Next button.
4. On the Digital Signature page, make sure the certificate you previously created and its password are entered and click Finish.
5. Locate the native installer in the Package Explorer (see Figure 9).

6. Double-click the AIR file you created in the last section and in the Application Install window that opens, click Uninstall (see Figure 10), and then Finish.

7. In Flash Builder, double-click the native installer file you just created and then step through the installation process for your operating system. For example, on a Mac, double-click the Install Facebook User Status icon (see Figure 11).

If the user is online and does not have the required version of the AIR runtime installed, she will get a dialog box to grant permission to install the runtime (see Figure 12).

If the user is offline, the AIR runtime cannot be downloaded so the user will instead get a message that she needs to install Adobe AIR before she can install the application (see Figure 13).

8. Close the application.

You can create seamless installation experiences for users by creating and distributing native installers or by creating and deploying installation badges on web pages. Adobe provides an HTML template page for creating badge installers. All you need to do is edit this file and then deploy your badge along with the AIR file it references on a website. This badge allows for an image to be loaded into the button and for the color of the badge and the button to be changed.

Use an existing installation badge

First, use an existing installation badge to see how it works.

1. In a browser window, go to the Tour de Flex.
2. Click the installation badge (Install Now) for Tour the Flex in the upper right of the page (see Figure 14), and step through the installation process.

Place the AIR file on a web server

To create your own badge installer, the first thing you need to do to is to put your AIR file on a web server so you can specify a URL to download it from in the badge installer. You will place additional files on the web server in later steps.

1. Place the AIR file on a local or remote web server.
2. In a browser, browse to the URL for the AIR file, make sure the file can be successfully downloaded, and then copy the URL. You will paste this location into the badge HTML page shortly.

Create the badge HTML page

Next, modify the HTML template page for creating the badge installer.

1. Navigate to the latest SDK folder in the Flash Builder install directory on your computer. An example location on a Mac would be /Applications/Adobe Flash Builder 4.5/sdks/4.5.1/ and on Windows C:\Program Files\Adobe\Adobe Flash Builder 4.5\sdks\4.5.1\.
2. Open the /Adobe Flash Builder/sdks/x.x.x/samples/badge/ directory and look at the files it contains.

The default_badge.html file is a template file for creating badge installers. You make changes to this file and then post it on your server or more typically, copy its HTML code and place it inside a web page on your website. The default_badge.html file references the badge.swf file and the AC_RunActiveContent.js files.

3. Copy these three files: default_badge.html, badge.swf, and AC_RunActiveContent.js.
4. Return to Flash Builder, right-click on the FacebookUserStatusAIR project in the Package Explorer, and select Paste. You should now see the files in your project (see Figure 15). You don't actually need to place the files in your project; it is just convenient for working on them and then deploying all the files to a web server.
   

5. Right-click on the default_badge.html file and select Rename.
6. In the Rename resource dialog box, enter a new name of fb_badge.html and then click OK.
7. In the Package explorer, right-click on fb_badge.html and select Open With > Text Editor.
8. Locate the title tag on line 4 and change the page title to Facebook User Status Application Installer Page.

9. Locate the required version properties on lines 25, 27, and 29 and change them to require Flash Player 10.2.0 (or whatever version is required by the SDK you are using).
   

10. Locate the flashvars variable on line 59 and change the appname, appurl, airversion, and imageurl variables to the appropriate values.

The appname is the name of the application that will be displayed in a message under the install button if the AIR runtime is not present.

The appurl is the URL of the AIR file on the server. For appurl, use the URL for the location of your AIR file on your web server. You must use an absolute, not relative, URL.

The airversion is the version of the AIR runtime required. Your application is using AIR 2. You can find this value in the FacebookUserStatusAIR-app.xml file.

The imageurl is the URL of an image to display in the badge interface. For imageurl, you can specify a relative or absolute URL. Use the fb_status_app_icon128.png file in the project's images folder. In the code example above, a relative URL is specified and you just have to post this image file in the same directory as the HTML page.

You can also specify some additional, optional variables. You can set buttoncolor to a six-digit hex value (or to transparent) to set the color of the button background and messagecolor to a six-digit hex value for setting color of the text message displayed under install button.

11. On line 63, change the name of the application and the location of the AIR file.

12. On line 91, change the name of the application and the location of the AIR file.

13. Save the file.
14. Copy the three badge files: fb_badge.html, badge.swf, and AC_RunActiveContent.js and place them on your web server.
15. Copy the fb_status_app_icon128.png file from the src > images directory and place it in the same directory on your web server.
16. Copy the AIR file and place it in the same directory on the web server.

Install from the badge

You are now ready to test the badge installation.

1. In a browser, browse to the fb_badge.html file that you placed on your web server, for example, http://stallons.com/facebook/userstatusAIR/fb_badge.html. You should see a badge with the image you specified (see Figure 16).

2. Click the badge.
3. In the Application Install dialog box, click Open (see Figure 17).

Because you already installed the application, you get the option to run, replace, or uninstall the application (see Figure 18).

4. If you do not see an Uninstall button, click the More Options link at the bottom of the window and then you will see an Uninstall button (see Figure 18).

5. Click Uninstall to uninstall the application so that you can then use the badge installer to reinstall it.
6. Click the Finish button.
7. Return to the browser and click the badge installer again.
8. In the Application Install dialog box, click Open. If the user did not already have the required version of the AIR runtime installed, the AIR runtime would have first been downloaded and installed.
9. On the installation confirmation screen, click Install.
10. On the installation preferences screen, click Continue. The application should be installed in the location you selected and should launch just as it did when you installed directly from the AIR file or the native installer.
11. Close the application.

Before you distribute a desktop application, you should build into it the ability to be updated in the future. The application needs a way to check and see if it should be updated and then have the ability to update itself (using the AIR runtime). In order to accomplish this, you need to add some logic to your application and put an XML file on your web server that has details for the latest version and location of the application. Your application checks this XML file periodically (whever you decide it should) to see if it needs be updated.

You add update logic to your application using an update framework created by Adobe that includes APIs and optional UI components for the update process. It provides the ability to periodically check for updates based on an interval or at the request of the user and to download AIR files (the updates) from a web server. It also provides information and messages to the user throughout the update process. You are going to use the default user interface provided with the framework in your application, but this interface can also be customized.

Create the update configuration files

You are going to create two configuration files. One will live on your web server and contains update information for your application including the latest version number and the URL for the corresponding AIR file. The other is a local file, part of the application itself, and contains information about how the update should occur including how often and where to retrieve info about the latest application version (the location of the first file on the web server).

1. In Flash Builder, select File > New > Other and in the New dialog box, drill-down to General > Untitled Text File and click Finish.
2. Add the following text to the file but replace the url value to point to a location on your web server. You will create this v2 AIR file shortly.

3. Save the file as update.xml in the FacebookUserStatusAIR project.
4. Move or copy this file to your web server.
5. In Flash Builder, select File > New > Other and in the New dialog box, drill-down to General > Untitled Text File and click Finish.
6. Add the following text to the file except set the url element to match the name and location of the file you just created and put on your server.

The delay element sets the interval in days between periodic checks of new updates. The default value is 0 and means no periodic checks are done.

This config file can also contain a defaultUI element to control which dialog boxes are displayed during the update process. See the AIR documentation for more details.

7. Select File > Save As.
8. In the Save As Dialog box, drill-down to FacebookUserStatusAIR > src, enter a file name of update_config.xml, and click OK. You should see the file in your project (see Figure 19).

Add update functionality

Now you need to add code to your application to use the update framework to check the update config file on the server to see if it needs to be updated.

1. In the Package Explorer, expand the Flex 4.x branch and locate the applicationUpdater SWC files (see Figure 20).

The applicationUpdater.swc includes the basic update functionality without any user interface. The applicationUpdater_ui.swc includes the basic functionality of the update library but also includes a user interface for displaying update options. You are going to use the API of the ApplicationUpdaterUI class (air.update.ApplicationUpdaterUI) to initialize the update process. For more details on using this class, peruse its API in the ActionScript 3 Reference.

2. In the Package Explorer, collapse the Flex 4.x branch.
3. Return to FacebookUserStatusAIR.mxml.
4. Inside the Script block, declare a private variable called _appUpdater that is an instance of the ApplicationUpdaterUI class (air.update.ApplicationUpdaterUI). Be sure to choose ApplicationUpdaterUI from code-hinting so the import statement is written for you.

5. Inside the windowedapplication1_creationCompleteHandler() function, set the ApplicationUpdaterUI configurationFile property to the config file you created earlier in the data folder, update_config.xml.

The File class (flash.filesystem.File) is only available in desktop applications and an instance of it represents a directory or file on the user's computer. The app:/ refers to the application directory of the application, where the application was stored when it was installed. See the File class API in the ActionScript 3 Reference for more details.

6. Still inside the windowedapplication1_creationCompleteHandler() function, call the initialize() method of the ApplicationUpdaterUI class. This method initializes the update framework and if the delay that was specified in the update_config.xml file has expired, it starts the update process. Otherwise it restarts the timer (which is managed by the AIR runtime).

7. Inside the windowedapplication1_creationCompleteHandler() function, register to listen for the initialized event of the ApplicationUpdaterUI class (which is broadcast after the initialization is complete) and specify a handler updateInitializedHandler .

You register to listen for events in ActionScript using the addEventListener() function. You pass to it the name of the event you want to listen for (like click or initialized in this case) and a reference to the function that will be the event handler. Instead of using the string "initialized" as the name of the event, use the static constant of the UpdateEvent class equal to this string.

You can place the code before or after the initialize() call; code execution in Flash Player is single-threaded and the handler will never be invoked before all the code inside this function is executed. Be sure to select UpdateEvent form code-hinting so the import is written for you.

8. Inside the Script block, create a protected function updateInitializedHandler() that receives one argument of type UpdateEvent and returns nothing.

9. Inside the updateInitializedHandler() function, call the checkNow() method of the ApplicationUpdaterUI instance to start the update process and check for updates now

Normally, you would not need to execute any code once the updater is initialized. If the delay time has elapsed, the application will automatically check to see if it needs to be updated. In this case, however, the time will not have elapsed and we don't want to wait a day, so we are going to add code to check for updates now.

10. Save the file and run the application. You should immediately get a Check for updates dialog box (see Figure 21).

11. Click Check for Updates.
12. In the Update available dialog box, click Download now. You will get an error message because you have not yet created and posted the v2 version of the AIR application. You will do this next.
13. Click Close.
14. Close the application.

Package and install the application with update capability

Next you need to package and install this new version of the application which now has update capabilities.

1. Select Project > Export Release Build.
2. In the Export release Build dialog box, export the FacebookUserStatusAIR project to FacebookUserStatusAIR_v1.air (see Figure 22).

3. Click Next.
4. On the Digital Signature page, make sure your certificate and password are correctly entered and click Next.
5. On the Package Contents page, confirm that the update_config.xml file and the images will be included in the package (see Figure 23).

6. Click Finish.
7. In the Package Explorer, double-click the FacebookUserStatusAIR_v1.air file.
8. In the Application Install dialog box, click Replace to replace the existing version with this new version that has update functionality (see Figure 24).

9. Close the application.

Create, package, and post a new application version

Next, create a new version of the application to post to your web server. You are going to change the background color of the application in the new version so after the update process, you will be able to tell instantly that the application was updated.

1. Open FacebookUserStatusAIR-app.xml.
2. Locate the versionNumber node and change its value from 0.0.0 to 2.0.0.

3. Save the file.
4. Return to FacebookUserStatusAIR.mxml.
5. In the WindowedApplication tag, add a backgroundColor and set it equal to light gray (#e7e7e7).
6. Comment out the code inside the updateInitialized() function so the update check is not done every time the application is launched but instead by the delay you set in the update_config.xml file.

7. Save the file.
8. Select Project > Export Release Build.
9. In the Export release Build dialog box, export the FacebookUserStatusAIR project to FacebookUserStatusAIR_v2.air.
10. Click Finish.
11. Post the FacebookUserStatusAIR _v2.air to your web server. Make sure its name and location match what you specified in the update.xml file.

Run the application and update it

Lastly, run the application and update it to the new version.

1. In Flash Builder, double-click the FacebookUserStatusAIR _v1.air file to run the existing version of the application that was already installed.
2. In the Application Install dialog box, click Run Now. The application still has a white background and you should get a Check for updates dialog box.
3. Click Check for Updates.
4. In the Update available dialog box, click Download now (see Figure 25).

5. In the Install update dialog box, click Install now (see Figure 26).

6. The updated application should launch and it should have the new gray background (see Figure 27).

7. Close the application.

Where to go from here

In Part 2 of this tutorial series, you packaged and deployed your Flex and Facebook application as a desktop application. Specifically, you created and digitally signed an AIR file, packaged the application as a native installer, created and deployed a badge installer on a web server, and installed the application using all three. Finally, you added update capability to the application, created and deployed an updated version of the application, and tested the update mechanism.

To learn more about creating and customizing Flex applications, see the Flex documentation and the Adobe Flex Developer Center. To learn more about creating and customizing AIR applications, see the AIR documentation and the Adobe AIR Developer Center.

To deploy the application as an external web application, continue with Part 3 of the tutorial series, Modify and deploy as a web application.

To deploy the application as a web application on Facebook.com, continue with Part 4 of the tutorial series, Modify and deploy on Facebook.com.