Get Started with Vungle (SDK v. 5.1 and higher) - Adobe AIR

Follow these instructions to integrate our Vungle Adobe Air Plugin into a basic sample application. The source code we reference here is available on our public GitHub repository.

Contents

Before you Begin

  • The Vungle Extension Requires Adobe AIR SDK 4.0 or higher. For instructions on updating the AIR SDK in Flash Builder or Flash Professional, refer to the “Additional Notes” section.

  • If you are working with Android, the Vungle AIR extension requires JDK 6 or JDK 7 (depending on the version of Flash you are using) to be installed on the development system. Android 3.0 (Honeycomb - API version 11) or later is required for the application to run.

  • You can refer to the ActionScript 3 Class Documentation.

  • Review example/VungleExample.as for a sample application class. (If you're a Flash Professional user and are not sure how to use a Document Class, refer to “Using the VungleExample.as Document Class in Animate or Flash Professional CS6?” at the end of this article.)

Step 1. Include the Extension Library

Start by creating a new AIR for mobile project and adding the native extension.

If you’re targeting Android, you may also need to add Google Play Services library to your project. Because many other extensions already include this library, it may already be present. To add the extension, repeat the steps below, but use com.vungle.extensions.android.GooglePlayServices.ane in place of com.vungle.extensions.Vungle.ane.

For Animate and Flash Professional CS6 or Higher

  1. Create a new AIR for Android or AIR for iOS project.
  2. Select File → Publish Settings...
  3. Select the wrench icon next to Script for 'ActionScript Settings'.
  4. In the Library Path tab, click Browse for Native Extension (ANE) File and select the vungle.extensions.Vungle.ane file. Click OK.
  5. Select the wrench icon next to Target for 'Player Settings'.
  6. If targeting Android: In the Permissions tab, enable 'INTERNET', 'WRITE_EXTERNAL_STORAGE', and 'ACCESS_NETWORK_STATE'.
  7. Select the Manually manage permissions and manifest additions for this app option and click OK.

For Flash Builder 4.6 or Higher

  1. In Project Properties, under Actionscript Build Path, select Native Extensions.
  2. Choose Add ANE... and navigate to the vungle.extensions.Vungle.ane file.
  3. Select Actionscript Build Packaging → Google Android.
  4. In the Native Extensions tab, select the Package option next to the extension.
  5. If targeting iOS, repeat steps 3 and 4 for the 'Apple iOS' target.

Step 2. Update Your Application Descriptor

For Vungle to work, changes are required to the application XML file for your app. Modify the XML file created by your IDE with the following changes. 

Note: If you're a Flash Professional user, make sure you've followed the steps above for including the extension library “For Animate and Flash Professional CS6 or Higher''; otherwise, Flash may undo your changes as you make them. 

  1. Set your AIR SDK to 4.0 (or later) in the app descriptor file:
    <application xmlns="http://ns.adobe.com/air/application/4.0">
  2. Include a link to the extension in the descriptor: 
    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    </extensions>
  3. If targeting Android: you may need to include the Google Play Services extension. Add its extension ID here as well. 
    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    <extensionID>com.vungle.extensions.android.GooglePlayServices</extensionID>
    </extensions>

For AIR Applications Targeting Android

If targeting Android, update your Android Manifest Additions in the android XML element to:

  • include the INTERNET, WRITE_EXTERNAL_STORAGE, and ACCESS_NETWORK_STATE permissions
  • add VideoFullScreenAdActivityMraidFullScreenAdActivity, and MraidFullScreenAdActivity  activity definitions
  • add the google-play-services version metadata tag:
    
    <android>
    <manifestAdditions><![CDATA[
    
    <manifest android:installLocation="auto">
    
    <uses-permission android:name="android.permission.INTERNET"/>
     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="18" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
     <application>
       <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/>
       <activity android:name="com.vungle.publisher.VideoFullScreenAdActivity"
         android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
         android:theme="@android:style/Theme.NoTitleBar.Fullscreen"/>
       <activity android:name="com.vungle.publisher.MraidFullScreenAdActivity"
         android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
         android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"/>
       <activity android:name="com.vungle.publisher.FlexViewAdActivity"
         android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
         android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"/>
     </application>
    
    </manifest>
    ]]></manifestAdditions>
    </android>

Step 3. Integrate the Vungle API

The Vungle API can be added your application in just a few lines of ActionScript.

Initialize the Vungle Extension

Note: A default placement is created for each app automatically. You must provide its placement reference ID in this initialization step whether or not you plan to take advantage of the placements functionality. If you create multiple placements, provide all the reference IDs.

Initialize the API when your application starts.

  • If using pure ActionScript, do this in the constructor of your Document class.
  • If using Flex, call this in the initialize() event of the main class.
  • If using timeline code in Flash, do this on Frame 1.
  1. Import the API Classes:
    import com.vungle.extensions.*; 
    import com.vungle.extensions.events.*;
  2. Initialize the API by calling create(), and passing in a string of your application ID and an array that contains the placement reference ID of the application from the Vungle Dashboard. If you are targeting both iOS and Android from the same project, provide different application ID and its placement array per platform to the create() method.

    Wrap your call to Vungle.create() in a try/catch because Vungle may throw an error during the creation process (for instance, the extension throws an error if running on the desktop):
    try
    {
        // initialize with your app id
        Vungle.create("your_vungle_id", [“placement1”, “placement2”, “placement3”]);
     
    } catch (error:Error) {
        // could not create extension. Are you running on something besides iOS/Android?
    }

Load a Placement Ad

To play a placement ad, you must load an ad for that placement. Note that your auto-cached placement doesn’t require you to call this method. The SDK will try to load the auto-cached placement internally.

Vungle.vungle.loadAd(“non_auto_cached_placement”);

Play a Placement Ad

You will know when the ad is ready to play through event listeners. Once a placement is available to play, you can play an ad.

If (Vungle.vungle.isAdAvailable(“placement_id”)) {
    Vungle.vungle.playAd(“placement_id”);
}

Add Event Listeners

The Vungle Extension dispatches four events: VungleEvent.AD_PLAYABLE, VungleEvent.AD_STARTED, VungleEvent.AD_FINISHED, VungleEvent.AD_FAILED, VungleEvent.AD_INIT, and VungleEvent.AD_LOG.

  1. The AD_PLAYABLE is dispatched when an ad is ready to play.
    Vungle.vungle.addEventListener(VungleEvent.AD_PLAYABLE, onAdPlayable);
    function onAdPlayable(e:VungleEvent):void
    {
        if (e.isAdPlayable) {
            trace(“ad is playable for placement: “ + e.placement);
            Vungle.vungle.playAd(e.placement);
        } else {
    	trace(“ad not playable for placement: “ + e.placement);
        }
    }
  2. The AD_STARTED and AD_FINISHED events are dispatched when an ad is displayed and dismissed, respectively: 
    Vungle.vungle.addEventListener(VungleEvent.AD_STARTED, onAdStarted);
    Vungle.vungle.addEventListener(VungleEvent.AD_FINISHED, onAdFinished);
    
    function onAdStarted(e:VungleEvent):void
    {
        trace("ad displayed for placement: " + e.placement);
    }
    
    function onAdFinished(e:VungleEvent):void
    {
        trace("ad dismissed for placement: “ + e.placement + “, CTA = " + e.wasCallToActionClicked);
    
        if (e.wasSuccessfulView) {	
            trace("counts a completed view - present reward.");
        }
    }
  3. The AD_INIT is dispatched when Vungle SDK has finished initialization. 
    function onAdInit(e:VungleEvent):void
    {
        trace(“Vungle SDK is initialized: “ + e.isInitialized”);
    }
  4. The AD_LOG is dispatched when a log message is sent by the the Vungle SDK. You can use it for debugging. Logging is implemented only in Vungle SDK for iOS, so this event is platform-specific. 
    Vungle.vungle.setLoggingEnabled(true);
    Vungle.vungle.addEventListener(VungleEvent.AD_LOG, onAdLog);
    
    private function onAdLog(e:VungleEvent):void
    {
        log("ad log: " + e.message);
    }

More Options

As you have already seen, you can pass an object with configuration options when calling the playAd() method. These are the available properties in VungleAdConfig:

Option

Value

Description

orientation

VungleOrientation

Android

●      VungleOrientation.AUTO_ROTATE

●      VungleOrientation.ANDROID_MATCH_VIDEO

iOS

●      VungleOrientation.IOS_LANDSCAPE

●      VungleOrientation.IOS_PORTRAIT

soundEnabled

Boolean

If true (default), sound will be enabled during video ad playback, subject to the device's sound settings. If false, video playback will begin muted. Note that the user can mute or unmute sound during playback.

backButtonImmediatelyEnabled

Boolean

For Android only, if set to true, it enables user to immediately exit an ad using the back button. If false (default), the user cannot use the back button to exit the ad until the on-screen close button is shown.

immersiveMode

Boolean

For Android only, if set to true, it enables immersive mode on KitKat+ devices. It is set to false by default)

