Getting Started - Ad Control Help Center

Overview

Use the Adrop Android SDK to display various ad formats in your app.

Supported Ad Formats

Format	Description
Banner	Rectangular ads displayed in a portion of the screen
Native	Customizable ads that match your app’s UI
Interstitial	Full-screen ads
Rewarded	Video ads that reward users upon completion
Popup	Ads displayed as popups at specific moments
Splash	Ads displayed with your logo at app launch

Requirements

Android 6.0 (API Level 23) or higher
Gradle 8.7 or higher
Kotlin 2.1.0 or higher
compileSdkVersion 34 or higher
Jetpack (AndroidX) support

Prerequisites

1. Add adrop_service.json File

Download File

Download the adrop_service.json file from Ad Control Console > Admin > App.

Add to Project

Place the downloaded file in the app/src/main/assets/ folder.

app/
└── src/
    └── main/
        └── assets/
            └── adrop_service.json

The SDK will not work properly without the adrop_service.json file.

2. Get Unit ID

Find the unit ID for your ad placement in the Ad Unit tab of the console.

Installation

Gradle Setup

Settings.gradle.kts

Add the repository to your project-level settings.gradle.kts file:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://artifact.bytedance.com/repository/pangle") }
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://artifact.bytedance.com/repository/pangle") }
    }
}

Build.gradle.kts

Add the dependency to your app-level build.gradle or build.gradle.kts file:

dependencies {
    implementation("io.adrop:adrop-ads:1.11.1")
    implementation("io.adrop:adrop-ads-backfill:1.11.2")
}

dependencies {
    implementation "io.adrop:adrop-ads:1.11.1"
    implementation "io.adrop:adrop-ads-backfill:1.11.2"
}

Check the latest version on Maven Central.

AndroidManifest.xml Setup

Add the App ID to your AndroidManifest.xml for backfill ads:

AndroidManifest.xml

<manifest>
    <application>
        <!-- Backfill App ID -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
    </application>
</manifest>

Please contact Adrop to get your App ID.

Initialization

Initialize the SDK in the onCreate() method of your Application class.

import android.app.Application
import io.adrop.ads.Adrop
import io.adrop.ads.model.AdropTheme

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize SDK
        Adrop.initialize(this, production = false, targetCountries = arrayOf())
        Adrop.setTheme(AdropTheme.AUTO)
    }
}

import android.app.Application;
import io.adrop.ads.Adrop;
import io.adrop.ads.model.AdropTheme;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Initialize SDK
        Adrop.INSTANCE.initialize(this, false, new String[]{});
        Adrop.INSTANCE.setTheme(AdropTheme.AUTO);
    }
}

Initialization Parameters

Parameter	Type	Default	Description
`context`	`Application`	-	App’s Application instance (required)
`production`	`Boolean`	`false`	Production mode. Set to `true` for release
`targetCountries`	`Array<String>`	`[]`	Target country codes (ISO 3166 alpha-2)
`tokenKey`	`String?`	`null`	App token key from `adrop_service.json` (optional)

If your adrop_service.json contains multiple app configurations, use tokenKey to specify which key to use for initialization.

Make sure to set production = true before release. Ads will not be displayed if set to false in production.

User Settings

Set UID

Set a user identifier for targeted advertising.

Adrop.setUID("user_123")

Adrop.INSTANCE.setUID("user_123");

Set the UID before entering the ad placement for targeted ads to work properly.

Set Theme

Set the theme for ads that support dark mode. Must be called after initialize().

// Light mode
Adrop.setTheme(AdropTheme.LIGHT)

// Dark mode
Adrop.setTheme(AdropTheme.DARK)

// Follow system setting (recommended)
Adrop.setTheme(AdropTheme.AUTO)

// Light mode
Adrop.INSTANCE.setTheme(AdropTheme.LIGHT);

// Dark mode
Adrop.INSTANCE.setTheme(AdropTheme.DARK);

// Follow system setting (recommended)
Adrop.INSTANCE.setTheme(AdropTheme.AUTO);

AUTO mode automatically detects the system dark mode setting. When the theme changes, the splash ad cache is automatically cleared.

Deep Link Handling

Handle deep links when the app is launched via an external link.

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.let { Adrop.handleDeepLink(it) }
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    if (intent != null) {
        Adrop.INSTANCE.handleDeepLink(intent);
    }
}

Test Unit IDs

Use test unit IDs during development. Replace with real unit IDs before production release.

