App SDK - Android

Conversant also offers a server-to-server integration option for apps via certain mediation partners. Please see our Integrate reference page to learn more.

SDK Integration Overview

The Conversant SDK (formerly Greystripe SDK) provides a simple way to monetize your game or application via full-screen interstitial and banner ads. Once integrated with the SDK, your application will communicate with Conversant's system to retrieve and display ads. Conversant handles all ad sales, both in the US and internationally, and provides comprehensive backend accounting and reporting.

Please note that the following instructions apply to Conversant Android SDK v2.4.

Setup and Enrollment

You should already have signed up through Conversant's developer website and registered the apps you plan to ad-enable. For each app registered, you are given an App ID which can be found with the following steps here.

Please note that it may take some time before your registration and IDs are available. During this period you can use the testing IDs and process from our Testing page.

User Privacy

Our SDK does not provide personally identifiable information about users to us. However, we do collect device identifiers (specific device identifier depends on type of app, Google Play or Amazon Appstore), gross location data (via IP), as well as information about impressions and clicks. We also run surveys which allow users the option to anonymously report age, range, and gender.

If you’re ad-enabling your application with Conversant or any other network, it is your responsibility to let users know how information is handled. Your agreement with Conversant (particularly Sections 4.3, 4.4, 7.1) require you to disclose what information is being shared with any third party.

While we can’t offer specific legal advice (check with an attorney if you want some) or privacy policy language, Google provides this example. You should determine the best approach and language for you.

Supported Sizes and Platforms

Our recommended minimum Android API version is 8, which is OS version 2.2.

We support the following sizes on handsets (Small or Medium screen size):

  • Mobile Banner – 320x50
  • Fullscreen Interstitial - Fills the full device screen at any size.

And these ad sizes on tablets (Large screen size and bigger):

  • Mobile Banner – 320x50
  • Medium Rectangle – 300x250
  • Leaderboard – 728x90
  • Fullscreen Interstitial - Fills the full device screen at any size.

Application Approval Process - Please Read!

Application Approval! Your Android application must be reviewed and approved by Conversant before it will receive live ads.

In order to attract premium brand advertising, we need to verify that their ads will not appear in apps which may be crude or offensive. Applications that haven't been approved will receive $0.00 eCPM Public Service Ads (PSAs). Visit the Approval Process page for more details.

We review new apps on a weekly basis. However, you can expedite the review process by sending a request through our App Approval page. In your message, please provide us with the URL for your site or a link to your application on the App Store/Google Play. We try to answer all app approval requests within two business days so there isn't too large of delay before you begin generating ad revenue from the new users that downloaded your latest application build.

Testing

In order to test your SDK integration, a demo application is included in the Conversant SDK download folder. Inside this demo app, you will find a unique GUID specifically designed for testing. When integrated properly with this test GUID, your app will begin to receive Conversant themed test ads.

Getting Started with the Sample Project

To better understand the integration process of the Conversant Android SDK into your app, it is recommended that you first utilize the Sample App that is provided in the original SDK download folder.

Step 1

Open Eclipse and create a new project under File > New > Project

Android Demo

Step 2

Select Android > Android Project from Existing Code and click Next

Android Demo

Step 3

Select Browse under the Root Directory folder and the Open window will appear. Navigate to your downloaded conversant-android-sdk-master folder, selecting the ConversantSampleApp folder. Click Open and then Finish to load the project.

Android Demo

Step 4

Once the project loads and is viewable under the Package Explorer, right-click on the project com.conversantmedia.sdksample and select Properties

Android Demo

Step 5

Under the Properties window, select the Java Build Path under the left menu and then select the Libraries tab on the top bar. Under this view, select the Add External JARs button on the right menu and navigate to the conversant-android-sdk-2.4.0.jar file located in the downloaded SDK folder.

Android Demo

Step 6

Once the .jar file is added, select the Order and Export tab on the top bar and you will see the added conversant-android-sdk-2.4.0.jar file. Verify the box next to the newly added .jar file is checked and click OK.

Android Demo

Step 7

The Conversant Sample App is now ready to build and run!

Android SDK 2.4 Integration Guide

Step 1 - Download the Android SDK

  1. Download the Conversant iOS SDK from our GitHub page, clone the repository to your computer using Git or download directly.

  2. Download the Conversant Android SDK or clone the repository to your computer using Git.

  3. Review the latest releases notes.

  4. Navigate to the file location the unzipped/cloned files on your computer.

    In addition to the license and readme files, there are four folders:

    • "ConversantSDK" contains the Android 2.4.0 SDK .jar file
    • "ConversantSDKDocs" contains the navigational Java documents in web form
    • "ConversantSampleApp" contains a sample project for the Conversant's SDK, complete with a test GUID returning only Conversant themed ads

