Android & Amazon SDK

Before you begin:
  • Have you signed up for a Chartboost account?
  • Did you add an app to your dashboard?
  • If you are integrating an older SDK version (up to 7.5.0)  follow this integration page instead.
  • Amazon integration uses the same SDK as Android. These integration instructions apply to games for Google Play or the Amazon App Store.
  • Chartboost Sample App is available here.
  • If your game is built in Unity, we strongly recommend using our Unity plugin for Android. If you prefer to use the Android SDK with your own Unity adapter, use this method to make sure ads show up within your game.
Publishers should call the addDataUseConsent API from the Chartboost SDK and pass in the appropriate value for whether consent exists, does not exist, or is unknown. Publishers are required as part of Terms of Service to obtain the consent from their users before Chartboost will process any personal data and pass it to the Chartboost SDK via the above method. This method should be called before startWithAppId.
Learn more about privacy methods here.

Requirements and Optional Permissions
  • The Chartboost SDK requires API level 21 (Android OS 5) or higher.
  • The Chartboost Android SDK requires the use of AndroidX.
  • Required permission: android.permission.INTERNET
  • Required permission: android.permission.ACCESS_NETWORK_STATE
  • Optional (but recommended) permission: android.permission.READ_PHONE_STATE Allows the SDK to handle calls that interrupt video playback.

Add Chartboost repository and dependencies to your Gradle file.
  • To integrate Chartboost, add this code to your Android Gradle file:
repositories {
      maven { url "https://chartboostmobile.bintray.com/Chartboost" }
}
dependencies {
       implementation 'com.chartboost:chartboost-sdk:8.2.0'
}

Add the Google Play Services Library as a dependency of your project. If you are using Chartboost SDK 7.2.1 or higher, you will need “play-services-base” and “play-services-ads-identifier”, while older SDK releases need “play-services-ads”
  • The Google Play Services library has its own set of integration instructions, including additions to your Android Manifest and ProGuard configuration.
  • Follow these setup instructions from Google.
  • After following Google’s instructions to integrate the Play Services Library you should find something similar to the following two lines in your build.gradle file:
implementation "com.google.android.gms:play-services-base:$project.ext.googlePlayServicesVersion"
implementation "com.google.android.gms:play-services-ads-identifier:$project.ext.googlePlayServicesVersion"

Add the following entry in your AndroidManifest.xml file.

 
<activity android:name="com.chartboost.sdk.CBImpressionActivity"
               android:excludeFromRecents="true"
               android:hardwareAccelerated="true"
               android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"
               android:configChanges="keyboardHidden|orientation|screenSize" />
For complex integrations that don’t include CBImpressionActivity, any activities that show Chartboost ads must have the value android:hardwareAccelerated="true" in their activity entry on the Android Manifest, or video might not display properly.

If you display Chartboost ads in any activity that supports different orientations, add the following attribute to those activities in AndroidManifest.xml.

 
android:configChanges="keyboardHidden|orientation|screenSize"
This helps smoothen video playback during orientation changes.

Import the Chartboost SDK into any activity that uses Chartboost.

 
import com.chartboost.sdk.Chartboost;
import com.chartboost.sdk.CBLocation;
import com.chartboost.sdk.ChartboostDelegate;
import com.chartboost.sdk.Libraries.CBLogging.Level;
import com.chartboost.sdk.Model.CBError.CBClickError;
import com.chartboost.sdk.Model.CBError.CBImpressionError;
import com.chartboost.sdk.Tracking.CBAnalytics;
import com.chartboost.sdk.CBImpressionActivity;

Initialize Chartboost SDK
  • startWithAppId doesn’t require Activity anymore. From version 8.0.1+ context should be passed instead.
