Android Quickstart Guide

The following Quickstart Guide will help you set up the AdAdapted Android SDK in your app. Please email us at publishers@adadapted.com with any questions!

Downloading / Importing the SDK

Version Framework (.aar) Release Date
2.1.0 SDK Version 2.1.x Upgrade Guide 2020-05-22
2.0.2 Advertising Framework 2019-09-07

For details on recent updates to the Android SDK, please see the release changelog.

Setting up the SDK

Add the SDK to your project (2.1.x and above)

To add the AdAdapted Android SDK to your app, simply add the following repository url to your root build.gradle:

allprojects {
            repositories {
                    ...
                    maven { url 'https://jitpack.io' }
            }
    }

Then add the dependency (based on latest release):

dependencies {
    implementation 'com.gitlab.adadapted:android_sdk:2.1.0'
}

Finally, do a gradle sync and you should be all set to begin using the AdAdapted Android SDK!

Add the SDK to your project (2.0.x and below)

After downloading the SDK, drag the file from your downloads folder to your project “libs” directory. This should be located in path_to_project/app/libs. In Android Studio, in the Gradle Scripts section, you will now need to modify both project and module build.gradle files. First, open the project build.gradle file. Under allprojects, you’ll need to add a couple of lines within the repositories braces:

allprojects {
    repositories {
        jcenter()
        flatDir {
            dirs 'libs'
        }
    }
}

In the module build.gradle file, add the following three lines in your dependencies:

implementation (name: 'adadapted_sdk', ext: 'aar')
implementation 'com.google.android.gms:play-services-ads:10.2.6'
implementation 'com.android.volley:volley:1.1.0'

Note: Android play-services may have been updated since the last revision to this guide, but you should still be able to use the latest version of play-services without any trouble.

Finally, do a gradle sync and you should be all set to begin using the AdAdapted Android SDK!

Using the SDK

Initialization

There are only a few steps required to initialize the SDK. We recommend creating your own class that extends Application. The following guide assumes that this is what you have done, but you can also initialize the SDK inside your primary launcher activity.

Inside the onCreate() method of your class definition, add the following lines:

@Override
public void onCreate() {
    // ...

    // Replace the API_KEY with the key provided to you
    // When your app is ready for release, change DEV to PROD
    AdAdapted.INSTANCE
        .withAppId("API_KEY")
        .inEnv(AdAdapted.Env.DEV)
        .start(this)
}
@Override
public void onCreate() {
    // ...

    // Replace the API_KEY with the key provided to you
    // When your app is ready for release, change DEV to PROD
    AdAdapted.init()
        .withAppId("API_KEY")
        .inEnv(AdAdapted.Env.DEV)
        .start(this)
}

Next, you will need to modify the AndroidManifest.xml file. First update your permissions to include:

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

Now, assuming you created a separate Application class, make sure to add the following attribute inside the <application> tag:

android:name=".YourApplicationName"

Also inside the <application> tag, add this activity:

<activity
    android:name="com.adadapted.android.sdk.ui.activity.AaWebViewPopupActivity"
    android:label="WebViewPopupActivity">
</activity>

This last code snippet ensures that any content ads will work properly when clicked.

In the next section you can add a zone and test the SDK to make sure that the ads display.

Add a zone to your app

A zone is a space in the application in which an ad may be displayed. Zones have a known size (to fit properly in the UI) and a numeric ID, which is provided by AdAdapted and exposed to the SDK in the code. Once set up in the app, the AdAdapted platform can serve ads to the zone via the SDK.

First, inside one of your visible layout files, add the following view:

<com.adadapted.android.sdk.ui.view.AaZoneView
    android:id="@+id/mainActivityAd"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"/>

In the example code above, the zone view was placed in activity_main.xml with the ID, “mainActivityAd”. Now, in the corresponding Java file (in this case MainActivity.java), update your onCreate() method to assign this new view a zone ID at initialization. This serves to associate the zone in the app with an ad on the AdAdapted platform.

AaZoneView mainActivityAd = (AaZoneView)findViewById(R.id.mainActivityAd);

// Substitute zone_id for your own numeric zone ID
mainActivityAd.init("zone_id")

Lastly, again within MainActivity.java, you should add the following two lifecycle methods:

@Override
public void onStart() {
    // ...

    mainActivityAd.onStart();
}

@Override
public void onStop() {
    mainActivityAd.onStop();

    // ...
}

That’s it! Now compile and run your app and you should see your first ad!

Add-to-List

Some ads have the ability to pass product information back to the app. The best way to use this information is to add the product(s) to a list. To do this, use the activity or fragment where the ad interaction is taking place to implement AdContentListener:

public class MainActivity extends AppCompatActivity implements AdContentListener {
    // ...
}

Next, you’ll need to override the onContentAvailable method, as shown below:

@Override
public void onContentAvailable(final String zoneId, final AdContent content) {
    Log.d(TAG,"In-app content available");
    final List<AddToListItem> items = content.getItems();

    for (final AddToListItem item : items) {
        Log.d(TAG,"AddToListItem: " + item.getTitle());
        // Take some action on item
    }

    // Acknowledge the items were added to the list
    content.acknowledge();
}

The AdContent object can be unpacked using the getItems() method and will return a list of 1 or more AddToListItem objects. Each AddToListItem may contain several pieces of information about the product(s) in the current ad (product title, image url, etc.). Please reference the JSON Payload Data Model section of the full documentation for more information on the AddToListItem payload.

Also notice the call to content.acknowledge() in the code snippet above. This call is necessary to acknowledge that the user actually clicked on the ad and that the product was added to the list. If this call isn’t included, your app may report incorrect clicks and performance data. If the payload was processed, but the product was not added to the list for whatever reason, you can indicate this as shown below:

content.failed("Reason for not adding product to list")

Finally, you’ll need to add and remove the listener in the lifecycle methods. This is achieved by passing an AdContentListener into onStart() and onStop() configured above:

 @Override
 public void onStart() {
     // ...

     mainActivityAd.onStart(this);
 }

 @Override
 public void onStop() {
     mainActivityAd.onStop(this);

     // ...
 }

List Manager

To improve the user experience and enhance overall advertising performance, AdAdapted provides the List Manager as a part of our integration with new app partners. There are three primary methods that can be easily implemented for this purpose as a part of the normal list lifecycle of the app.

First, whenever a product is added to a list, acknowledge this by calling itemAddedToList():

AdAdaptedListManager.itemAddedToList("added_product_name");

Or, if the product has been added to a specific list:

AdAdaptedListManager.itemAddedToList("list_name", "added_product_name");

Over time, items may be crossed off (purchased / completed) or removed (no longer wish to purchase / not completed). Both of these events should be acknowledged as well:

AdAdaptedListManager.itemCrossedOffList("crossed_off_product_name");

AdAdaptedListManager.itemDeletedFromList("deleted_product_name");

The above methods are also overloaded to include a list name argument as the first parameter (see itemAddedToList() example above).