SAAndroidSDK DocumentationRelease 3.6.5

Gabriel Coman

April 12, 2016

Contents

1 Getting started 31.1 Creating Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Adding Placements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Getting started 72.1 Add the SDK through Gradle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Add the SDK as a JAR library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3 Finishing up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 Configuring the SDK 11

4 Loading ads 134.1 Saving an Ad for later use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.2 Saving multiple Ads for later use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.3 Dealing with orientation changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5 Display Ads 175.1 Banner ads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6 Parental Gate 19

7 Callbacks 21

8 Full Examples 23

i

ii

SAAndroidSDK Documentation, Release 3.6.5

The SuperAwesome Android SDK (Software Development Kit) lets you to easily add COPPA compliant advertise-ments to your apps.

Info ContentsVersion 3.6.5GitHub https://github.com/SuperAwesomeLTD/sa-mobile-sdk-android/tree/develop_v3Support devsupport@superawesome.tvLicense LICENSE.txtDemo sa-android-sdk-demo.zip

Table of Contents:

Contents 1

SAAndroidSDK Documentation, Release 3.6.5

2 Contents

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 inthe dashboard representing one of your own apps.

Each app has a number of associated parameters such as ID, name, domain (or iTunes URL), etc. The name anddomain can be configured when you create the app, while the ID is automatically assigned so as to be unique to eachapp.

3

SAAndroidSDK Documentation, Release 3.6.5

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 yourapp, 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 remem-ber 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

SAAndroidSDK Documentation, Release 3.6.5

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 PlacementStandard Mobile 320x50px Mobile banner 30471SM Mobile 300x50px Small mobile banner 30476Interstitial 320x480px Mobile fullscreen (portrait) 30473Interstitial LS 480x320px Mobile fullscreen (landscape) 30474Leaderboard 728x90px Tablet banner 30475MPU 300x250px Smaller tablet banner 30472LG Interstitial 768x1024px Tablet fullscreen (portrait) 30477LG Interstitial LS 1024x768px Tablet fullscreen (landscape) 30478Video Preroll Flexible Mobile & tablet video 30479Gamewall Flexible Gamewall N/A

1.2. Adding Placements 5

SAAndroidSDK Documentation, Release 3.6.5

6 Chapter 1. Getting started

CHAPTER 2

Getting started

Note: This document assumes:

• an Android Studio project called AndroidDemo

• containing a single activity called MainActivity

• and a manifest file called AndroidManifest

2.1 Add the SDK through Gradle

The simplest way of installing the AwesomeAds SDK in Android Studio is to download the AAR library throughGradle.

Just include the following in your module’s build.gradle file (usually the file under MyApplication/app/):

repositories {maven {

url "http://dl.bintray.com/sharkofmirkwood/maven"}

}

dependencies {compile 'tv.superawesome.sdk:sa-sdk:3.6.4@aar'compile 'com.google.android.gms:play-services:8.4.0'

}

7

SAAndroidSDK Documentation, Release 3.6.5

2.2 Add the SDK as a JAR library

If you’re running an environment which does not support Gradle, then you’ll need to add the SDK manually.

1. Download sa-sdk-3.6.4.jar

You’ll need to add it to your project’s lib folder, usually AndroidDemo/app/libs. The libs folder should be located onthe same level as the src and build folders. Once it’s there, in Android Studio you’ll need to select it, right-click it andthen Add as Library.

2. Download sa-sdk-res.zip and unzip it.

8 Chapter 2. Getting started

SAAndroidSDK Documentation, Release 3.6.5

You’ll find two folders inside:

• drawable: containing a bunch of PNG files; copy the PNG files inside your projects’ drawable folder

• layout: containing a buch of XML files; copy the XML files inside your projects’ layout folder

3. Add the following items in your AndroidManifest file, under the Application tag:

<activity android:name="tv.superawesome.sdk.views.SAVideoActivity$SAVideoActivityInner"android:label="SAVideoActivity"android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen"></activity>

