Requirements
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
Required products
Flash Builder (Download trial)
Adobe Animate CC
Adobe AIR SDK
Additional required other products
User level
Intermediate

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, native iOS 6 Facebook features, 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
  • Share social content for Sina Weibo, Twitter, SMS, Facebook and more with iOS 6’s native dialogs
  • 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
  • For the Android version of this tutorial, click here.

 
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. Select ''Mobile Web' and fill in 'Mobile Web URL' with your iTunes web URL. If your app is not live yet, you can use an existing web url, such as Angry Birds, which is http://itunes.apple.com/us/app/adobe-photoshop-express/id331975235?. Leave the required '?' at the end of the URL.
  4. Click Save Changes to complete the Facebook set up.

 
Installing the Latest AIR SDK

The GoViral native extension requires the AIR 3.5 SDK or a later version. You can download the latest AIR SDK from here. If you haven't already installed the AIR 3.5 SDK for your Flash Professional CS6 or Flash Builder IDE, follow the instructions below.
 
 
Enabling the Latest AIR SDK in Flash Professional CS6
  1. Unzip the AIR SDK package on your hard drive.
  2. Launch Flash Professional CS6.
  3. Choose Help > Manage AIR SDK.
  4. Click the Plus (+) Button and navigate to the location of the unzipped AIR SDK.
  5. Click OK.
  6. Choose File > Publish Settings.
  7. Select the AIR 3.5 (or Later) SDK for iOS as the Target.
 
Enabling the Latest AIR SDK in Flash Builder on Windows
  1. Unzip the AIR SDK package on your hard drive.
  2. Close Flash Builder.
  3. Locate the Flash Builder SDK directory. On Windows, this is typically c:\Program Files\Adobe\Adobe Flash Builder 4.6\sdks.
  4. Make a copy of the current Flex SDK directory, and give it a descriptive name. For instance, copy the 4.6.0 SDK folder inside /sdks and name the copy 4.6.0_AIR37.
  5. Copy and paste the contents of the AIR 3.5 SDK into the 4.6.0_AIR37 directory. Accept all changes.
  6. Edit the flex-sdk-description.xml file inside the new directory, and change the value of the <name> tag to match the version of the latest AIR SDK- for instance, Flex 4.6.0 (AIR 3.7).
  7. Open Flash Builder and choose Project > Properties > Flex Compiler > Configure Flex SDKs.
  8. Click Add and navigate to the new folder location.
 
Enabling the latest AIR SDK in Flash Builder on OS X
  1. Copy the contents AIR 3.5 SDK package to your hard drive.
  2. Close Flash Builder.
  3. Locate the Flash Builder SDK directory. On OS X, it is typically /Applications/Adobe Flash Builder 4.6/sdks/.
  4. Create a new folder inside the /Flash Builder 4.6/sdks/ folder named after the latest SDK- for instance, AIR37SDK and copy the contents of the AIR SDK package that you downloaded in step 1 into it.
  5. Open the Terminal, and merge the new AIR SDK files into your current SDK directory: sudo cp -Rp /Applications/Adobe\ Flash\ Builder\ 4.6/sdks/AIR37SDK/ /Applications/Adobe\ Flash\ Builder\ 4.6/sdks/4.6.0/
  6. Edit the flex-sdk-description.xml file inside the new directory, and change the value of the <name> tag to match the version of the latest AKR SDK- for instance, Flex 4.6.0 (AIR 3.7).
  7. Open Flash Builder and choose Project > Properties > Flex Compiler > Configure Flex SDKs.
  8. Click Add and navigate to the new folder location.
  9. The most time consuming part is done. Now you’re ready to write some code!
     

 
Including the GoViral API Library

The next step is to add the com.milkmangames.extensions.GoViral.ane to your project. These files can be found in the extension folder of the GoViral extension package.
 
