With the GoViral native extension for Android 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 Android is a completely native Java 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 to Google Play
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 Android 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

GoViral is also available for iOS. For iOS-specific set up instructions, see Using the GoViral social networking extension for iOS.

Setting up your app on the Facebook Developer site

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.

Go to http://developers.facebook.com. If you haven't already done so, register as a developer with Facebook to create your first app.
After logging in, select Apps from the top menu (see Figure 1).

Figure 1. Click Apps in the top menu.

Click Create New App (see Figure 2).

Figure 2. Click Create New App.

In the Create New App dialog box, type a display name for your application and click Continue (see Figure 3).

Figure 3. Type a name for your app.

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.

Complete the Basic Info section, including a contact email address. Be sure to select a Category for your app (see Figure 4).

Figure 4. Enter basic information for your app.

Click Native Android App to expand the iOS Section. Facebook for Android does not use the same security method for authenticating the app as Facebook does itself. It uses your Android Key Hash. You will need to generate a Key Hash for the testing/debug version of your app, and one for the release version. For now, type any string in this box, such as invalidkeyhash (see Figure 5). Later, you can use the native extension to retrieve your actual Key Hash. After you complete the Facebook.com set up, refer to the section, Getting your Android Key Hash below.

Figure 5. Type the Android Key Hash.

For Android Package Name, type your full Android app ID, such as air.com.yourcompany.yourappname. For Android Class Name, type the package name plus .AppEntry, such as, air.com.yourcompany.yourappname.AppEntry. Select Configured For Android SSO.
Click Save Changes to complete the Facebook set up.

Installing the AIR 3.5 SDK

The GoViral Social Media 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 AIR 3.5 SDK in Flash Professional CS6

Unzip the AIR 3.5 SDK package on your hard drive.
Launch Flash Professional CS6.
Choose Help > Manage AIR SDK.
Click the Plus (+) Button and navigate to the location of the unzipped AIR SDK.
Click OK.
Choose File > Publish Settings.
Select the AIR 3.5 SDK for Android as the Target.

Enabling the AIR 3.5 SDK in Flash Builder 4.6 on Windows

Unzip the AIR 3.5 SDK package on your hard drive.
Close Flash Builder.
Locate the Flash Builder SDK directory. On Windows, this is typically c:\Program Files\Adobe\Adobe Flash Builder 4.6\sdks.
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_AIR35.
Copy and paste the contents of the AIR 3.5 SDK into the 4.6.0_AIR35 directory. Accept all changes.
Edit the flex-sdk-description.xml file inside the new directory, and change the value of the <name> tag to Flex 4.6.0 (AIR 3.5).
Open Flash Builder and choose Project > Properties > Flex Compiler > Configure Flex SDKs.
Click Add and navigate to the new folder location.

Enabling the AIR 3.5 SDK in Flash Builder 4.6 on OS X

Copy the contents AIR 3.5 SDK package to your hard drive.
Close Flash Builder.
Locate the Flash Builder SDK directory. On OS X, it is typically /Applications/Adobe Flash Builder 4.6/sdks/.
Create a new folder inside the /Flash Builder 4.6/sdks/ folder named AIR35SDK and copy the contents of the AIR3.5 SDK package that you downloaded in step 1 into it.
Open the Terminal, and merge the AIR 3.5 SDK files into your current SDK directory: sudo cp -Rp /Applications/Adobe\ Flash\ Builder\ 4.6/sdks/AIR35SDK/ /Applications/Adobe\ Flash\ Builder\ 4.6/sdks/4.6.0/
Edit the flex-sdk-description.xml file inside the new directory, and change the value of the <name> tag to Flex 4.6.0 (AIR 3.5).
Open Flash Builder and choose Project > Properties > Flex Compiler > Configure Flex SDKs.
Click Add and navigate to the new folder location.

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 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:
Choose File > Publish Settings > Flash > ActionScript 3.0 Settings
Select External Library Path.
Click Browse to SWC File.
Select the GoViralAPI.swc file.

In Flash Builder 4.6:

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

In FlashDevelop:

Copy the GoViralAPI.swc file to your project folder.
In the explorer panel, right-click the SWC and select Add To Library.
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:

Import the API Classes:

        import com.milkmangames.nativeextensions.*;
import com.milkmangames.nativeextensions.events.*;
    

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.

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”,””);

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);

    

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, and a comma-separated list of
// Facebook WRITE permissions as a second 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_actions");
}
    

The user will be presented with the Facebook Connect prompt, and asked to grant your app permission to use Facebook on their behalf. Android will task switch to the Facebook app to authenticate the user and then return to your app on completion.

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 Google Play 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 Google Play 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 android 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 will use the device’s currently installed Twitter client to send messages via Twitter. Some Twitter Android apps do not accept messages that have both custom status messages and images; in these cases, the image will be attached but a default status message may be displayed for the user to edit.

Note: Due to the limitations of interprocess communication on Android, the native Twitter app on the Android device may dispatch a DIALOG_FINISHED event, even if the dialog box was canceled by the user.

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.

        // 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 native 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

Note: Due to the limitations of interprocess communication on Android, the native email app on the Android device may dispatch a MAIL_SENT event, even if the dialog box was canceled by the user.

Send an email with an image attachment