Step 2 - Add the Conversant SDK to your project

  1. To begin, open your project in your preferred program of choice(we recommend and show our demos using Eclipse)

  2. Go to the Project menu, right-click and select Properties

    Android Demo

  3. Under the Properties window, select the Java Build Path under the left menu and then select the Libraries tab on the top bar. Under this view, select the Add External JARs button on the right menu and navigate to the conversant-android-sdk-2.4.0.jar file located in the downloaded SDK folder.

    Android Demo

  4. Once the .jar file is added, select the Order and Export tab on the top bar and you will see the added conversant-android-sdk-2.4.0.jar file. Verify the box next to the newly added .jar file is checked and click OK.

    Android Demo

  5. Finally, incorporate the necessary calls to the Conversant SDK in your AndroidManifest.xml.

Activity and Permissions (Required)

Conversant's full screen interstitial ads and full screen click-through browser are displayed in their own Activity. To initialize this activity add the following lines to the <application> section of your manifest:

 <activity android:name="com.greystripe.sdk.GSFullscreenActivity" android:configChanges="keyboard|keyboardHidden|orientation|screenSize"></activity>

Add the following required permissions in the <manifest> section of AndroidManifest.xml.

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

Add the following optional permissions in the <manifest> section of AndroidManifest.xml. Optional permissions enable your application to receive a subset of rich media ads that take advantage of the calendar, contacts, and coupons (save image) functionality in Android.

 <uses-permission android:name="android.permission.WRITE_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Application ID (Optional)

Conversant provides a unique Application Identifier (called a “GUID”) which is used to identify your application and properly serve and credit ads to your account. GUIDs can be provided as part of the Ad constructor (more on that below). But, we also provide a convenience constructor, allowing you to skip passing in the ID at ad creation by specifying the App Id globally in the manifest. You can add this global GUID by declaring a metadata property in the <application> section of the manifest:

 <meta-data android:name="gs_guid" android:value="YOUR GUID GOES HERE"/>

Integrating Ads

Conversant's 2.x API uses an object-oriented paradigm. All ads are instances of objects, and are constructed and controlled by the host app. There is no ad manager object or other global SDK object which needs to be initialized at app start-up. All interaction occurs with GSAd subclasses and their listeners.

Initializing Ads

All ads, both full screen interstitials and in-content banners, inherit from the GSAd class and share a basic lifecycle. The first step is to create an instance of the GSAd subclass for the type of ad you want to show. For example, here is the constructor to initialize a full screen ad from your onCreate method:

 myFullscreenAd = new GSFullscreenAd(this, “232B-754E”);

This constructor takes two arguments. The first is the host application instance. The second is the App Id (or “GUID”) for the application in Conversant's system. (As noted above the GUID can also be specified globally in the AndroidManifest.xml.)

You should also add event listeners for each ad. GSAdListener defines an Interface for objects that want to be notified of GSAd events, such as download and clickthrough. We’ll get into the detail of these events below, but for now here is an example of adding the GSAdListener to our new GSFullscreenAd:

 MyFullscreenListener myFullscreenAdListener = new MyFullscreenListener();
myFullscreenAd.addListener(myFullscreenAdListener);

Fullscreen Interstitial Ads

Fetching Fullscreen Interstitial Ads

Once a fullscreen interstitial ad is initialized, you will need to request an ad from the Conversant server. In order to ensure a smooth end-user experience, Conversant ads must be fetched prior to display. To do this, you must call the ad object’s fetch method:

 myFullscreenAd.fetch();

This will request an ad from Conversant's server and result in an event, either success or failure, which will be sent to the GSAdListener.

Maximizing Fill Rate

Downloading a full screen rich media ad can take as long as 1 minute, depending on the connection speed and size of the ad. In order to maximize the likelihood of an ad being available when you want to display it, we recommend you initialize your ad objects and call the fetch() method of GSFullscreenAd as early in the application lifecycle as possible. This is particularly important if you plan to show full screen ads at or near the beginning of an application session.

Displaying Fullscreen Interstitial Ads

The last step is to display an ad. To determine if an ad is downloaded and ready to be displayed, you can listen for the onFetchedAd event, or call the isAdReady() method of GSAd for that ad instance. Once you have an ad downloaded and ready, just call the display() method of GSFullscreenAd:

 if (myFullscreenAd.isAdReady()) {
    myFullscreenAd.display();
}

Note that since full screen ad display occurs in a separate Activity, the launching Activity will receive normal Android Activity lifecycle notifications when our ad Activity begins and ends. You should follow standard Android programming conventions and pause all application activity including any audio or background computation while your Activity is suspended and a fullscreen ad, or clickthrough, is being displayed.

Banners Ads

Adding Banners Using the Layout.xml

In line banner ads can be integrated via the Android layout.xml system. To add a banner to your layout, simply include a banner element in the xml:

 <view class="com.greystripe.sdk.GSMobileBannerAdView"
    android:id="@+id/gsBanner
    android:layout_width="320dp"
    android:layout_height="50dp"
    gs:autoload="false"/>

