Get Started on Android

Before You Begin

Create and set up your Chartboost account.
Download and review the Chartboost Sample App

Amazon integration uses the same SDK as Android. These integration instructions apply to games for Google Play or the Amazon App Store.

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

Setting Up Chartboost SDK

Add the Chartboost repository and dependencies with the following code to your Gradle file.

repositories {
	mavenCentral()
	maven { url 'https://cboost.jfrog.io/artifactory/chartboost-ads/' }
}

dependencies {
	implementation 'com.chartboost:chartboost-sdk:9.4.1'
}

Add the Google Play Services Library as a dependency of your project. When you use our latest SDK, you will need “play-services-base” and “play-services-ads-identifier”.
- The Google Play Services library has its own set of integration instructions, including additions to your Android Manifest and ProGuard configuration.
- Follow Google’s instructions to integrate the Play Services Library.
- You should then 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 attribute to activities in the AndroidManifest.xml file if you display Chartboost ads with multiple orientations in those activities. This will help smoothen video playback during orientation changes.

android:configChanges="keyboardHidden|orientation|screenSize"

Import the Chartboost SDK into any activity that uses Chartboost with the following:

import com.chartboost.sdk.Chartboost;
import com.chartboost.sdk.ads.Interstitial;
import com.chartboost.sdk.ads.Rewarded;
import com.chartboost.sdk.ads.Banner;

import com.chartboost.sdk.Chartboost 
import com.chartboost.sdk.ads.Interstitial 
import com.chartboost.sdk.ads.Rewarded 
import com.chartboost.sdk.ads.Banner

If you’re using additional SDK features, you’ll also want to import these activities:

import com.chartboost.sdk.LoggingLevel;
import com.chartboost.sdk.Analytics;
import com.chartboost.sdk.events.CacheError;
import com.chartboost.sdk.events.CacheEvent;
import com.chartboost.sdk.events.ClickError;
import com.chartboost.sdk.events.ClickEvent;
import com.chartboost.sdk.events.DismissEvent;
import com.chartboost.sdk.events.ImpressionEvent;
import com.chartboost.sdk.events.ShowError;
import com.chartboost.sdk.events.ShowEvent;

import com.chartboost.sdk.LoggingLevel 
import com.chartboost.sdk.Analytics
import com.chartboost.sdk.events.CacheError 
import com.chartboost.sdk.events.CacheEvent 
import com.chartboost.sdk.events.ClickError 
import com.chartboost.sdk.events.ClickEvent 
import com.chartboost.sdk.events.DismissEvent 
import com.chartboost.sdk.events.ImpressionEvent 
import com.chartboost.sdk.events.ShowError 
import com.chartboost.sdk.events.ShowEvent

Initialize Chartboost SDK
- startWithAppId must always be called on bootup, regardless of any other actions your app takes.
- 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 by the Terms of Service to obtain 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.
- startWithAppId doesn’t require Activity anymore. From version 8.0.1+, the context should be passed instead.

Chartboost.startWithAppId(getApplicationContext(), appId, appSignature, startError -> {
	if (startError == null) {
		Toast.makeText(SelectionActivity.this, "SDK is initialized", Toast.LENGTH_SHORT).show();
    	checkKnownConsentStatus();
	} else {
		Toast.makeText(SelectionActivity.this, "SDK initialized with error: "+startError.getCode().name(), Toast.LENGTH_SHORT).show();
	}
});

Chartboost.startWithAppId(applicationContext, appId, appSignature) { startError ->
	if (startError == null) {
    	Toast.makeText([email protected], "SDK is initialized", Toast.LENGTH_SHORT).show()
    	checkKnownConsentStatus()
	} else {
    	Toast.makeText([email protected], "SDK initialized with error: ${startError.code.name()}", Toast.LENGTH_SHORT).show()
	}
}

Add your app ID and app signature
- Replace appID and appSignature with 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:

Create interstitial object without mediation object:

Interstitial chartboostInterstitial = new Interstitial("location", new InterstitialCallback() {
	@Override
	public void onAdDismiss(@NonNull DismissEvent dismissEvent) {

	}

	@Override
	public void onAdLoaded(@NonNull CacheEvent cacheEvent, @Nullable CacheError cacheError) {
    	// after this is successful ad can be shown
	}

	@Override
	public void onAdRequestedToShow(@NonNull ShowEvent showEvent) {

	}

	@Override
	public void onAdShown(@NonNull ShowEvent showEvent, @Nullable ShowError showError) {

	}

	@Override
	public void onAdClicked(@NonNull ClickEvent clickEvent, @Nullable ClickError clickError) {

	}

	@Override
	public void onImpressionRecorded(@NonNull ImpressionEvent impressionEvent) {

	}
}, null);

val chartboostInterstitial = Interstitial("location", object : InterstitialCallback {
    
	override fun onAdDismiss(dismissEvent: DismissEvent) {

	}

	override fun onAdLoaded(cacheEvent: CacheEvent, cacheError: CacheError) {
	  	// after this is successful ad can be shown
	}

	override fun onAdRequestedToShow(showEvent: ShowEvent) {

	}

	override fun onAdShown(showEvent: ShowEvent, showError: ShowError?) {

	}

	override fun onAdClicked(clickEvent: ClickEvent, clickError: ClickError?) {

	}

	override fun onImpressionRecorded(impressionEvent: ImpressionEvent) {

	}
}, null)

Create interstitial with mediation object:

Mediation mediation = new Mediation("Mediation", "1.0.0", "1.0.0.1");
chartboostInterstitial = new Interstitial("location", callback, mediation);

val mediation = Mediation("Mediation", "1.0.0", "1.0.0.1")
val chartboostInterstitial = Interstitial("location", callback, mediation)

Cache interstitial:

chartboostInterstitial.cache();

chartboostInterstitial.cache()

Show interstitial:

if (chartboostInterstitial.isCached()) {
	// check is cached is not mandatory
	chartboostInterstitial.show();
}

if (chartboostInterstitial.isCached()) {
	// check is cached is not mandatory
	chartboostInterstitial.show()
}

For customized control over how ads behave in your game, the Chartboost SDK offers delegate methods and named locations.

📘
Note

Do not call showInterstitial directly after cacheInterstitial for the same location, or the SDK will fail silently.

Prefetched videos (in total) only take up 30-50MB, even when you are using mediation.

To Show a Rewarded Video Ad

Create a rewarded object without Mediation object:

Rewarded chartboostRewarded = new Rewarded("location", new RewardedCallback() {
	@Override
	public void onRewardEarned(@NonNull RewardEvent rewardEvent) {

	}

	@Override
	public void onAdDismiss(@NonNull DismissEvent dismissEvent) {

	}

	@Override
	public void onAdLoaded(@NonNull CacheEvent cacheEvent, @Nullable CacheError cacheError) {
		// after this is successful ad can be shown
	}

	@Override
	public void onAdRequestedToShow(@NonNull ShowEvent showEvent) {

	}

	@Override
	public void onAdShown(@NonNull ShowEvent showEvent, @Nullable ShowError showError) {

	}

	@Override
	public void onAdClicked(@NonNull ClickEvent clickEvent, @Nullable ClickError clickError) {

	}

	@Override
	public void onImpressionRecorded(@NonNull ImpressionEvent impressionEvent) {

	}
}, null);

val chartboostRewarded = Rewarded("location", object : RewardedCallback {

	override fun onRewardEarned(rewardEvent: RewardEvent) {

	}
    
	override fun onAdDismiss(dismissEvent: DismissEvent) {

	}
    
	override fun onAdLoaded(cacheEvent: CacheEvent, cacheError: CacheError?) {
		// after this is successful ad can be shown
	}
    
	override fun onAdRequestedToShow(showEvent: ShowEvent) {

	}
    
	override fun onAdShown(showEvent: ShowEvent, showError: ShowError?) {

	}
    
	override fun onAdClicked(clickEvent: ClickEvent, clickError: ClickError?) {

	}

	override fun onImpressionRecorded(impressionEvent: ImpressionEvent) {

	}
}, null)

Create a rewarded object with Mediation object:

Mediation mediation = new Mediation("Mediation", "1.0.0", "1.0.0.1");
chartboostRewarded = new Rewarded("start", callback, mediation);

val mediation = Mediation("Mediation", "1.0.0", "1.0.0.1")
val chartboostRewarded = Rewarded("start", callback, mediation)

Cache rewarded:

chartboostRewarded.cache();

