SAAdobeAIRSDK Documentation

Transcription

1 SAAdobeAIRSDK Documentation Release Gabriel Coman April 12, 2016

2

3 Contents 1 Getting started Creating Apps Adding Placements Getting started For Android builds For ios builds Configuring the SDK 11 4 Loading ads Saving an Ad for later use Saving multiple Ads for later use Display Ads Banner ads In-Line Video ads Interstitial ads Fullscreen video ads Parental Gate 21 7 Callbacks Standard ad callbacks Parental gate callbacks Video callbacks Full Examples Simple Example Complex Example i

4 ii

5 The SuperAwesome Adobe AIR SDK (Software Development Kit) lets you to easily add COPPA compliant advertisements to your apps. Info Contents Version ios Support ios 6.0+ Android Support API 11: Android 3.0 (Honeycomb) GitHub Support License LICENSE.txt Table of Contents: Contents 1

6 2 Contents

7 CHAPTER 1 Getting started The first step in integrating the SuperAwesome SDK is to register on the SuperAwesome Dashboard. From here you ll be able to create apps and placements, obtain performance reports (number of impressions, clicks), view current revenue, etc. 1.1 Creating Apps When first logging in to the dashboard, the first thing you ll want to do is create one or more Apps, with each app in the dashboard representing one of your own apps. Each app has a number of associated parameters such as ID, name, domain (or itunes / Google Play URL), etc. The name and domain can be configured when you create the app, while the ID is automatically assigned so as to be unique to each app. 3

8 In turn, each app can have multiple placements. 1.2 Adding Placements Placements represent ad units where creatives will be served. Creatives are the actual ad data that gets shown in your app, like images, videos, interactive rich media content, etc. Each placement has a number of associated parameters like ID, name, format, dimension. The placement s ID is a unique identifier associated with it. In the SDK it will be used to load ad data. The name is a human readable identifier. It s good practice to name your placements something easy to remember or suggestive. The format can be video, display, etc, and informs you of what type of ads should be run on the placement. The dimensions give you an idea of where you should try to place the ad in your app. 4 Chapter 1. Getting started

9 Below you can find a description of all mobile placement types, as well as test IDs, that have a 100% fill rate. Name Size Description Test Placement Standard Mobile 320x50px Mobile banner SM Mobile 300x50px Small mobile banner Interstitial 320x480px Mobile fullscreen (portrait) Interstitial LS 480x320px Mobile fullscreen (landscape) Leaderboard 728x90px Tablet banner MPU 300x250px Smaller tablet banner LG Interstitial 768x1024px Tablet fullscreen (portrait) LG Interstitial LS 1024x768px Tablet fullscreen (landscape) Video Preroll Flexible Mobile & tablet video Gamewall Flexible Gamewall N/A 1.2. Adding Placements 5

10 6 Chapter 1. Getting started

11 CHAPTER 2 Getting started The SuperAwesome Adobe AIR SDK, as of version 3.1.6, is built as an AIR Native Extension in order to work together with the SuperAwesome Android or ios SDK. This in turn allows you to harness the full power of native components, such as video based on AVFoundation / VideoView technology, proper WebViews, better fullscreen experience, etc. Note: This document assumes: a Flash Builder ActionScript Mobile Project named AdobeAIRDemo, containing a single.as file, called AdobeAIRDemo.as, that acts as main class. To begin integrating the SDK download the latest version of the SAAIR.ane file, then right-click on your project in the Package Explorer and select Properties : 7

12 8 Chapter 2. Getting started