In this element, we are creating a generic view with the appropriate size GSAd subclass as its “class” parameter value. We are also setting the optional “autoload” parameter to “false”. This means the banner will not fetch and display an ad when the banner instance is first drawn to the screen.

That means we need to explicitly request and display an ad in the Java code. To do that, you can access the GSBannerAdView instance using the usual findViewById() method:

 myBannerAd = (GSMobileBannerAdView) this.findViewById(R.id.gsBanner);

You can then call the Ad’s refresh() method to trigger a fetch and display:

 myBannerAd.refresh();

Refreshing Banners

The refresh() method attempts to fetch a banner ad and, if the view is on the screen, display the fetched ad. If you do not want the banner to display immediately on fetch, do not add the banner view instance to the view hierarchy. The ad will be fetched, but the cached ad will not display until you explicitly add it to the view hierarchy.

Adding Banners Programmatically

It is also possible to create a banner ad programmatically without using the layout.xml. The GSAdView classes all inherit from a standard Android view and can be created directly using a constructor like the Fullscreen ad:

 myBannerAd = new GSMobileBannerAdView(this);

Unlike Fullscreen ads, banners don’t have explicit fetch and display methods. The refresh method attempts to fetch an ad. If an ad is returned, and the GSAdView is currently on screen, the ad will immediately be displayed. If an ad is returned and the GSAdView is not in the view hierarchy, the ad will be locally cached until the ad is drawn to the screen (in which case the ad will then display and count an impression). For example, complete the setup of a banner ad:

 MyBannerAdListener myBannerAdListener = new MyBannerAdListener();
myBannerAd.addListener(myBannerAdListener);
myBannerAd.refresh();

Then, in your listener, add the banner view to the view hierarchy when the ad is fetched:

 public void onFetchedAd(GSAd ad) {
  myView = MyActivity.this.findViewById(R.id.myBannerViewContainer);
  myView.addView(myBannerAd);
}

In all cases, events are available so that the host app can listen for the result of their refresh attempt, and respond appropriately. For example, lets say you want to roll-over to another ad provider if Conversant doesn’t have a small banner available. You can simply create a GSMobileBannerAdView instance, register your listener and call refresh as shown above. Then, use the ad listener methods described below to either add the GSAdView to the hierarchy (in the case of a successful fetch) or roll-over to another provider (in the case of a failure).

AdListener Events

During the course of the ad lifecycle, there are a number of events which your app can respond to using GSAdListener.

 // Called when the ad fails to be fetched and cannot be displayed.
public void onFailedToFetchAd(GSAd ad, final GSAdErrorCode error);

// Called when the ad has loaded and can be displayed.
public void onFetchedAd(GSAd ad);

// Called when the user clicks on the ad.
public void onAdClickthrough(GSAd ad);

// Called when the user skips, closes, or otherwise dismisses an ad.
public void onAdDismissal(GSAd ad);

// Called when a banner ad is about to expand, taking over the whole screen.
public void onAdExpansion(GSAd ad);

// Called after an expanded/resized banner ad has collapsed
public void onAdCollapse(GSAd ad);

// Called after a banner ad has been resized.
public void onAdResize(GSAd ad, AdPosition newPosition);

320x50 Banner Example

private class MyBannerListener implements GSAdListener {
     @Override
     public void onFailedToFetchAd(GSAd ad, final GSAdErrorCode error) {
          String errorString = error.toString();
          Toast.makeText(MainActivity.this.getApplicationContext(),
               errorString, Toast.LENGTH_SHORT).show();
     }
   
     // other listeners
}

Fullscreen Interstitial Example

private class MyFullscreenListener implements GSAdListener {
     @Override
     public void onFailedToFetchAd(GSAd ad, final GSAdErrorCode error) {
          String errorString = error.toString();
          Toast.makeText(MainActivity.this.getApplicationContext(),
               errorString, Toast.LENGTH_SHORT).show();
     }
   
     // other listeners
}

Google Play Services Support

The Conversant 2.4 SDK supports the Google Play Services library and the Google Advertising ID. For more information about the Advertising ID, click here.

To install the Google Play Services SDK, follow the installation instructions here.

As referenced in the installation instructions above, the following will need to be added to the AndroidManifest.xml file:

<meta-data android:name="com.google.android.gms.version"
           android:value="@integer/google_play_services_version" />

ProGuard and Obfuscation

If you are obfuscating your code with ProGuard, please note that our Jar file is already obfuscated.

Add the following code to your ProGuard config to prevent our SDK from being obfuscated:

 -keep class com.greystripe.** { *; }

For more information about ProGuard, visit: http://developer.android.com/tools/help/proguard.html

Problems or Questions?

If you encounter any problems during integration please try the Testing process described on our Testing page. If your problem persists, please check the Troubleshooting page for information about common pitfalls and known issues.

If you have other questions or concerns please review our technical FAQ and our business information pages.