The showEmailComposerWithBitmap() method will display the native Android 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.

Sharing generic messages with Android

The Android operating system supports Intents, a powerful feature that enables an application to post a message and have another application handle it on the user’s behalf. For instance, when sharing a message as an Intent, the user may choose to post it via SMS, Bluetooth, Instagram, or another app currently installed on their device.

Share an Intent with a string message

The shareGenericImage() method will display a list of supported applications to the user, from which they may select one to send the message. The method takes a subject and a string message as parameters. The last parameter is a Boolean value specifying the format. Set it to false if your message is formatted as plain text; set it as true if your message is formatted as HTML.

The method isGenericShareAvailable() is checked first, to ensure that the current operating system supports Intents.

        If(GoViral.goViral.isGenericShareAvailable())
{
    // send an intent message ‘hello world!', and a
    // plain text body of 'This is the body of the message.'
    GoViral.goViral.shareGenericMessage(
      "hello world!",
      "This is the body of the message.",
      false
    );
}

    

When the Intent is finished, the GVShareEvent.GENERIC_MESSAGE_SHARED event will be dispatched.

Send an Intent with an image attachment

The shareGenericMessageWithImage() method shares an Intent with an image. It uses the same parameters as shareGenericMessage(), with one exception—it takes an additional parameter that you can use to specify a BitmapData image to attach to the Intent.

        If(GoViral.goViral.isGenericShareAvailable())
{
    // send an intent message ‘hello world!', and a
    // plain text body of 'This is the body of the message.',
    // and an image myBitmapData
    GoViral.goViral.shareGenericMessage(
      "hello world!",
      "This is the body of the message.",
      false,
      myBitmapData
    );
}

    

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.

If it is not already set, set your AIR SDK version in the application descriptor file:

<application xmlns="http://ns.adobe.com/air/application/3.5">

Include a link to the extension in the descriptor:

        <extensions>
<extensionID>com.milkmangames.extensions.GoViral</extensionID>
</extensions>

    

Make sure that your <id> property exactly matches the App ID you created in the Facebook Developer site.
Set the Android ManifestAdditions required by the extension. Add the following section, <android>, to the descriptor file:

        <android>
<manifestAdditions><![CDATA[
<manifest android:installLocation="auto">
<uses-sdk android:targetSdkVersion="12"/>
<uses-sdk android:minSdkVersion="8"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.INTERNET"/>
<application>
<activity android:name="com.milkmangames.extensions.android.MsgWrapActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>
<activity android:name="com.milkmangames.extensions.android.FacebookWrapActivity" android:configChanges="keyboardHidden|orientation|screenSize"/> 
</application>
</manifest> 
]]></manifestAdditions>
</android>


    

Building the application

Flash Builder 4.6 on Windows

Flash Builder 4.6 has full support for native extensions.

Make sure you've included the ANE file as described in Including the GoViral API library.
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.
Build your application and deploy as usual.

Flash Professional CS6

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

FlashDevelop

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

Make sure you've included the SWC file as described in Including the GoViral API library.
Build your app from FlashDevelop, and note the location of the generated SWF file.
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_35.
Create a directory to store the component files of your application. The example below assumes the directory is c:\dev\myapp.
Copy the SWF file, .p12 keystore file, application descriptor file, and .ane file into your new directory.
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

Use the AIR SDK to compile the final APK 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_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.

Getting your Android Key Hash

Unlike on iOS, Facebook uses the Android Key Hash when authenticating your application on Android. Your Android Key Hash is a special key string that is unique to the keystore (.p12 file) you use to sign your application.

Follow these steps to get your Android Key Hash:

Build your application with the version of the native extension found in the /extension/androiddebugane folder.
Run your app on your Android device. When initFacebook() is called, a pop-up window will display your Android Key Hash.
You can select the Mail button to email the Key Hash to yourself.
Visit the developer.facebook.com page for your app and type the Key Hash under Android Key Hash.

Here are a few important points to keep in mind:

Facebook authentication will not work on Android until your Key Hash has been entered on developer.facebook.com.
The Key Hash for your testing/debug app will not be the same as the Key Hash for your release app on Google Play. Be sure to use the correct Key Hash before releasing your app publicly.
Be sure to build your app with the release version of the native extension before releasing it to Google Play. Otherwise, your Key Hash will be compromised and visible to all users.

Troubleshooting

If Android is not returning to your app after launching the Facebook single sign-on page:

Verify that your AIR Application ID matches exactly the one you entered in the Facebook Developer website.
If you’re using the Publish Settings dialog box in Flash Professional CS6, make sure that your descriptor file changes are not being overridden by the Flash Professional IDE. Choosing File > Publish instead of using the Publish Settings dialog box will prevent the XML file from being overridden.
Update to the latest version of the Facebook application from Google Play; or install the SDK version of the Facebook app from here.
Make sure you've properly entered your Android Key Hash on developer.facebook.com. Refer to Getting Your Android Key Hash for details.

Where to go from here

Now that you have social networking up and running in your app, you may want to explore the other native extension tutorials:

For additional extensions, see More Native extensions from Milkman Games.

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

Using the GoViral Facebook, Twitter, and mail native extension for Android

by Alex Liebert

Content

Created

Page tools

Requirements

Prerequisite knowledge

User level

Required products