<activity android:name="tv.superawesome.sdk.views.SAInterstitialActivity$SAInterstitialActivityInner"android:label="SAInterstitialActivity"android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen"android:configChanges="keyboardHidden|orientation|screenSize"></activity>

<service android:name="tv.superawesome.lib.sautils.SAAsyncTask$SAAsync" android:exported="false"/>

2.2. Add the SDK as a JAR library 9

SAAndroidSDK Documentation, Release 3.6.5

This will register two new activities and one service for your application, all needed by the SDK.

4. At the end you’ll also need to add Google Play Services as a dependency to the project, either as a JAR orthrough Gradle.

2.3 Finishing up

The last thing to do, whether you’ve added the SuperAwesome SDK through Gradle or the Jar archive is to setup somepermissions in the AndroidManifest file:

<uses-permission android:name="android.permission.INTERNET"/>

10 Chapter 2. Getting started

CHAPTER 3

Configuring the SDK

Once you’ve integrated the SuperAwesome SDK, you can access all functionality by including the SuperAwesomelibrary:

import tv.superawesome.*;

There are also a few global SDK parameters you can change according to your needs:

Parameter Values MeaningConfiguration

Production *Staging

Should the SDK get ads fromthe production or test server.Test placements are all onproduction.

Test mode

EnabledDisabled *

Should the SDK serve test ads. Fortestplacements (30471, 30476, etc) mustbe Enabled.

• = denotes default values

You can leave these settings as they are or change them to fit your testing or production needs. You can specify themin your activity class (MainActivity.java).

import tv.superawesome.*;

public class MainActivity extends AppCompatActivity {

@Overrideprotected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);setContentView(R.layout.activity_main);

SuperAwesome.getInstance().setConfigurationProduction();// SuperAwesome.getInstance().setConfigurationStaging();

SuperAwesome.getInstance().enableTestMode();// SuperAwesome.getInstance().disableTestMode();

11

SAAndroidSDK Documentation, Release 3.6.5

// this is mandatory!SuperAwesome.getInstance().setApplicationContext(getApplicationContext());

}}

12 Chapter 3. Configuring the SDK

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’llwant to display. Then, once that data is successfully loaded, you can finally show the ad. The two steps are independentof 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 30471. A good place to do this is in anActivity’s onCreate function, 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. You’ll usually need just oneinstance per Activity.

import tv.superawesome.*;

public class MainActivity extends Activity {

// private SALoader class memberprivate SALoader loader = null;

@Overrideprotected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);setContentView(R.layout.activity_main);

// setup the test modeSuperAwesome.getInstance().enableTestMode();

// load ads only when the// activity starts for the first timeif (savedInstanceState == null) {

// initialize the loader objectloader = new SALoader();// call the Load ad functionloader.loadAd(30471, null);

}}

}

The loadAd(30471, null) 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(intplacementId), to notify you of either success or failure. In order to use these callbacks:

13

SAAndroidSDK Documentation, Release 3.6.5

• your MainActivity class must implement the SALoaderListener:

public class MainActivity extends Activityimplements SALoaderListener

• the MainActivity must be set as delegate for the SALoader object created earlier:

public class MainActivity extends Activityimplements SALoaderListener {

// private SALoader class memberprivate SALoader loader = null;

@Overrideprotected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);setContentView(R.layout.activity_main);

// setup the test modeSuperAwesome.getInstance().enableTestMode();

// load ads only when the// activity starts for the first timeif (savedInstanceState == null) {

// initialize the loader objectloader = new SALoader();// call the Load ad function// notice the second function parameter is not "null",// but "this"!loader.loadAd(30471, this);

}}

}

• finally, your MainActivity must also implement the two callback methods mentioned above:

public class MainActivity extends Activityimplements SALoaderListener {

// rest of the implementation ...

@Overridepublic void didLoadAd(SAAd ad) {

// at this moment ad data is readyad.print();

}

@Overridepublic void didFailToLoadAdForPlacementId(int i) {

// at this moment no ad could be found}

}

You’ll notice that didLoadAd: has a callback parameter of type SAAd. The SAAd class contains all the informationneeded to actually display an ad, such as format (image, video), dimensions, click URL, video information, creativedetails, etc. You can find out all details by calling the print function, as shown in the example.

14 Chapter 4. Loading ads

SAAndroidSDK Documentation, Release 3.6.5

4.1 Saving an Ad for later use

To save ads for later use, you can do something like this:

public class MainActivity extends Activityimplements SALoaderListener {

// private SALoader class memberprivate SALoader loader = null;

// declare a SAAd object to save data inprivate SAAd bannerAdData = null;

@Overrideprotected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);setContentView(R.layout.activity_main);

SuperAwesome.getInstance().setConfigurationProduction();SuperAwesome.getInstance().enableTestMode();

// load ads only when the// activity starts for the first timeif (savedInstanceState == null) {

// initialize the loader objectloader = new SALoader();// call the Load ad functionloader.loadAd(30471, this);

}}

@Overridepublic void didLoadAd(SAAd ad) {

// at this moment ad data is readybannerAdData = ad;

}

@Overridepublic void didFailToLoadAdForPlacementId(int i) {

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

public class MainActivity extends Activityimplements SALoaderListener {

// private SALoader class memberprivate SALoader loader = null;

// declare a SAAd object to save data inprivate SAAd bannerAdData = null;

4.1. Saving an Ad for later use 15

SAAndroidSDK Documentation, Release 3.6.5

private SAAd interstitialAdData = null;private SAAd videoAdData = null;

@Overrideprotected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);setContentView(R.layout.activity_main);

SuperAwesome.getInstance().setConfigurationProduction();SuperAwesome.getInstance().enableTestMode();

// load ads only when the// activity starts for the first timeif (savedInstanceState == null) {

// initialize the loader objectloader = new SALoader();

// call the Load ad function successively// to load three ads in parallelloader.loadAd(30471, this);loader.loadAd(30473, this);loader.loadAd(30479, this);

}}

@Overridepublic void didLoadAd(SAAd ad) {

if (ad.placementId == 30471) {bannerAdData = ad;

}else if (ad.placementId == 30473) {

interstitialAdData = ad;}else if (ad.placementId == 30479) {

videoAdData = ad;}

}

@Overridepublic void didFailToLoadAdForPlacementId(int i) {

// at this moment no ad could be found}

}

4.3 Dealing with orientation changes

16 Chapter 4. Loading ads

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 suppose we have the same setup as the previous section, but we’ll also add four SuperAwesome display objectsthat we’ll want to show at the press of a button in our app.

import tv.superawesome.*;

public class MainActivity extends Activityimplements SALoaderListener {

// private SALoader class memberprivate SALoader loader = null;

// declare a SAAd object to save data inprivate SAAd bannerAdData = null;private SAAd interstitialAdData = null;private SAAd videoAdData = null;

// display objectsprivate SABannerAd banner = null;private SAVideoAd video = null;private SAVideoActivity fvideo = null;private SAInterstitialActivity interstitial = null;

// rest of the implementation}

5.1 Banner ads

To add a SABannerAd object to your activity, first add it in the associated xml file (in this case /lay-outs/activity_main.xml):

<tv.superawesome.sdk.views.SABannerAdandroid:id="@+id/bannerid"android:layout_width="match_parent"android:layout_height="100dp"/>

Then in your activity:

17

SAAndroidSDK Documentation, Release 3.6.5

18 Chapter 5. Display Ads

CHAPTER 6

Parental Gate

19

SAAndroidSDK Documentation, Release 3.6.5

20 Chapter 6. Parental Gate

CHAPTER 7

Callbacks

21

SAAndroidSDK Documentation, Release 3.6.5

22 Chapter 7. Callbacks

CHAPTER 8

Full Examples

23