Using the GoViral social networking extension for iOS

by Alex Liebert

Milkman Games

Installing the AIR 3.5 SDK
Including the GoViral API Library
Getting started with the API
Sharing messages with the iOS 6 Activity View
Share to Twitter, Sina Weibo, or Facebook with the Social Composer
Updating your application descriptor file
Building your application
Where to go from here

Created

19 December 2012

Requirements
Prerequisite knowledge Experience building games for iOS with Flash Builder or Flash Professional and Adobe AIR, and the GoViral Networking Native Extension will help you make the most of this article.	Required products Adobe AIR SDK
Additional required other products Milkman Games GoViral Social Networking Extension for iOS
User level Intermediate

iOS 6 introduces a range of new built-in social networking features for developers, including a tighter integration with Facebook, Twitter, and the recently added Sina Weibo, and a quick way to post messages and images to a service of the user's choosing. With Adobe AIR 3.5 and the GoViral Native Extension, you can share status updates, pictures, and URLs to a variety of services with just a few lines of code.

This article covers using iOS 6's Social Composer and Activity Sharing views, which allow quick sharing without the need to create a developer account with the target services. To learn about deeper Facebook integration, including single sign-on, friend requests, Graph API, and other advanced features, refer to the previous GoViral tutorial Using the GoViral social networking extension for iOS.

Installing the AIR 3.5 SDK

The GoViral native extension requires the AIR 3.5 SDK or a later version. You can download the latest AIR SDK from http://www.adobe.com/special/products/air/sdk/. 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 iOS 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 iOS, 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.

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:

Create a new mobile project
Choose File>Publish Settings...
Select 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.

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

Before accessing iOS 6 Social features in the extension, initialize the GoViral instance.

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

Sharing messages with the iOS 6 Activity View

The iOS 6 "Activity View" presents the user with a pop-up UI, from which they can choose to share a message immediately with a service of their choosing—such as Mail, SMS, Twitter, Facebook, or Sina Weibo.

Post a message

Start by adding an event listener for GVShareEvent.GENERIC_MESSAGE_SHARED, which will be dispatched when the activity is completed:

GoViral.goViral.addEventListener(GVShareEvent.GENERIC_MESSAGE_SHARED,onShared);

function onShared(e:GVShareEvent):void
{
trace("message was shared with activity view!");
}

To open the Activity View, call the shareGenericMessage() method—passing in the subject, the message, and whether it is HTML-formatted. The last two parameters set the position where the Activity View will appear if the app is running on an iPad. (You can set this to the point location of the button associated with the action.)

// make sure this function is available (iOS 6 or higher)
if(GoViral.goViral.isGenericShareAvailable())
{
GoViral.goViral.shareGenericMessage(
"This is a subject!", // not all targets will use the 'subject'
"I'm sharing this!", // this is the message to share
false, // set to 'true' if the message is html-formatted
800, // on iOS 6 ipads, show the popup at 800 pts x
800 // on iOS 6 ipads, show the popup at 800 pts y
);

Post a message with an image

To show the Activity View with an image attachment, use the shareGenericMessageWithImage() method. The parameters are exactly the same as shareGenericMessage(), but with the addition of a pointer to the BitmapData image you'd like to attach:

// make sure this function is available (iOS 6 or higher)
if(GoViral.goViral.isGenericShareAvailable())
{
GoViral.goViral.shareGenericMessage(
"This is a subject!", // not all targets will use the 'subject'
"I'm sharing this!", // this is the message to share
false, // set to 'true' if the message is html-formatted
myBitmapData, // the BitmapData to attach
800, // on iOS 6 ipads, show the popup at 800 pts x
800 // on iOS 6 ipads, show the popup at 800 pts y

);

Share to Twitter, Sina Weibo, or Facebook with the Social Composer

IOS 6 introduces another new feature, the Social Composer View, which can be used for quickly sharing messages an image directly to built-in social services as Sina Weibo, Twitter, and Facebook.

Start by adding an event listener for GVShareEvent.SOCIAL_COMPOSER_FINISHED, which will be dispatched when the activity is completed, and GVShareEvent.SOCIAL_COMPOSER_CANCELED, which will be dispatched if the user cancels the action:

GoViral.goViral.addEventListener(GVShareEvent.SOCIAL_COMPOSER_FINISHED,onSocialFinished);
GoViral.goViral.addEventListener(GVShareEvent.SOCIAL_COMPOSER_CANCELED,onSocialCanceled);

function onSocialFinished(e:GVShareEvent):void
{
trace("message was shared to"+e.socialServiceType+" with social composer view!");
}
function onSocialCanceled(e:GVShareEvent):void
{
trace("the user canceled the social composer.");
}

Open a Social Composer view with the displaySocialComposerView() method. You may specify a social service type from one of the constants GVSocialServiceType.FACEBOOK, GVSocialServiceType.TWITTER, or GVSocialServiceType.SINAWEIBO, as well as a message—and optionally, an image and URL. Before calling it , you should check isSocialServiceTypeAvailable() to make sure the service is enabled and the OS supports it. The following example shares to Sina Weibo, attaching a message, URL, and BitmapData image:

// share with Sina Weibo in iOS 6, if it's available
if(GoViral.goViral.isSocialServiceAvailable(GVSocialServiceType.SINAWEIBO))
{
GoViral.goViral.displaySocialComposerView(
GVSocialServiceType.SINAWEIBO,
"I'm sharing this message",
myBitmapData,
http://www.milkmangames.com
}

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.

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.5">

Include a link to the extension in the descriptor:

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

Building your 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 CS6 on Windows:

Create a new project of the type AIR for iOS.
Choose File > Publish Settings.
Select 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 .mobileprovision file, 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 7 or earlier, click Start > All Programs > Accessories > Command Prompt. On Windows 8, Right Click the Start Screen; Click All apps > Windows System > 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 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_35\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 basic iOS 6 sharing enabled in your app, you may wish to explore deeper integration with Facebook, Twitter, and Mail in this tutorial, or view these other Native Extension articles:
Using the Push Notifications native extension for iOS
Using the Amazon In-App Purchase Adobe AIR native extension for Android and Kindle Fire
Using in-app ratings with the RateBox native extension for Adobe AIR on iOS and Android
Using native extensions in Adobe Flash Professional CS6
Using the In-App Billing Adobe AIR native extension for Android
Using the iOS In-App Purchase native extension for Adobe AIR
Using the GameCenter Adobe AIR native extension for iOS
Using the iAd Adobe AIR native extension for iOS
For additional extensions, see More Native Extensions from Milkman Games.