public static void startWithAppId(Context context, ​String appId, String appSignature)
PRO TIP: Watch for an Exception: Initialization error message. This indicates that the SDK was not initialized properly.
PRO TIP: If you’re using the Android SDK with your own Unity adapter, you must report Unity as the framework immediately after startWithAppId using the method Chartboost.setFramework(CBFramework.CBFrameworkUnity, unityVersion);. Replace unityVersion with the value returned by this Unity function.
startWithAppId must always be called during hard and soft bootups within the first few seconds of your app launching, regardless of any other actions or user interaction within your app.
Publishers should call the addDataUseConsent API from the Chartboost SDK and pass in the appropriate value for whether consent exists, does not exist, or is unknown. Publishers are required as part of Terms of Service to obtain the consent from their users before Chartboost will process any personal data and pass it to the Chartboost SDK via the above method. This method should be called before startWithAppId.

Add your app ID and app signature.
Chartboost App ID is a unique App identifier in our systems, therefore it is required to use a different Chartboost App ID per each app.

To show a static or video interstitial ad:

 
Chartboost.cacheInterstitial(CBLocation.LOCATION_DEFAULT);
Chartboost.showInterstitial(CBLocation.LOCATION_DEFAULT);
  • You can use the CBLocation interface class to get a list of default location constants as well as define your own.  Once a location is used, it will be added to your dashboard, where you can customize its settings.
  • For customized control over how ads behave in your game, the Chartboost SDK also offers more features such as caching, delegate methods, and named locations.
  • Learn more about Chartboost video ads ▶
Do not call showInterstitial directly after cacheInterstitial for the same location, or the SDK will fail silently.
We strongly recommend that you cache your interstitials before showing them. Learn more about caching ▶
Prefetched videos (in total) only take up 30-50MB, even when you are using mediation.

To show a rewarded video ad:

 
Chartboost.cacheRewardedVideo(CBLocation.LOCATION_GAMEOVER);
Chartboost.showRewardedVideo(CBLocation.LOCATION_GAMEOVER);
We strongly recommend that you cache your interstitials before showing them. Learn more about caching ▶
Prefetched videos (in total) only take up 30-50MB, even when you are using mediation.

To show a banner ad:

 
chartboostBanner.cache()
chartboostBanner.show()
Banner ads are not supported for Amazon integrations.
To make the banner ad show, first create it (detailed here), and then call the delegate method.
By default, a banner will automatically update its content on its own. The refresh default rate is 30s.
Banners by auto-cache after shown if setAutomaticallyRefreshesContent is set to true. Otherwise, you can change the value of setAutomaticallyRefreshesContent to false to not automatically cache banner ads.

If you’re using ProGuard, add the following to your proguard-rules.pro:

 
-keep class com.chartboost.** { *; }
PRO TIP: Follow Google Play Services instructions for proper ProGuard setup.

Test your integration.

Check the SDK icon in the Chartboost dashboard.
  • Go to your app’s App Settings > Basic Settings in your dashboard.
  • When our servers successfully receive a bootup call from our SDK using your app ID, the SDK icon underneath your app’s icon will turn from gray to green.

w00t! You just integrated the Chartboost SDK into your app!

Now you can start a campaign ▶

Check out more Chartboost SDK features

  • Caching: Speed up load times for ads by storing them locally on devices.
  • Chartboost Video: Add beautiful, high-quality video ads to give players the best in-game experience.
  • Named locations: Fine-tune your campaign targeting and ad frequency from the dashboard.
  • Delegate methods: Gain more control over how your game behaves around ads.
  • SDK configuration methods: Access Chartboost SDK functionality and settings.
  • Mediation: Show your ads along a waterfall of other top-quality networks.

Override your activity’s lifecycle methods.

  • Add the following code to extend your activity’s onBackPressed() methods:
@Override
public void onBackPressed() {
    // If an interstitial is on screen, close it.
    if (Chartboost.onBackPressed())
        return;
    else
        super.onBackPressed();
}
You might also like…
  • Error codes: Common problems and their solutions when integrating the SDK for Android.

▲ Back to top


Last Updated on December 1, 2020