Adobe
Sign in My orders My Adobe

by Alex Liebert

Alex Liebert

Content

Created

29 May 2012

Page tools

ActionScript Adobe AIR Flash Builder Flash Professional gaming iOS Native extensions social networking

Prerequisite knowledge

Experience building games for iOS with Flash Builder or Flash Professional and Adobe AIR will help you make the most of this article.

 

Additional required other products

User level

Intermediate

Required products

With the GoViral extension for iOS from Milkman Games, you can rapidly integrate social networking support for Facebook, Twitter, and email into your mobile AIR application using ActionScript 3.

The GoViral extension for iOS is a completely native iOS solution that enables you to:

  • Integrate with the official Facebook app and website for authentication
  • Send Facebook invitations (recipients are directed straight back to your app or the App Store)
  • Access the entire Facebook Graph API through ActionScript 3
  • Use one-line functions for common Facebook tasks like invites and wall posts
  • Display native Facebook dialog boxes with the official Facebook iOS SDK
  • Send plain-text or HTML email messages to friends with image attachments
  • Post scores or other status updates to Twitter
  • Jumpstart development with a complete sample application, ActionScript 3 documentation, and a getting started guide

Setting up your app on the Facebook Developer site

This section covers setting up a Facebook mobile app in the Developer section of the Facebook website.

Before you can use the Facebook features of the extension, you'll need to create the app on the Facebook Developer site and register for a Facebook App ID.

  1. Go to http://developers.facebook.com. If you haven't already done so, register as a developer with Facebook to create your first app.
  2. After logging in, select Apps from the top menu (see Figure 1).
Figure 1. Click Apps in the top menu.
Figure 1. Click Apps in the top menu.
  1. Click Create New App (see Figure 2).
Figure 2. Click Create New App.
Figure 2. Click Create New App.
  1. In the Create New App dialog box, type a display name for your application and click Continue (see Figure 3).
Figure 3. Enter a name for your app.
Figure 3. Enter a name for your app.
  1. Complete the security check if prompted.

A Facebook App ID and App Secret have now been created for your application. Take note of the App ID; you'll need it later to configure your application with Adobe AIR.

Figure 4. Enter basic information for your app.
Figure 4. Enter basic information for your app.
  1. Complete the Basic Info section, including a contact email address. Be sure to select a Category for your app.
  2. Click Native iOS App to expand the iOS Section.
  3. For iOS Bundle ID, type your iOS Application Bundle ID. This ID will need to match both the ID you used in iTunes Connect for the app, and the ID you use in your AIR application descriptor file.
Figure 5. Enter the iPhone App Store ID.
Figure 5. Enter the iPhone App Store ID.
  1. For iPhone App Store ID, you'll need to enter the numeric iTunes App Store ID for your app. If your app is not yet live on the App Store, you can enter a different app's numeric ID here for now. Later, when your app has been approved by Apple, you can replace it with your own numeric ID. If you need a numeric ID to use temporarily during development, you may use 331975235, which is the ID for Adobe Photoshop Express iOS (see Figure 5).
  2. Enable the options labeled Configured For iOS SSO and iOS Native Deep Linking.
  3. Click Save Changes to complete the Facebook set up.

Including the GoViral API Library

The next step is to add the GoViralAPI.swc library (or com.milkmangames.nativeextensions.GoViral.ane, for Flash Builder 4.6 and later) to your project. These files can be found in the extension folder of the GoViral extension package.

In Flash Professional:

  1. Create a new project of the type 'AIR for iOS'.
  2. Select File > Publish Settings...
  3. Select the wrench icon next to 'Script' for 'ActionScript Settings'.
  4. Select the Library Path tab.
  5. Press the 'Browse for Native Extension (ANE) File' button and select the com.milkmangames.nativeextensions.GoViral.ane file.

In Flash Builder 4.6:

  1. Go to Project Properties (right-click your project in Package Explorer and select Properties).
  2. Select ActionScript Build Path and click the Native Extensions tab.
  3. Click Add ANE and navigate to the com.milkmangames.nativeextensions.GoViral.ane file.

In FlashDevelop:

  1. Copy the GoViralAPI.swc file to your project folder.
  2. In the explorer panel, right-click the SWC and select Add To Library.
  3. Right-click the SWC file in the explorer panel again, select Options, and then select External Library.

Getting started with the API

You can start using the GoViral extension with a few simple calls. See example/GoViralExample.as for a full example that shows how to interface with Facebook, Twitter, and email.