chartboostRewarded.cache()

We strongly recommend that you cache your interstitials before showing them.
Prefetched videos (in total) only take up 30-50MB, even when you are using mediation.

Show rewarded:

chartboostRewarded.show();

chartboostRewarded.show()

For customized control over how ads behave in your game, the Chartboost SDK offers delegate methods and named locations.

To Show a Banner Ad:

Create a banner object without Mediation object:

Banner chartboostBanner = new Banner(context, "location", Banner.BannerSize.STANDARD, new BannerCallback() {
	@Override
	public void onAdLoaded(@NonNull CacheEvent cacheEvent, @Nullable CacheError cacheError) {

	}

	@Override
	public void onAdRequestedToShow(@NonNull ShowEvent showEvent) {

	}

	@Override
	public void onAdShown(@NonNull ShowEvent showEvent, @Nullable ShowError showError) {

	}

	@Override
	public void onAdClicked(@NonNull ClickEvent clickEvent, @Nullable ClickError clickError) {

	}

	@Override
	public void onImpressionRecorded(@NonNull ImpressionEvent impressionEvent) {

	}
}, null);

val chartboostBanner = Banner(context, "location", Banner.BannerSize.STANDARD, object : BannerCallback {
    
	override fun onAdLoaded(cacheEvent: CacheEvent, cacheError: CacheError?) {

	}

	override fun onAdRequestedToShow(showEvent: ShowEvent) {

	}
    
	override fun onAdShown(showEvent: ShowEvent, showError: ShowError?) {

	}
    
	override fun onAdClicked(clickEvent: ClickEvent, clickError: ClickError?) {

	}
    
	override fun onImpressionRecorded(impressionEvent: ImpressionEvent) {

	}
}, null)

Create a banner object with mediation:

Mediation mediation = new Mediation("Mediation", "1.0.0", "1.0.0.1");
chartboostBanner = new Banner(context, "location", Banner.BannerSize.STANDARD, callback, mediation);

val mediation = Mediation("Mediation", "1.0.0", "1.0.0.1")
val chartboostBanner = Banner(context, "location", Banner.BannerSize.STANDARD, callback, mediation)

Attach the banner to a holder. The banner object is extending FrameLayout and needs to be attached to the view to be displayed on the screen.

RelativeLayout bannerHolder = findViewById(R.id.example_banner_holder);
bannerHolder.addView(chartboostBanner);

val bannerHolder = findViewById<RelativeLayout>(R.id.example_banner_holder).apply {
	addView(chartboostBanner)
}

CacheBanner:

chartboostBanner.cache();

chartboostBanner.cache()

Show banner:

public void onAdLoaded(CacheEvent cacheEvent, @Nullable CacheError cacheError) {
	if (cacheError != null) {
		/* Handle error */
	} else {
		chartboostBanner.show();
	}
}

override fun onAdLoaded(cacheEvent: CacheEvent, cacheError: CacheError?) {
	if (cacheError != null) {
		/* Handle error */
	} else {
		chartboostBanner.show()
	}
}

Remove banner:

chartboostBanner.detach();

chartboostBanner.detach()

Public Banner Errors:

CacheError cacheError = new CacheError(CacheError.Code.INTERNAL, new Exception("banner cache error"));
cacheError.getCode();

ShowError showError = new ShowError(ShowError.Code.INTERNAL, new Exception("banner show error"));
showError.getCode();

ClickError clickError = new ClickError(ClickError.Code.INTERNAL, new Exception("banner click error"));
clickError.getCode();

val cacheError = CacheError(CacheError.Code.INTERNAL, Exception("banner cache error"))
cacheError.code

val showError = ShowError(ShowError.Code.INTERNAL, Exception("banner show error"))
showError.code

val clickError = ClickError(ClickError.Code.INTERNAL, Exception("banner click error"))
clickError.code

📘
Note
Banner ads are not supported for Amazon integrations.

Testing Your SDK Integration

Run your project on an Android device.
Use Test Mode to see if test ads show up.

SDK Configuration Methods

These methods allow you to access Chartboost SDK functionality and settings.

/**
* Set the Chartboost SDK logging level.
* @param level The logging level.
* @return true if was set successfully, false otherwise
*/
fun setLoggingLevel(level: LoggingLevel)