Before you begin:

    • Have you signed up for a Chartboost account?
    • Did you add an app to your dashboard?
    • Did you download the latest SDK?
    • Amazon integration uses the same SDK as Android. These integration instructions apply to games for Google Play or the Amazon App Store.
    • 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.
  • The Chartboost SDK requires API level 9 (Android OS 2.3) or higher.
  • Required permission: android.permission.INTERNET
  • Required permission: android.permission.ACCESS_NETWORK_STATE
  • Highly recommended: To ensure compatibility with Android 6.0 devices, set the project’s Build and Compile SDK Version to API Level 23 in your build.gradle file:
    buildToolsVersion = '23.0.0' compileSdkVersion = 23
  • Highly recommended: To target Android 6.0 Marshmallow features, set the project’s Target SDK Version to API Level 23 in your AndroidManfiest.xml:
  • Optional (but recommended) permission: android.permission.WRITE_EXTERNAL_STORAGE Allows the SDK to cache all ad assets (creatives, custom frames, etc.) in external memory. This maximizes performance by immediately delivering ads and reducing network traffic used by the SDK.
  • Optional (but recommended) permission: android.permission.ACCESS_WIFI_STATE Allows the SDK to check WiFi details in the HTTP request. This will be used alongside Android ID and/or GAID as the identifier for the user. Check out device identifiers for more info.
  • Optional (but recommended) permission: android.permission.READ_PHONE_STATE Allows the SDK to handle calls that interrupt video playback.

Add the chartboost.jar file to your libs directory.

  • If you don’t have a libs folder, create one and add the .jar file to it.
  • Optional: Add and the doc directory to libs to get Javadocs in your IDE.

Add the following entry in your AndroidManifest.xml file.

<activity android:name="com.chartboost.sdk.CBImpressionActivity"
               android:configChanges="keyboardHidden|orientation|screenSize" />
  • This helps smoothen ad transitions and video playback.

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

  • 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 the Chartboost SDK in your launcher activity class.

  • Extend your main activity’s onCreate lifecycle method like this:
public class <your Class name> extends Activity {

public void onCreate() {
    Chartboost.startWithAppId(this, appId, appSignature);
  • Alternatively, you can let the SDK handle this for you by simply extending ChartboostActivity. This prevents the need to override activity lifecycle methods like onCreate so you can simply call Chartboost.OnCreate().
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.

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.

Override your activity’s lifecycle methods.

  • Add the following code to extend your activity’s onStart(), onPause(), onResume(), onStop(), onDestroy(), and onBackPressed() methods:
public void onStart() {

public void onResume() {

public void onPause() {

public void onStop() {

public void onDestroy() {

public void onBackPressed() {
    // If an interstitial is on screen, close it.
    if (Chartboost.onBackPressed())

To show a static or video interstitial ad:

  • 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.
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:

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.

If you’re using ProGuard, add the following to your

-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.

Using OpenGL and older versions of the Chartboost SDK

<activity android:name="com.chartboost.sdk.CBImpressionActivity"
               android:configChanges="keyboardHidden|orientation|screenSize" />
  • For Chartboost SDK v3.4.0 or lower: cb.setImpressionsUseActivities(true);
  • For Chartboost SDK v4.x: CBPreferences.getInstance().setImpressionsUseActivities(true);
  • For Chartboost SDK v5.x: Chartboost.setImpressionsUseActivities(boolean impressionsUseActivities) Call this method in your activity’s onCreate() method after you initialize the SDK with startWithAppId but before calling Chartboost.onCreate()

You might also like…
  • Error codes: Common problems and their solutions when integrating the SDK for Android.

▲ Back to top