incentivizedUserId

String

You can set a unique user ID to be passed to your application to verify that this user should be rewarded for watching an incentivized ad.

incentivizedCancelDialogTitle

String

You can customize a message to display to users when they attempt to close the video before completion.

 

Note: This option only applies to standard Vungle ads and not Dynamic Template ads. The option that applies to Dynamic Template ads will be available to specify on the dashboard and has same options.

incentivizedCancelDialogBodyText

incentivizedCancelDialogCloseButtonText

incentivizedCancelDialogKeepWatchingButtonText

Sample code: 

var adConfig:VungleAdConfig = new VungleAdConfig();
            
adConfig.orientation = VungleOrientation.ANDROID_MATCH_VIDEO | VungleOrientation.IOS_LANDSCAPE;
adConfig.soundEnabled = false;

android: {
    adConfig.backButtonImmediatelyEnabled = true;
    adConfig.immersiveMode = true;
};

adConfig.incentivizedUserId = "vungle_test_user";
adConfig.incentivizedCancelDialogBodyText = "body_text";
adConfig.incentivizedCancelDialogCloseButtonText = "close_button_text";
adConfig.incentivizedCancelDialogKeepWatchingButtonText = "continue_button_text";
adConfig.incentivizedCancelDialogTitle = "title_text";