13 Then go to ActionScript Build Path and then to the Native Extensions tab. Lastly you ll want to add the.ane file you just downloaded by clicking on the Add ANE button. If you follow all these steps the SuperAwesome AIR SDK will be installed as a Native Extension. There are however a couple of additional steps to do for either the Android or ios build. 2.1 For Android builds When building your Adobe AIR app as an Android application, you ll often want to change the associated XML file that AIR generates alongside your project to add or change different parameters to make it suitable for deploying on Android. Using the SuperAwesome AIR SDK is no exception, and you ll have to add the following lines to the Android / Manifest Additions part of the xml file. <android> <manifestadditions><![cdata[ <manifest android:installlocation="auto"> <uses-permission android:name="android.permission.access_network_state"/> <uses-permission android:name="android.permission.access_wifi_state"/> <uses-permission android:name="android.permission.internet"/> <application android:allowbackup="true"> <activity android:name="tv.superawesome.sdk.views.sainterstitialactivity$sainterstitialac android:label="sainterstitialactivity" android:theme="@android:style/theme.black.notitlebar.fullscreen" android:configchanges="keyboardhidden orientation screensize"></activity> <activity android:name="tv.superawesome.sdk.views.savideoactivity$savideoactivityinner" android:label="savideoactivity" android:theme="@android:style/theme.black.notitlebar.fullscreen"></activity> <service android:name="tv.superawesome.lib.sautils.saasynctask$saasync" android:exported= <meta-data android:name="com.google.android.gms.version" android:value="8.4.0"/> </application> </manifest> ]]></manifestadditions> <containsvideo>true</containsvideo> </android> As you can see this adds some new permissions the SDK needs (access to Internet) and also adds two activities (SAInterstitialActivity and SAVideoActivity) and a new service (SAAsyncTask) For Android builds 9

14 2.2 For ios builds This feature is not yet available, but will be soon. 10 Chapter 2. Getting started

15 CHAPTER 3 Configuring the SDK Once you ve integrated the SuperAwesome SDK, you can access all functionality by including the SuperAwesome library in any actionscript file you want to use it. import tv.superawesome.* or including one of the relevant headers import tv.superawesome.superawesome; import tv.superawesome.saloader; import tv.superawesome.saad; import tv.superawesome.sabannerad; import tv.superawesome.savideoad; import tv.superawesome.safullscreenvideoad; import tv.superawesome.sainterstitialad; import tv.superawesome.interfaces.saloaderinterface; import tv.superawesome.interfaces.saadinterface; import tv.superawesome.interfaces.saparentalgateinterface; import tv.superawesome.interfaces.savideoadinterface; There are also a few global SDK parameters you can change according to your needs: Parameter Values Meaning Configuration Test mode Production * Staging Should the SDK get ads from the production or test server. Test placements are all on production. Enabled Disabled * Should the SDK serve test ads. For test placements (30471, 30476, etc) must be Enabled. = denotes default values You can leave these settings as they are or change them to fit your testing or production needs, as follows: // Import all the SuperAwesome SDK library // with all subsequent namespaces import tv.superawesome.* 11

16 // // AdobeAIRDemo is a generic Flash Builder // Mobile Project that will be exported to // either Android or ios { public function AdobeAIRDemo() { SuperAwesome.getInstance().setConfigurationProduction(); // SuperAwesome.getInstance().setConfigurationStaging(); SuperAwesome.getInstance().enableTestMode(); // SuperAwesome.getInstance().disableTestMode(); 12 Chapter 3. Configuring the SDK

17 CHAPTER 4 Loading ads After you ve created your Apps and Placements in the dashboard and successfully integrated the SDK in your project, the next logical step is to actually start showing ads. For this purpose, the SDK employs a two-step process: First, you ll need to load ad data for each placement you ll want to display. Then, once that data is successfully loaded, you can finally show the ad. The two steps are independent of each other so you can easily pre-load ads for later use, saving performance. In the code snippet below we ll start by loading data for the test placement A good place to do this is in the constructor of a class descending from Sprite (such as AdobeAIRDemo), where we ll create a SALoader object to help us. SALoader is a SDK class whose sole role is to load, parse, process and validate ad data by comunicating with the native SDK (either ios or Android). You ll usually need just one instance of it. import tv.superawesome.* { // declare a new SALoader object private var loader:saloader = null; public function AdobeAIRDemo() { // configure SDK to test mode SuperAwesome.getInstance().enableTestMode(); // create the loader and load ad loader = new SALoader(); loader.loadad(30471); The loadad(30471) function loads data asynchronously, so as not to block the main UI thread. When it s done, it calls two important callback methods, didloadad(saad loadedad) and didfailtoloadadforplacementid(int placementid), to notify you of either success or failure. In order to use these callbacks: your main class (AdobeAIRDemo) must implement the SALoaderInterface implements SALoaderInterface it must be set as delegate for the SALoader object created earlier 13

18 implements SALoaderInterface { // declare a new SALoader object private var loader:saloader = null; public function AdobeAIRDemo() { // configure SDK to test mode SuperAwesome.getInstance().enableTestMode(); // create the loader and load ad loader = new SALoader(); // assign loader's delegate object loader.delegate = this; loader.loadad(30471); finally, your AdobeAIRDemo class must also implement the two callback methods mentioned above implements SALoaderInterface { // rest of your code, the constructor, etc... public function didloadad(ad: SAAd): void { // at this moment ad data is ready ad.print(); public function didfailtoloadad(placementid: int): void { // at this moment no ad could be found You ll notice that didloadad(saad ad) has a callback parameter of type SAAd. The SAAd class contains all the information needed to actually display an ad, such as format (image, video), dimensions, click URL, video information, creative details, etc. You can find out all details by calling the print() function, as shown in the example. 4.1 Saving an Ad for later use To save ads for later use, you can do something like this: import tv.superawesome.* implements SALoaderInterface { // declare a new SALoader object private var loader:saloader = null; // declare a SAAd object as a class member variable 14 Chapter 4. Loading ads

19 private var banneraddata: SAAd = null; public function AdobeAIRDemo() { // configure SDK to test mode SuperAwesome.getInstance().enableTestMode(); // create the loader loader = new SALoader(); // assign loader's delegate object loader.delegate = this; loader.loadad(30471); public function didloadad(ad: SAAd): void { // save current loaded ad into // class member variable banneraddata banneraddata = ad; public function didfailtoloadad(placementid: int): void { // at this moment no ad could be found 4.2 Saving multiple Ads for later use Finally, if you want to load multiple ads and save them for later use, you can do as such: import tv.superawesome.* implements SALoaderInterface { // declare a new SALoader object private var loader: SALoader = null; // declare a number of SAAd objects private var banneraddata: SAAd = null; private var interstitialaddata: SAAd = null; private var videoaddata: SAAd = null; public function AdobeAIRDemo() { // configure SDK to test mode SuperAwesome.getInstance().enableTestMode(); // create the loader and set delegate loader = new SALoader(); loader.delegate = this; // load ad data for a banner loader.loadad(30471); // and for an interstitial banner.loadad(30473); // and for a video 4.2. Saving multiple Ads for later use 15

20 banner.loadad(30479); public function didloadad(ad: SAAd): void { if (ad.placementid == 30471) { banneraddata = ad; else if (ad.placementid == 30473) { interstitialaddata = ad; else if (ad.placementid == 30479) { videoaddata = ad; public function didfailtoloadad(placementid: int): void { // at this moment no ad could be found 16 Chapter 4. Loading ads

21 CHAPTER 5 Display Ads In the next sections we ll see how to display banners, inline video ads, interstitials and fullscreen video ads. We ll assume we have the same setup as the previous section, but we ll also add four SuperAwesome display objects that we ll want to show at the press of a button in our app. import tv.superawesome.* implements SALoaderInterface { // the loader object private var loader: SALoader = null; // ad data private var banneraddata: SAAd = null; private var interstitialaddata: SAAd = null; private var videoaddata: SAAd = null; // the four display objects private var banner: SABannerAd = null; private var interstitial: SAInterstitialAd = null; private var video: SAVideoAd = null; private var fvideo: SAFullscreenVideoAd = null; 5.1 Banner ads To following code snippet shows you how to add a SABannerAd object to your app. implements SALoaderInterface { // load ad data here... public function showbanner() { if (banneraddata!= null) { var frame = new Rectangle(250, 450, 640, 100); banner = new SABannerAd(frame); banner.setad(banneraddata); 17

22 banner.play(); Notice that the SABannerAd class is calling the Android or ios native components to display on screen, so there s no need for you to add it as a child to the scene. The two functions to pay attention here are setad(saad ad) and play(). setad(saad ad) takes a SAAd object as parameter, in this case banneraddata. It tells the banner what ad data to try to display. play() actually starts the display process on screen. 5.2 In-Line Video ads SAVideoAd gets initialized and added in a similar way: implements SALoaderInterface { // load ad data here... public function showinlinevideo() { if (videoaddata!= null) { var frame = new Rectangle(250, 450, 640, 100); video = new SAVideoAd(frame); video.setad(videoaddata); vidoe.play(); As with SABannerAd, the SAVideoAd object must not be added to the view hierarchy, since it calls native methods. It also implements the same two functions: setad(saad ad) and play(). 5.3 Interstitial ads Interstitial ads are represented by objects of type SAInterstitialAd. implements SALoaderInterface { // load ad data here... public function showinterstitial() { if (interstitialaddata!= null) { interstitial = new SAInterstitialAd(); interstitial.setad(interstitialaddata); interstitial.play(); 18 Chapter 5. Display Ads

23 Again, notice the presence of setad(saad ad) and play() - they perform the same role as for banner or video ads. The difference here is that the SAInterstitialAd constructor does not take a Rect object as parameter. That s because interstitial as shown as fullscreen ads, on top of any existing content. For Android a new Activity will be launched and for ios a new View Controller. Interstitial ads have their own SDK-provided close button. 5.4 Fullscreen video ads Finally, fullscreen video ads are represented by SAFullscreenVideoAd. implements SALoaderInterface { // load ads here... public function showvideo() { if (videoaddata!= null) { fvideo = new SAFullscreenVideoAd(); fvideo.setad(ad); fvideo.shouldshowclosebutton = true; fvideo.shouldautomaticallycloseatend = true; fvideo.play(); They re similar to interstitial ads, but notice there are two parameters you can set, shouldshowclosebutton and shouldautomaticallycloseatend Fullscreen video ads 19

24 20 Chapter 5. Display Ads

25 CHAPTER 6 Parental Gate Parental gates are used in apps targeted towards kids to prevent them from engaging in commerce or following links out of an app to websites, social networks, or other apps without the knowledge of their parent or guardian. A parental gate presents an adult level task which must be completed in order to continue. You can enable our parental gate on banners, interstitials and video ads. banner.isparentalgateenabled = true; 21

26 22 Chapter 6. Parental Gate

27 CHAPTER 7 Callbacks Once an ad starts playing, it will send back callbacks to notify you that it has finished different lifecycle activities. To respond to them we ll use a similar interface / delegate pattern as with SALoaderInterface. 7.1 Standard ad callbacks To catch standard ad callbacks: your class must implement the SAAdInterface interface: implements SALoaderInterface, SAAdInterface { private var banneraddata: SAAd = null; private var banner: SABannerAd = null; // rest of the implementation... the class must be set as delegate for your display objects: implements SALoaderInterface, SAAdInterface { // rest of the implementation... public function showbanner() { if (banneraddata!= null) { var frame = new Rectangle(250, 450, 640, 100); banner = new SABannerAd(frame); banner.setad(banneraddata); banner.addelegate = this; banner.play(); your class must implement the callback methods specified by SAAdInterface: 23

28 implements SALoaderInterface, SAAdInterface { // rest of the implementation... public function adwasshown(placementid: int): void { // called when an ad is first shown public function adfailedtoshow(placementid: int): void { // called when an ad is not shown // because of some internal errors // or lack of internet connectivity public function adwasclosed(placementid: int): void { // available only for interstitial and // fullscreen video ads // // signals when an ad is closes public function adwasclicked(placementid: int): void { // called when an ad is clicked public function adhasincorrectplacement(placementid: int): void { // called when an ad has an incorrect // placement type for the ad it's trying to // show // e.g. a SAVideoAd object with a banneraddata // SAAd object 7.2 Parental gate callbacks To catch parental gate callbacks: Your class must implement the SAParentalGateInterface: implements SALoaderInterface, SAParentalGateInterface { private var banneraddata: SAAd = null; private var banner: SABannerAd = null; // rest of the implementation... the class must be set as delegate for your display objects: 24 Chapter 7. Callbacks

29 implements SALoaderInterface, SAParentalGateInterface { // rest of the implementation... public function showbanner() { if (banneraddata!= null) { var frame = new Rectangle(250, 450, 640, 100); banner = new SABannerAd(frame); banner.setad(banneraddata); bad.isparentalgateenabled = true; bad.parentalgatedelegate = this; banner.play(); your class must implement the callback methods specified by SAAdInterface: implements SALoaderInterface, SAParentalGateInterface { // rest of the implementation... public function parentalgatewascanceled(placementid: int): void { // this function is called when a // parental gate pop-up "cancel" button is pressed public function parentalgatewasfailed(placementid: int): void { // this function is called when a // parental gate pop-up "continue" button is // pressed and the parental gate // failed (because the numbers weren't OK) public function parentalgatewassucceded(placementid: int): void { // this function is called when a // parental gate pop-up "continue" button is // pressed and the parental gate succeeded 7.3 Video callbacks To catch video ad callbacks (available only for SAVideoAd and SAFullscreenVideoAd objects): implements SALoaderInterface, SAVideoAdInterface { 7.3. Video callbacks 25

30 private var videoaddata: SAAd = null; private var video: SAVideoAd = null; // rest of the implementation... the class must be set as delegate for your display objects: implements SALoaderInterface, SAVideoAdInterface { // rest of the implementation... public function showvideo() { if (videoaddata!= null) { var frame = new Rectangle(150, 50, 640, 100); video = new SAVideoAd(frame); video.setad(videoaddata); video.videoaddelegate = this; video.play(); your class must implement the callback methods specified by SAAdInterface: implements SALoaderInterface, SAVideoAdInterface { // rest of the implementation... public function adstarted(placementid: int): void { // fired when an ad has started public function videostarted(placementid: int): void { // fired when a video ad has started public function videoreachedfirstquartile(placementid: int): void { // fired when a video ad has reached 1/4 of total duration public function videoreachedmidpoint(placementid: int): void { // fired when a video ad has reached 1/2 of total duration public function videoreachedthirdquartile(placementid: int): void { // fired when a video ad has reached 3/4 of total duration public function videoended(placementid: int): void { // fired when a video ad has ended 26 Chapter 7. Callbacks

31 public function adended(placementid: int): void { // fired when an ad has ended public function alladsended(placementid: int): void { // fired when all ads have ended 7.3. Video callbacks 27

32 28 Chapter 7. Callbacks

33 CHAPTER 8 Full Examples 8.1 Simple Example The first example shows how you can add a video ad in your app with just a few lines of code. package { import flash.display.sprite; import flash.display.stagealign; import flash.display.stagescalemode; import flash.geom.rectangle; import tv.superawesome.*; implements SALoaderInterface { // declare the three main variables // needed by SuperAwesome to load & display // an Ad private var loader: SALoader = null; private var video: SAVideoAd = null; private var addata: SAAd = null; public function AdobeAIRDemo() { // set stage stage.align = StageAlign.TOP_LEFT; stage.scalemode = StageScaleMode.NO_SCALE; // config SuperAwesome SuperAwesome.getInstance().setConfigurationProduction(); SuperAwesome.getInstance().enableTestMode(); // load the ad loader = new SALoader(); loader.delegate = this; loader.loadad(30479); // implementation of the SALoaderInterface public function didloadad(ad: SAAd): void { // handle success 29

34 addata = ad; var frame = new Rectangle(0, 50, 640, 400); video = new SAVideoAd(frame); video.setad(addata); video.play(); public function didfailtoloadad(placementid: int): void { // failure 8.2 Complex Example This example shows how you can add different types of ads and make them respond to multiple callbacks. package { import flash.display.sprite; import flash.display.stagealign; import flash.display.stagescalemode; import flash.geom.rectangle; import tv.superawesome.*; implements SALoaderInterface, SAAdInterface, SAParentalGateInterface, SAVideoAdInterface { // loader private var loader: SALoader = null; // ad data private var banneraddata: SAAd = null; private var interstitialaddata: SAAd = null; private var videoaddata: SAAd = null; // display objects private var banner: SABannerAd = null; private var interstitial: SAInterstitialAd = null; private var fvideo: SAFullscreenVideoAd = null; public function AdobeAIRDemo() { // set stage stage.align = StageAlign.TOP_LEFT; stage.scalemode = StageScaleMode.NO_SCALE; // config SuperAwesome SuperAwesome.getInstance().setConfigurationProduction(); SuperAwesome.getInstance().enableTestMode(); // load the ad 30 Chapter 8. Full Examples

35 loader = new SALoader(); loader.delegate = this; loader.loadad(30471); loader.loadad(30473); loader.loadad(30479); // // three function to display ads - // these should be connected to buttons public function showbanner(): void { var frame = new Rectangle(0, 0, 320, 50); // it's good practice to always check // that the ad data is not null if (banneraddata) { banner = new SABannerAd(frame); banner.setad(banneraddata); banner.addelegate = this; banner.isparentalgateenabled = true; banner.parentalgatedelegate = this; banner.play(); public function showinterstitial(): void { if (interstitialaddata) { interstitial = new SAInterstitialAd(); interstitial.setad(interstitialaddata); interstitial.play(); public function showvideo(): void { if (videoaddata) { fvideo = new SAFullscreenVideoAd(); fvideo.setad(ad); fvideo.videoaddelegate = this; fvideo.shouldshowclosebutton = true; fvideo.shouldautomaticallycloseatend = true; fvideo.isparentalgateenabled = false; fvideo.play(); // // SAAdInterface implementation public function adwasshown(placementid: int): void { trace("ad " + placementid + " Was shown"); public function adfailedtoshow(placementid: int): void { public function adwasclosed(placementid: int): void { public function adwasclicked(placementid: int): void { public function adhasincorrectplacement(placementid: int): void { // // SAParentalGateInterface implementation 8.2. Complex Example 31

36 public function parentalgatewascanceled(placementid: int): void { public function parentalgatewasfailed(placementid: int): void { public function parentalgatewassucceded(placementid: int): void { // // SAVideoAdInterface implementation public function adstarted(placementid: int): void { public function videostarted(placementid: int): void { public function videoreachedfirstquartile(placementid: int): void { public function videoreachedmidpoint(placementid: int): void { trace("reached midpoint with " + placementid); public function videoreachedthirdquartile(placementid: int): void { public function videoended(placementid: int): void { public function adended(placementid: int): void { public function alladsended(placementid: int): void { trace("all video ads ended!"); 32 Chapter 8. Full Examples