# Get Started on Android ## Before You Begin 1. [Create and set up your Chartboost account](/en/monetization/get-started/) 2. Download and review the [Chartboost Sample App](https://github.com/ChartBoost/android-sdk-sample-java) Amazon integration uses the same SDK as Android. These integration instructions apply to games for Google Play or the Amazon App Store. ## Minimum Supported Development Tools | Software | Version | | -------- | ------- | | Minimum Supported Version | API 19 (Android 4.4 KitKat) | | Compile Version | API 35 | | Gradle | 8.2 | | Kotlin | 1.9.21 | | Recommended Java | 17 | ### Runtime Permissions Refer to the [Android Developers documentation](https://developer.android.com/training/permissions/declaring){:target="_blank"} for details on how to declare and handle both normal and runtime permissions. Required normal permissions: - `android.permission.INTERNET` - `android.permission.ACCESS_NETWORK_STATE` Recommended optional runtime permissions (allows the SDK to handle calls that interrupt video playback): - `android.permission.READ_PHONE_STATE` ## Setting Up Chartboost SDK #### 1. Add the Chartboost repository and dependencies with the following code to your Gradle file. ```java repositories { mavenCentral() maven { url 'https://cboost.jfrog.io/artifactory/chartboost-ads/' } } dependencies { implementation 'com.chartboost:chartboost-sdk:9.13.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 [Google’s instructions to integrate the Play Services Library](https://developers.google.com/android/guides/setup). - You should then find something similar to the following two lines in your `build.gradle` file: ```java implementation "com.google.android.gms:play-services-base:$project.ext.googlePlayServicesVersion" implementation "com.google.android.gms:play-services-ads-identifier:$project.ext.googlePlayServicesVersion" ``` #### 3. 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. ```java android:configChanges="keyboardHidden|orientation|screenSize" ``` #### 4. 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:

Kotlin
Java

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.ExpirationEvent
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.ExpirationEvent;
import com.chartboost.sdk.events.ImpressionEvent;
import com.chartboost.sdk.events.ShowError;
import com.chartboost.sdk.events.ShowEvent;

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

Note: Some Android API 21-24 (5.0-7.0) devices cannot initialize with Chartboost Monetization SDK due to their incompatibility with newer TLS versions and/or certificates.

Kotlin
Java

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

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();
	}
});

#### 6. 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 Banner Ad Create a banner object without Mediation object:

Kotlin
Java

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) {

	}

	// Optional: called when a cached ad expires or is evicted
	override fun onAdExpired(expirationEvent: ExpirationEvent) {

	}
}, null)

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) {

	}

	// Optional: called when a cached ad expires or is evicted
	@Override
	public void onAdExpired(@NonNull ExpirationEvent expirationEvent) {

	}
}, null);

Create a banner object with mediation:

Kotlin
Java

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

Mediation mediation = new Mediation("Mediation", "1.0.0", "1.0.0.1");
chartboostBanner = new 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.

Kotlin
Java

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

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

CacheBanner:

Kotlin
Java

```
chartboostBanner.cache()
```
```
chartboostBanner.cache();
```

Show banner:

Kotlin
Java

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

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

Remove banner:

Kotlin
Java

```
chartboostBanner.detach()
```
```
chartboostBanner.detach();
```

Public Banner Errors:

Kotlin
Java

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

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

## To Show a Static or Video Interstitial Ad Create interstitial object without mediation object:

Kotlin
Java

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

	}

	override fun onAdLoaded(event: CacheEvent, error: 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) {

	}

	// Optional: called when a cached ad expires or is evicted
	override fun onAdExpired(expirationEvent: ExpirationEvent) {

	}
}, null)

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) {

	}

	// Optional: called when a cached ad expires or is evicted
	@Override
	public void onAdExpired(@NonNull ExpirationEvent expirationEvent) {

	}
}, null);

Create interstitial with mediation object:

Kotlin
Java

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

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

Cache interstitial:

Kotlin
Java

```
chartboostInterstitial.cache()
```
```
chartboostInterstitial.cache();
```

Show interstitial:

Kotlin
Java

```
	chartboostInterstitial.show()
```
```
	chartboostInterstitial.show();
```

Note:

Do not call show() directly after cache() for the same interstitial object, or the ad may not be ready to display.

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:

Kotlin
Java

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) {

	}

	// Optional: called when a cached ad expires or is evicted
	override fun onAdExpired(expirationEvent: ExpirationEvent) {

	}
}, null)

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) {

	}

	// Optional: called when a cached ad expires or is evicted
	@Override
	public void onAdExpired(@NonNull ExpirationEvent expirationEvent) {

	}
}, null);

Create a rewarded object with Mediation object:

Kotlin
Java

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

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

Cache rewarded:

Kotlin
Java

```
chartboostRewarded.cache()
```
```
chartboostRewarded.cache();
```

Show rewarded:

Kotlin
Java

```
chartboostRewarded.show()
```
```
chartboostRewarded.show();
```

- For customized control over how ads behave in your game, the Chartboost SDK offers [delegate methods](/en/monetization/integrate/android/delegate-methods/) and [named locations](/en/monetization/integrate/android/named-locations/). ## ExoPlayer Dependency for Video Ads Chartboost SDK utilizes both ExoPlayer v2.18.7 (`com.google.android.exoplayer:exoplayer-core`) and AndroidX Media3 ExoPlayer v1.4.1 (`androidx.media3:media3-exoplayer`). If you have a dependency on ExoPlayer, you may get an error similar to the following: ``` > A failure occurred while executing com.android.build.gradle.internal.tasks.CheckDuplicatesRunnable > Duplicate class com.google.android.exoplayer2.ui.DownloadNotificationHelper found in modules exoplayer-core-2.18.7-runtime (com.google.android.exoplayer:exoplayer-core:2.18.7) and exoplayer-ui-2.15.1-runtime (com.google.android.exoplayer:exoplayer-ui:2.15.1) ``` To resolve this, exclude the ExoPlayer dependency from Chartboost SDK in Gradle: ```kotlin dependencies { implementation('com.chartboost:chartboost-sdk:9.13.0') { exclude group: 'com.google.android.exoplayer' } } ``` ## Testing Your SDK Integration 1. Run your project on an Android device. 2. Use [Test Mode](/en/monetization/charles-web-proxy/) to see if test ads show up. ## SDK Configuration Methods These methods allow you to access Chartboost SDK functionality and settings.

Kotlin

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