Follow these steps to get started:

  1. Import the API Classes:
import com.milkmangames.nativeextensions.ios.*; import com.milkmangames.nativeextensions.ios.events.*;
  1. Begin by initializing the API and creating an instance of a GoViral object by calling GoViral.create() . Make sure the current platform is supported (PCs and Android devices are not) by checking the GoViral.isSupported() method:
if(GoViral.isSupported()) { GoViral.create(); } else { trace(“GoViral only works on iOS!”); return; }

Adding Facebook support to your app

The GoViral extension offers complete support for Facebook mobile APIs, including single sign-on/authentication, wall posts, friend invitations, and the entire Facebook graph API.

  1. Start by initializing the Facebook SDK using your Facebook App ID. (The Facebook App ID can be found in your Facebook Developer site panel, as described in Setting up your app on the Facebook Developer site.)
// replace 000000 with your Facebook app id! GoViral.goViral.initFacebook(“000000”,””);
  1. Add event listeners for Facebook related events. The following example code shows all the available listeners; you may not need them all.
// Listen for events. GoViral.goViral.addEventListener(GVFacebookEvent.FB_DIALOG_CANCELED, onFacebookEvent); GoViral.goViral.addEventListener(GVFacebookEvent.FB_DIALOG_FAILED, onFacebookEvent); GoViral.goViral.addEventListener(GVFacebookEvent.FB_DIALOG_FINISHED, onFacebookEvent); GoViral.goViral.addEventListener(GVFacebookEvent.FB_LOGGED_IN, onFacebookEvent); GoViral.goViral.addEventListener(GVFacebookEvent.FB_LOGGED_OUT, onFacebookEvent); GoViral.goViral.addEventListener(GVFacebookEvent.FB_LOGIN_CANCELED, onFacebookEvent); GoViral.goViral.addEventListener(GVFacebookEvent.FB_LOGIN_FAILED, onFacebookEvent); GoViral.goViral.addEventListener(GVFacebookEvent.FB_REQUEST_FAILED, onFacebookEvent); GoViral.goViral.addEventListener(GVFacebookEvent.FB_REQUEST_RESPONSE, onFacebookEvent);
  1. When the user taps a Connect With Facebook (or similarly labeled button) in your app, you can log the user into Facebook by invoking GoViral.goViral.authenticateWithFacebook() .You can use the GoViral.goViral.isFacebookAuthenticated() method to determine if the user is logged in already :
// if the user is not already logged in... if(!GoViral.goViral.isFacebookAuthenticated()) { // show a connect with Facebook prompt. // this method takes a comma separated list of facebook permissions as a parameter. // you can refer to the facebook documentation at // http://developers.facebook.com/docs/authentication/permissions/ to determine which // permissions your app requires. GoViral.goViral.authenticateWithFacebook("user_likes,user_photos, publish_stream"); }

The user will be presented with the Facebook Connect prompt, and asked to grant your app permission to use Facebook on their behalf. If the official Facebook app is installed, and the device supports multitasking, iOS will task switch to the Facebook app to authenticate the user and then return to your app on completion.

If the official Facebook app is not installed, and the device supports multitasking, iOS will task switch to Safari and present an authentication dialog box there; on completion, your app will be returned to the foreground.

If the device does not support multitasking, an authentication dialog box will be presented inside your own app.

When the login succeeds, fails, or is cancelled by the user, a GVFacebookEvent.FB_LOGGED_IN , GVFacebookEvent.FB_LOGIN_FAILED , GVFacebookEvent.FB_LOGIN_CANCELED event will be dispatched respectively.

Post to the Facebook Wall

To post an update to the user's Facebook wall, use showFacebookFeedDialog() . The following example will display a Facebook dialog box prompting the user to make a wall post with a title, caption, message, description, link, and image URL:

// show a dialog to post the user's wall GoViral.goViral.showFacebookFeedDialog( "Posting from AIR", "This is a caption", "This is a message!", "This is a description", "http://www.milkmangames.com", "http://www.milkmangames.com/blog/wp-content/uploads/2012/01/v202.jpg" );

When the dialog box is dismissed, one of the following events will be dispatched:

  • GVFacebookEvent.FB_DIALOG_FINISHED if the dialog box finished normally
  • GVFacebookEvent.FB_DIALOG_CANCELED if the dialog box was canceled
  • GVFacebookEvent.FB_DIALOG_FAILED if the dialog box failed

