/air

Source for the Adobe AIR native extension for the Chartboost SDK with compile scripts.

Primary LanguageActionScriptMIT LicenseMIT

The Chartboost Adobe AIR plugin provides the functionality for showing ads and MoreApps pages, and supplies our analytics system with detailed information about campaign performance.

Contents

Overview

Adding the AIR plugin to your games is quick and easy – you just need a few ingredients:

Notes

  • The Chartboost Adobe AIR plugin is currently in beta
  • The plugin uses iOS SDK v5.1.5 and Android SDK v5.1.3
  • The Chartboost AIR plugin supports iOS 6 and higher – Chartboost methods will fail silently on iOS 5 or older operating systems
  • Chartboost supports Android 2.3 and higher

Pre-Integration Steps

After you've added your app to the Chartboost dashboard and set up a publishing campaign, you're ready to prepare your AIR project for integration with Chartboost.

First, import the Chartboost native extension in your AIR app. We recommend creating a directory in your project for native extensions where you can copy Chartboost.ane and Chartboost.swc. Then (if you're using Flash Builder) you can simply add that directory as a native extension directory in your project settings.

Second, add the <extensionID> declaration to your AIR application descriptor's root <application> element:

<extensions>
    <extensionID>com.chartboost.plugin.air</extensionID>
</extensions>

If you'll be building for Android, you must also add these manifest additions to your AIR application descriptor file (remember to swap in your Chartboost app ID and app signature):

<manifestAdditions><![CDATA[
    <manifest android:installLocation="auto">
        <!-- This permission is required for Chartboost. -->
        <uses-permission android:name="android.permission.INTERNET"/>

    &lt;!-- These permissions are recommended for Chartboost. --&gt;
    &lt;uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/&gt;
    &lt;uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/&gt;
    &lt;uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/&gt;
    
    &lt;application&gt;
        &lt;!-- The app ID and signature for the Android version of your AIR app must be placed here. --&gt;
        &lt;meta-data android:name="__ChartboostAir__AppID" android:value="ANDROID_APP_ID" /&gt;
        &lt;meta-data android:name="__ChartboostAir__AppSignature" android:value="ANDROID_APP_SIGNATURE" /&gt;
        
        &lt;!-- Also required for the Chartboost SDK. --&gt;
        &lt;activity android:name="com.chartboost.sdk.CBImpressionActivity"
                                  android:excludeFromRecents="true" 
                                  android:theme="@android:style/Theme.Translucent.NoTitleBar"
                                  android:configChanges="fontScale|keyboard|keyboardHidden|locale|mnc|mcc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|uiMode|touchscreen" /&gt;
        &lt;!-- For Google Play Services (required by Chartboost) --&gt;
        &lt;meta-data android:name="com.google.android.gms.version"
                                  android:value="@integer/google_play_services_version" /&gt;
    &lt;/application&gt;
&lt;/manifest&gt;



]]></manifestAdditions>

Android developers: Note also that if you are using another plugin that includes Google Play Services, you may get an error while building. Use the provided ANE that is free of Google Play Services if you want to avoid this conflict.

Interacting With Chartboost

Chartboost Setup

First, import the Chartboost classes:

import com.chartboost.plugin.air.*;

We recommend making a variable in your class to store a reference to the global Chartboost instance:

private var chartboost:Chartboost;

// later...
chartboost = Chartboost.getInstance();

To initialize Chartboost, call the init() method with your Chartboost app ID and app signature. You'll probably need to call it conditionally for different platforms, so we've provided some helper functions for you to use:

if (Chartboost.isAndroid()) {
    chartboost.init("ANDROID_APP_ID", "ANDROID_APP_SIGNATURE");
} else if (Chartboost.isIOS()) {
    chartboost.init("IOS_APP_ID", "IOS_APP_SIGNATURE");
}
Calling Chartboost Methods

In /actionscript/src/com/chartboost/plugin/air/Chartboost.as, you'll find the AIR-to-native methods used to interact with the Chartboost plugin:

/** Initializes the Chartboost plugin and, on iOS, records the beginning of a user session */
public function init(appID:String, appSignature:String):void

/** Listen to a delegate event from the ChartboostEvent class. See the documentation


    

  • of the event you choose for the arguments and return value of the function you provide. */
public function addDelegateEvent(eventName:String, listener:Function):void
    • 



/** Caches an interstitial. */
public function cacheInterstitial(location:String):void


/** Shows an interstitial. */
public function showInterstitial(location:String):void


/** Checks to see if an interstitial is cached. */
public function hasInterstitial(location:String):Boolean


/** Caches the MoreApps page. */
public function cacheMoreApps(location:String):void


/** Shows the MoreApps page. */
public function showMoreApps(location:String):void


/** Checks to see if the MoreApps page is cached. */
public function hasMoreApps(location:String):Boolean


/** Caches the rewarded video. */
public function cacheRewardedVideo(location:String):void


/** Shows the rewarded video. */
public function showRewardedVideo(location:String):void


/** Checks to see if the rewarded video is cached. */
public function hasRewardedVideo(location:String):Boolean


/** Call this as a result of whatever UI you show in response to the


    

  • delegate method didPauseClickForConfirmation() */
public function didPassAgeGate(pass:Boolean):void
    • 



/** Custom settings */
public function setCustomID(customID:String):void
public function getCustomID():String


/** Set whether interstitials will be requested in the first user session */
public function setShouldRequestInterstitialsInFirstSession(shouldRequest:Boolean):void


/** Set whether or not to use the age gate feature.


    

  • Call Chartboost.didPassAgeGate() to provide your user's response. */
public function setShouldPauseClickForConfirmation(shouldPause:Boolean):void
    • 



/** Set whether the MoreApps page will have a full-screen loading view. */
public function setShouldDisplayLoadingViewForMoreApps(shouldDisplay:Boolean):void


/** Set whether video content is prefetched */
public function setShouldPrefetchVideoContent(shouldPrefetch:Boolean):void


/** Control whether ads are automatically cached when possible (default: true). */
public function setAutoCacheAds(shouldCache:Boolean):void
public function getAutoCacheAds():Boolean


/** Chartboost in-app purchase analytics */
public function trackIOSInAppPurchaseEvent(receipt:String, title:String, description:String, price:Number, currency:String, productID:String):void
public function trackGooglePlayInAppPurchaseEvent(title:String, description:String, price:String, currency:String, productID:String, purchaseData:String, purchaseSignature:String):void
public function trackAmazonStoreInAppPurchaseEvent(title:String, description:String, price:String, currency:String, productID:String, userID:String, purchaseToken:String):void
Listening to Chartboost Events

Chartboost fires many different events to inform you of the status of impressions. In order to react these events, you must explicitly listen for them. The best place to do this is the initialization code for your active screen:

// in some initializing code
chartboost.addDelegateEvent(ChartboostEvent.DID_CLICK_INTERSTITIAL, function (location:String):void {
    trace( "Chartboost: on Interstitial clicked: " + location );
});

In /actionscript/src/com/chartboost/plugin/air/ChartboostEvent.as, you'll find all the events that are available to listen to:

  
/** Fired when an interstitial fails to load.
 * Arguments: (location:String, error:CBLoadError) */
public static const DID_FAIL_TO_LOAD_INTERSTITIAL:String = "didFailToLoadInterstitial";

/** Fired when an interstitial is to display. Return whether or not it should.


    

  • Arguments: (location:String)
    • 

  • Returns: Boolean */
public static const SHOULD_DISPLAY_INTERSTITIAL:String = "shouldDisplayInterstitial";
    • 



/** Fired when an interstitial is finished via any method.


    

  • This will always be paired with either a close or click event.
    • 

  • Arguments: (location:String) */
public static const DID_CLICK_INTERSTITIAL:String = "didClickInterstitial";
    • 



/** Fired when an interstitial is closed


    

  • (i.e. by tapping the X or hitting the Android back button).
    • 

  • Arguments: (location:String) */
public static const DID_CLOSE_INTERSTITIAL:String = "didCloseInterstitial";
    • 



/** Fired when an interstitial is clicked.


    

  • Arguments: (location:String) */
public static const DID_DISMISS_INTERSTITIAL:String = "didDismissInterstitial";
    • 



/** Fired when an interstitial is cached.


    

  • Arguments: (location:String) */
public static const DID_CACHE_INTERSTITIAL:String = "didCacheInterstitial";
    • 



/** Fired when an interstitial is shown.


    

  • Arguments: (location:String) */
public static const DID_DISPLAY_INTERSTITIAL:String = "didDisplayInterstitial";
    • 



/** Fired when the MoreApps page fails to load.


    

  • Arguments: (location:String, error:CBLoadError) */
public static const DID_FAIL_TO_LOAD_MOREAPPS:String = "didFailToLoadMoreApps";
    • 



/** Fired when the MoreApps page is to display. Return whether or not it should.


    

  • Arguments: (location:String) */
public static const SHOULD_DISPLAY_MOREAPPS:String = "shouldDisplayMoreApps";
    • 



/** Fired when the MoreApps page is finished via any method.


    

  • This will always be paired with either a close or click event.
    • 

  • Arguments: (location:String)
    • 

  • Returns: Boolean */
public static const DID_CLICK_MORE_APPS:String = "didClickMoreApps";
    • 



/** Fired when the MoreApps page is closed


    

  • (i.e. by tapping the X or hitting the Android back button).
    • 

  • Arguments: (location:String) */
public static const DID_CLOSE_MORE_APPS:String = "didCloseMoreApps";
    • 



/** Fired when a listing on the MoreApps page is clicked.


    

  • Arguments: (location:String) */
public static const DID_DISMISS_MORE_APPS:String = "didDismissMoreApps";
    • 



/** Fired when the MoreApps page is cached.


    

  • Arguments: (location:String) */
public static const DID_CACHE_MORE_APPS:String = "didCacheMoreApps";
    • 



/** Fired when the MoreApps page is shown.


    

  • Arguments: (location:String) */
public static const DID_DISPLAY_MORE_APPS:String = "didDisplayMoreApps";
    • 



/** Fired after a click is registered, but the user is not forwarded to the IOS App Store.


    

  • Arguments: (location:String, error:CBClickError) */
public static const DID_FAIL_TO_RECORD_CLICK:String = "didFailToRecordClick";
    • 



/** Fired when a rewarded video is cached.


    

  • Arguments: (location:String) */
public static const DID_CACHE_REWARDED_VIDEO:String = "didCacheRewardedVideo";
    • 



/** Fired when a rewarded video is clicked.


    

  • Arguments: (location:String) */
public static const DID_CLICK_REWARDED_VIDEO:String = "didClickRewardedVideo";
    • 



/** Fired when a rewarded video is closed.


    

  • Arguments: (location:String) */
public static const DID_CLOSE_REWARDED_VIDEO:String = "didCloseRewardedVideo";
    • 



/** Fired when a rewarded video completes.


    

  • Arguments: (location:String, reward:int) */
public static const DID_COMPLETE_REWARDED_VIDEO:String = "didCompleteRewardedVideo";
    • 



/** Fired when a rewarded video is dismissed.


    

  • Arguments: (location:String) */
public static const DID_DISMISS_REWARDED_VIDEO:String = "didDismissRewardedVideo";
    • 



/** Fired when a rewarded video fails to load.


    

  • Arguments: (location:String, error:CBLoadError) */
public static const DID_FAIL_TO_LOAD_REWARDED_VIDEO:String = "didFailToLoadRewardedVideo";
    • 



/** Fired when a rewarded video is to display. Return whether or not it should.


    

  • Arguments: (location:String)
    • 

  • Returns: Boolean */
public static const SHOULD_DISPLAY_REWARDED_VIDEO:String = "shouldDisplayRewardedVideo";
    • 



/** Fired right after a rewarded video is displayed.


    

  • Arguments: (location:String) */
public static const DID_DISPLAY_REWARDED_VIDEO:String = "didDisplayRewardedVideo";
    • 



/** Fired when a video is about to be displayed.


    

  • Arguments: (location:String) */
public static const WILL_DISPLAY_VIDEO:String = "willDisplayVideo";
    • 



/** Fired if Chartboost plugin pauses click actions awaiting confirmation from the user.


    

  • Arguments: None */
public static const DID_PAUSE_CLICK_FOR_COMFIRMATION:String = "didPauseClickForConfirmation";
    • 



/** iOS only: Fired when the App Store sheet is dismissed, when displaying the embedded app sheet.


    

  • Arguments: None */
public static const DID_COMPLETE_APP_STORE_SHEET_FLOW:String = "didCompleteAppStoreSheetFlow";
    •
<

Testing Your Integration

To test the setup, start a publishing campaign, add the app you've been integrating with the plugin to the campaign, then build your project to a device.

If you can see Chartboost test interstitials where you've called for them in your code, you're good to go! Be sure to disable Test Mode (from the App Settings page) so you can see actual network ads:

Chartboost Support

More comprehensive documentation on the Chartboost Adobe AIR Plugin as well as the entire Chartboost system can be found at the Chartboost Help Site. You can also use the help site to contact the Chartboost Support Team if you're still experiencing any issues or have questions beyond the scope of the documentation.