Vungle.vungle.playAd(placement, adConfig);

Global Defaults

You can use the global configuration object to set default values for the options:

// set any configuration options you like
VungleAdConfig.globalConfig.orientation = VungleOrientation.ANDROID_MATCH_VIDEO;
VungleAdConfig.globalConfig.soundEnabled = false;

Then every new VungleAdConfig object is created with these values set by default. playAd() without options also uses the global configuration.

Note: While your app is in Test mode, you will not be able to download any of the apps advertised. Additionally, the Dashboard will not report the number of impressions. This is because test ads are used only to verify that you have integrated the SDK correctly. This functionality becomes available once your app has gone live in active mode.

Additional Notes

Using the VungleExample.as Document Class in Animate or Flash Professional CS6

  1. First, create the application and add the extension by following Steps 1-3 of this integration article.
  2. Copy and paste as into the same folder as your .fla. Do not copy and paste its contents onto the timeline.
  3. Change the app IDs and placement IDs on line 20 to be your own Vungle IDs.
  4. In Flash properties, under Document Class, type VungleExample and click OK.
  5. Build and install the application.

Installing a Newer Version of the AIR SDK (4.0 or Higher) in Flash Professional CS6

Follow this link to find the latest AIR SDK. If you have already installed AIR 4.0 or higher, you may skip this step. Otherwise, follow the instructions below:

  1. Unzip the AIR 4.0 or later SDK package to a location on your hard drive.
  2. Launch Flash Professional CS6.
  3. Select Help → Manage AIR SDK...
  4. Click the + (plus) button and navigate to the location of the unzipped AIR SDK.
  5. Click OK.
  6. Select File → Publish Settings.
  7. Select the latest AIR SDK for iOS from the Target dropdown menu.

Installing a Newer Version of the AIR SDK (4.0 or Higher) in Flash Builder

Follow this link to find the latest AIR SDK. If you have already installed AIR 4.0 or higher, you may skip this step. You can also make use of Adobe's latest instructions for updating Flash Builder AIR SDKs.

Resolving the 'Adobe Animate Invalid Input' Error

If you are receiving an error as shown in the image below, refer to this article.

image2.png

Have more questions? Submit a request

Comments