Invite Facebook friends

Your app can call the showFacebookRequestDialog() method of the GoViral API to prompt the user to invite their friends to your app. The following example displays the invite friends dialog box, with a message and a title. If a friend accepts the request on the website, they'll be directed to the App Store to get your app. If they accept it on their mobile device, the app will be loaded if it is installed, or they'll be sent to the App Store to get it.

// show a dialog so the user can invite friends to app. GoViral.goViral.showFacebookRequestDialog("Try out this app!","My App Title");

When the dialog box is dismissed, one of the following events will be dispatched:

  • GVFacebookEvent.FB_DIALOG_FINISHED if the dialog box finished normally
  • GVFacebookEvent.FB_DIALOG_CANCELED if the dialog box was canceled
  • GVFacebookEvent.FB_DIALOG_FAILED if the dialog box failed

Get the user's profile

You can retrieve the user's profile with the requestMyFacebookProfile() method. This will cause a GVFacebookEvent.FB_REQUEST_RESPONSE event to be dispatched. The friends property of this event is a Vector.<GVFacebookFriend> , which will contain the user's profile information.

The following code shows how to request the profile and handle the response.

Refer to example/GoViralExample.as for a complete sample application that handles all Facebook events.

// listen for a response GoViral.goViral.addEventListener(GVFacebookEvent.FB_REQUEST_RESPONSE, onFacebookResponse); // request the user's profile. GoViral.goViral.requestFacebookFriends(); function onFacebookResponse(e:GVFacebookEvent):void { // the graphPath property is 'me' for a profile request. if(e.graphPath==”me”) { var myProfile:GVFacebookFriend=e.friends[0]; trace(“my name is:”+myProfile.name); trace(“my gender is:”+myProfile.gender); trace(“My bio is:”+myProfile.bio); } }

Get the user's friends

You can retrieve the user's list of friends with the requestFacebookFriends() method. This will cause a GVFacebookEvent.FB_REQUEST_RESPONSE event to be dispatched. The friends property of this event is a Vector.<GVFacebookFriend> , which will contain the user's friends' information.

The following code shows how to request the user's friends and loop through the list of friends received in the response.

// listen for a response GoViral.goViral.addEventListener(GVFacebookEvent.FB_REQUEST_RESPONSE,onFacebookResponse); // request the user's friends list. GoViral.goViral.requestFacebookFriends(); function onFacebookResponse(e:GVFacebookEvent):void { // the graphPath property is 'me/friends' for a friends request. if(e.graphPath==”me/friends”) { for each(var friend:GVFacebookFriend in e.friends) { trace(“i have a friend named:”+friend.name); } } }

Post a photo to Facebook

You can post a BitmapData image to the user's Facebook photos with the facebookPostPhoto() method. Note that this requires you to have initialized Facebook with the "publish_stream,user_photos" permissions in your call to authenticateWithFacebook() . Refer to this document for more information on permissions.

// posts a bitmapData called 'myBitmapData' to Facebook GoViral.goViral.facebookPostPhoto("posted from ios sdk",myBitmapData);

When the request is finished, a GVFacebookEvent.FB_REQUEST_RESPONSE will be dispatched with its graphPath set to me/photos .

Call the Facebook Graph API

The GoViral extension provides access to the entirety of the Facebook Graph API via facebookGraphRequest() . You can use any method Facebook supports, including scores, achievements, videos, check-ins, events, groups, and more directly from ActionScript 3.

For more information on accessing the Graph API via the extension, see the ActionScript documentation for facebookGraphRequest() . The example application class also demonstrates this feature in the postGraphFacebook() function.

For more information on the Graph API, refer to this page.

Adding Twitter support to your app

The GoViral extension exposes iOS 5's built-in Twitter functionality to ActionScript 3. Because the AIR 3.1 and AIR 3.2 SDKs do not yet support iOS 5 on Windows machines, in order to access native Twitter functions the final IPA must be compiled on a Mac with the latest version of Xcode installed.

If you are not able to compile on a Mac, the GoViral extension also supports an alternative Twitter implementation that can be compiled from Windows using Twitter's basic mobile WebViews instead. For details on compiling an IPA with AIR and the iOS 5 SDK, refer to Building your app with full Twitter support (Mac required).

Post a status update to Twitter

To post a status update to Twitter just call showTweetSheet() with the message you'd like to post:

// show a twitter status post dialog with bitmapData image GoViral.goViral.showTweetSheetWithImage("This is a native twitter post!",myBitmapData);

Upon completion, a GVTwitterEvent.TW_DIALOG_FINISHED , GVTwitterEvent.TW_DIALOG_CANCELED , or GVTwitterEvent.TW_DIALOG_FAILED event will be dispatched.

Post an image to Twitter

You may post a BitmapData image to Twitter using the showTweetSheetWithImage() method. This method shows a native iOS Twitter post dialog box and requires the iOS 5 SDK to work; if you do not compile your IPA with the iOS SDK on a Mac, or the user's device does not have iOS 5 (or later) installed, then a web-based status dialog box will be shown instead.

// show a twitter status post dialog with bitmapData image GoViral.goViral.showTweetSheetWithImage("This is a native twitter post!",myBitmapData);

Upon completion, a GVTwitterEvent.TW_DIALOG_FINISHED , GVTwitterEvent.TW_DIALOG_CANCELED , or GVTwitterEvent.TW_DIALOG_FAILED event will be dispatched.

Adding email support to your app

Email is a great way to invite your users to share information from your app with their friends. The GoViral Extension supports plain-text and HTML email messages, as well as image attachments, which you may pass to the API as BitmapData objects.

Send an Email

The showEmailComposer() method will display the native iOS Email Composer window to the user, prepopulated with the information you specify. The method takes a subject, a comma-separated list of recipients, and an email body as its parameters. The last parameter is a Boolean value specifying the format. Set it to false if your email body is formatted as plain text; set it as true if your email body is formatted as HTML.

// show an email to who@where.com and john@doe.com, with subject 'this is a subject!', and a // plain text body of 'This is the body of the message.' GoViral.goViral.showEmailComposer( "This is a subject!", "who@where.com,john@doe.com", "This is the body of the message.", false );

When the email composition window is dismissed, one of the following events will be dispatched:

  • GVMailEvent.MAIL_SAVED if the user saved but did not send the message
  • GVMailEvent.MAIL_SENT if the user sent the message
  • GVMailEvent.MAIL_CANCELED if the user canceled the operation
  • GVMailEvent.MAIL_FAILED if an error occurred sending

Send an email with an image attachment

The showEmailComposerWithBitmap() method will display the native iOS Email Composer window to the user, prepopulated with the information you specify. It uses the same parameters as showEmailComposer() , with one exception—it takes an additional parameter that you can use to specify a BitmapData image to attach to the email message.

// show an email to who@where.com and john@doe.com, with subject 'this is a subject!', and a // plain text body of 'This has a pic attached.' Attaches a bitmapData image called // myBitmapData. GoViral.goViral.showEmailComposer( "This is a subject!", "who@where.com,john@doe.com", "This has a pic attached.", false, myBitmapData );

As with showEmailComposer() as described above, when the email composition window is dismissed an event will be dispatched indicating the status of the operation .

Updating your application descriptor file

In your application descriptor file, you need to specify the version of the AIR SDK you are using (3.1 or later) as well as a link to the extension. For a working example, see example/app.xml.

  1. If it is not already set, set your AIR SDK version in the application descriptor file (use 3.2 below if you are using that version of the SDK):
<application xmlns="http://ns.adobe.com/air/application/3.1">
  1. Include a link to the extension in the descriptor:
<extensions> <extensionID>com.milkmangames.extensions.GoViral</extensionID> </extensions>
  1. Make sure that your <id> property exactly matches the App ID you created in iTunes Connect.
  2. If you're implementing Facebook support, add your Facebook App ID to the XML Application Descriptor. Refer to Setting up your app on the Facebook Developer site for information on locating your Facebook App ID in the Facebook Developer website. Add the following <iphone> section to the descriptor file, and replace the 000000 in fb000000 with your Facebook App ID.
<iPhone> <InfoAdditions> <![CDATA[ <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>fb000000</string> </array> </dict> </array> ]]> </InfoAdditions> </iPhone>

Building your app with full Twitter support (Mac required)

When building with the extension, you'll need to specify the directory containing the com.milkmangames.nativeextensions.GoViral.ane file. Because the AIR SDK for Windows does not include support for iOS 5, you'll need a Mac with Xcode and the iOS 5 SDK installed to build an IPA file with full native Twitter support.

If you're building on a Mac, use the .ane file from the /extension/maconly folder in the extension package. If you're building on Windows, or don't need native Twitter UI support, see the next section, Building your app with basic Twitter support (or on Windows).