Format	Test Unit ID
Banner (320x50)	`PUBLIC_TEST_UNIT_ID_320_50`
Banner (320x100)	`PUBLIC_TEST_UNIT_ID_320_100`
Carousel Banner	`PUBLIC_TEST_UNIT_ID_CAROUSEL`
Banner Video (16:9)	`PUBLIC_TEST_UNIT_ID_BANNER_VIDEO_16_9`
Banner Video (9:16)	`PUBLIC_TEST_UNIT_ID_BANNER_VIDEO_9_16`

Native Ads

Format	Test Unit ID
Native (Image)	`PUBLIC_TEST_UNIT_ID_NATIVE`
Native Video (16:9)	`PUBLIC_TEST_UNIT_ID_NATIVE_VIDEO_16_9`
Native Video (9:16)	`PUBLIC_TEST_UNIT_ID_NATIVE_VIDEO_9_16`

Interstitial/Rewarded Ads

Format	Test Unit ID
Interstitial	`PUBLIC_TEST_UNIT_ID_INTERSTITIAL`
Rewarded	`PUBLIC_TEST_UNIT_ID_REWARDED`

Format	Test Unit ID
Popup (Bottom)	`PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM`
Popup (Center)	`PUBLIC_TEST_UNIT_ID_POPUP_CENTER`
Popup Video Bottom (16:9)	`PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM_VIDEO_16_9`
Popup Video Bottom (9:16)	`PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM_VIDEO_9_16`
Popup Video Center (16:9)	`PUBLIC_TEST_UNIT_ID_POPUP_CENTER_VIDEO_16_9`
Popup Video Center (9:16)	`PUBLIC_TEST_UNIT_ID_POPUP_CENTER_VIDEO_9_16`

Splash Ads

Format	Test Unit ID
Splash	`PUBLIC_TEST_UNIT_ID_SPLASH`

Error Codes

Error codes returned when ad loading or display fails.

Error Code	Description
`ERROR_CODE_NETWORK`	Network error
`ERROR_CODE_INTERNAL`	Internal error
`ERROR_CODE_INITIALIZE`	SDK initialization error
`ERROR_CODE_INVALID_UNIT`	Invalid ad unit ID
`ERROR_CODE_NOT_TARGET_COUNTRY`	Not in target country
`ERROR_CODE_AD_INACTIVE`	Inactive ad
`ERROR_CODE_AD_NO_FILL`	No ad available to display
`ERROR_CODE_AD_LOAD_DUPLICATED`	Duplicate ad load request
`ERROR_CODE_AD_LOADING`	Ad is loading
`ERROR_CODE_AD_EMPTY`	Ad is empty
`ERROR_CODE_AD_SHOWN`	Ad has already been shown
`ERROR_CODE_AD_HIDE_FOR_TODAY`	”Don’t show today” is set
`ERROR_CODE_ACCOUNT_USAGE_LIMIT_EXCEEDED`	Account usage limit exceeded
`ERROR_CODE_LANDSCAPE_UNSUPPORTED`	Landscape mode not supported
`ERROR_CODE_AD_BACKFILL_NO_FILL`	No backfill ad available

For detailed descriptions, see the Reference.

Banner Ads

Implement banner ads

Native Ads

Implement native ads

Interstitial Ads

Implement interstitial ads

Rewarded Ads

Implement rewarded ads

Popup Ads

Implement popup ads

Splash Ads

Implement splash ads

WebView Guide

Display web ads in WebView

Targeting

User properties and context targeting

Reference

Classes, listeners, and error codes

Examples

Example repository

​Overview

​Supported Ad Formats

​Requirements

​Prerequisites

​1. Add adrop_service.json File

​2. Get Unit ID

​Installation

​Gradle Setup

​Settings.gradle.kts

​Build.gradle.kts

​AndroidManifest.xml Setup

​Initialization

​Initialization Parameters

​User Settings

​Set UID

​Set Theme

​Deep Link Handling

​Test Unit IDs

​Banner Ads

​Native Ads

​Interstitial/Rewarded Ads

​Popup Ads

​Splash Ads

​Error Codes

​Table of Contents

Banner Ads

Native Ads

Interstitial Ads

Rewarded Ads

Popup Ads

Splash Ads

WebView Guide

Targeting

Reference

Examples

Overview

Supported Ad Formats

Requirements

Prerequisites

1. Add adrop_service.json File

2. Get Unit ID

Installation

Gradle Setup

Settings.gradle.kts

Build.gradle.kts

AndroidManifest.xml Setup

Initialization

Initialization Parameters

User Settings

Set UID

Set Theme

Deep Link Handling

Test Unit IDs

Banner Ads

Native Ads

Interstitial/Rewarded Ads

Popup Ads

Splash Ads

Error Codes

Table of Contents