In Flash Professional:
 
  1. Choose File > Publish Settings > Flash > ActionScript 3.0 Settings
  2. Select the Library Path tab
  3. Click Browse for Native Extension (ANE) File
  4. Select the com.milkmangames.extensions.GoViral.ane file.
  5. Choose Player Settings
  6. Select the Permissions tab, and enable INTERNET and WRITE_EXTERNAL_STORAGE
  7. Check the “Manually manage permissions and manifest additions for this app’ option.
In Flash Builder:
 
  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.extensions.GoViral.ane file.
  4. Select ActionScript Build Packaging and select the Package option for the current target.
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.

 
Updating your application descriptor file

In your application descriptor file, you need to specify the version of the AIR SDK you are using (3.5 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:
<application xmlns="http://ns.adobe.com/air/application/3.5">
  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 in the CFBundleUrlSchemes section, and the 000000 in the FacebookAppID section with your Facebook App ID.
<iPhone> <InfoAdditions> <![CDATA[ <key>FacebookAppID</key> <string>000000</string> <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>fb000000</string> </array> </dict> </array> ]]> </InfoAdditions> </iPhone>

 
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.*; import com.milkmangames.nativeextensions.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 READ permissions as a first // parameter. // You should have at least one read permission. // 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("basic info"); }
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 device is running iOS 6 or higher, iOS will present a dialog to accept any permissions without leaving the app.
 
If the device is running iOS 5 or earlier, and 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 device is running iOS 5 or earlier, 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); GoViral.goViral.addEventListener(GVFacebookEvent.FB_REQUEST_FAILED, onRequestFailed); // 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); } } Function onRequestFailed(e:GVFacebookEvent):void { trace("something went wrong: "+e.errorMessage); }
 
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. The extension will automatically request additional publish permissions, if required to post the photo.
 
// 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 .
 
 
Handle Mobile App Ad Installs
If you are using the mobile ads feature of the Facebook Platform, you can notify Facebook of an install after your app has started with the following call: GoViral.goViral.publishInstall();
 

 
Adding Twitter support to your app

The GoViral extension exposes iOS 5 and iOS 6's built-in Twitter functionality to ActionScript 3.
 
 
Post a status update to Twitter
To post a status update to Twitter just call showTweetSheet() with the message you'd like to post. (Twitter may not be available on devices with an iOS version below 5, or where the user has disabled Twitter in the device’s settings.  You can determine this case by first checking isTweetSheetAvailable() ) :
 
if(GoViral.goViral.isTweetSheetAvailable()) { // show a twitter status post dialog GoViral.goViral.showTweetSheet("This is a native twitter post!"); }
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 in a similar manner using the showTweetSheetWithImage() method.  
 
if(GoViral.goViral.isTweetSheetAvailable()) { // 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 .
 

 
Building the application

 
Flash Builder
Flash Builder 4.6 and later 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 Professional
  1. Make sure you've included the ANE file as described in Including the GoViral API library.
  2. Build your application and deploy as usual.
 
Flash Develop
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.5 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_37.
  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 device. The following command demonstrates how this is done for the sample paths described above. Replace these as necessary before running the command.
c:\dev\air_sdk_37\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.
 

 
Troubleshooting

If iOS is not returning to your app after launching the Facebook single sign on page, or the app crashes at startup:
 
  1. Verify that your AIR Application ID matches exactly the one you entered in the Facebook Developer website.
  2. Verify that the numeric Facebook App ID is correctly entered in the CFBundleUrlSchemes Array and the FacebookAppID string, as described in the section above, “Update your application descriptor file”. A common mistake is to leave out the ‘fb’ prefix. For instance, if your app ID is 123456, it should include “<string>fb123456</string>”, not “<string>123456</string>”.
  3. If you’re using the Publish Settings dialog in Flash CS6, make sure that your descriptor file changes are not being overridden by the Flash IDE. Confirm that the “Manually manage permissions and manifest additions for this app” option has been selected in the Publish Settings dialog before modifying the application descriptor.

 
Where to go from here

Now that you have basic social networking up and running in your iOS app, you may want to explore
iOS 6 Social Networking Features with the GoViral Native Extension, or these other native extension tutorials:
 
For additional extensions, see More Native Extensions from Milkman Games.