Flash Builder 4.6 on a Mac

Flash Builder 4.6 has full support for native extensions. Follow these steps:

  1. Make sure you've included the ANE file as described in Including the GoViral API library.
  2. Make sure that the extension is enabled for your target configuration. To do this, right-click your project in Package Explorer, select Properties, expand Flex Build Packaging > Apple iOS, and click the Native Extensions tab.
  3. While still on the Native Extensions tab, click the Browse button to the right of Apple iOS SDK and specify the location of the iOS 5 SDK on your Mac. If you don't have the SDK, you can download and install the Xcode/iOS Developer tools from the Apple Developer website. The typical location of the SDK is

    /Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.0.sdk/.
  4. Click Apply to save your changes.

Flash CS6 - Mac:

  1. Create a new project of the type AIR for iOS.
  2. Choose File > Publish Settings.
  3. Click the wrench icon next to Script for ActionScript Settings.
  4. Select the Library Path tab.
  5. Click Browse For Native Extension (ANE) File and select the com.milkmangames.nativeextensions.GoViral.ane file.
  6. Click OK.
  7. Choose File > ActionScript Settings.
  8. Select iOS SDK.
  9. Browse to the path of the iOS 5 SDK on your Mac. If you don't have the SDK, you can download and install the Xcode/iOS Developer tools from the Apple Developer website. The typical location of the SDK is /Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.0.sdk/.

Building your app with basic Twitter support (or on Windows)

As noted above, you'll need to specify the directory containing the com.milkmangames.nativeextensions.GoViral.ane file when building with the extension. If you're building on Windows, or don't need native Twitter UI support, you can use the .ane file in the /extension root directory.

Flash Builder 4.6 on Windows

Flash Builder 4.6 has full support for native extensions.

  1. Make sure you've included the ANE file as described in Including the GoViral API library.
  2. Make sure that the extension is enabled for your target configuration, under the Native Extensions tab of the Flex Build Packaging>Apple iOS Area in project properties.
  3. Build your application and deploy as usual.

Flash CS6 - Windows:

  1. Create a new project of the type AIR for iOS.
  2. Choose File > Publish Settings.
  3. Select the wrench icon next to Script for ActionScript Settings.
  4. Select the Library Path tab.
  5. Click Browse For Native Extension (ANE) File and select the com.milkmangames.nativeextensions.GoViral.ane file.

FlashDevelop on Windows

FlashDevelop does not have complete native extension integration, but you can still use it to build the SWF file for your app.

  1. Make sure you've included the SWC file as described in Including the GoViral API library.
  2. Build your app from FlashDevelop, and note the location of the generated SWF file.
  3. Make sure you've downloaded the AIR 3.1 SDK (or later), and unzipped it to a folder on your PC. This example below assumes you've unzipped it to c:\dev\air_sdk_31.
  4. Create a directory to store the component files of your application. The example below as su mes the directory is c:\dev\myapp.
  5. Copy the .mobileprovision file, SWF file, .p12 keystore file, application descriptor file, and .ane file into your new directory.
  6. Open the Command Prompt and navigate to the new directory. (On Windows, click Start > All Programs > Accessories > Command Prompt.) The following command would navigate to the c:\dev\myapp directory:
cd c:\dev\myapp
  1. Use the AIR SDK to compile the final IPA for your dev ice. The foll owing command demonstrates how this is done for the sample paths described above. Replace these as necessary before running the command.
c:\dev\air_sdk_31\bin\adt -package -target ipa-test-interpreter -storetype pkcs12 -keystore YOURKEYSTOREFILE.P12 -storepass YOURPASSWORD -provisioning-profile YOUR_MOBILEPROVISION_FILE.mobileprovision myapp.ipa myapp.xml myapp.swf -extdir.

Take note of the dot after -extdir . It is not a typo; it tells the adt packager to look for the extension in the current directory.

Where to go from here

Now that you have the GoViral extension for iOS up and running, you may want to explore the ActionScript 3 documentation or check out the other tools from available from Milkman Games.

Creative Commons License
This work is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 Unported License.

More Like This

Products

Solutions

Industries

Help

Learning

Ways to buy

Downloads

Company

Choose your region

Copyright © 2012 Adobe Systems Incorporated. All rights reserved.

Terms of Use | Privacy Policy and Cookies (Updated)

Reviewed by TRUSTe: site privacy statement