Before You Begin

  • Have you signed up for a Chartboost account?
  • Did you add an app to your dashboard?
  • 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.

📘

Note

  • 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 and Behavioral Targeting 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

1. Add Chartboost repository and dependencies to your Gradle file.

  • To integrate Chartboost, add this code to your Android Gradle file:
repositories {
mavenCentral()
}
dependencies {
implementation 'com.chartboost:chartboost-sdk:9.1.0'}

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

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

🚧

Caution

This helps smoothen video playback during orientation changes.

4. Import the Chartboost SDK into any activity that uses Chartboost

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

5. Initialize Chartboost SDK

startWithAppId doesn’t require Activity anymore. From version 8.0.1+ context should be passed instead.

Chartboost.startWithAppId(getApplicationContext(), appId, appSignature, startError {
if (startError == null) {
// handle success
} else {
// handle error
}
});

📘

Note

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

6. Add your app ID and app signature

📘

Note

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.

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

Create interstitial with mediation object:

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

Cache interstitial:

chartboostInterstitial.cache();

Show interstitial:

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

📘

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.

8. To show a rewarded video ad:

Create 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);

Create rewarded with mediation object:

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

Cache rewarded:

chartboostRewarded.cache()

Show rewarded:

chartboostRewarded.show()

📘

Note

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

9. To show a banner ad:

Create 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);

Create 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);

Attach banner to the holder. Banner object is extending FrameLayout and needs to be attached to the view to be displayed at the screen.

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

CacheBanner

chartboostBanner.cache();

Show banner:

chartboostBanner.show();

If you wish to remove the banner from view, use:

chartboostBanner.detach();
  • 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.

10. Test your integration

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