> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Learn how to integrate the Adrop SDK into your Android project.

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

<Steps>
  <Step title="Download File">
    Download the `adrop_service.json` file from [Ad Control Console](https://console.adrop.io) > **Admin** > **App**.
  </Step>

  <Step title="Add to Project">
    Place the downloaded file in the `app/src/main/assets/` folder.
  </Step>
</Steps>

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

<Warning>
  The SDK will not work properly without the `adrop_service.json` file.
</Warning>

### 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:

<CodeGroup>
  ```kotlin settings.gradle.kts theme={null}
  dependencyResolutionManagement {
      repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
      repositories {
          google()
          mavenCentral()
          maven { url = uri("https://artifact.bytedance.com/repository/pangle") }
      }
  }
  ```

  ```groovy settings.gradle theme={null}
  dependencyResolutionManagement {
      repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
      repositories {
          google()
          mavenCentral()
          maven { url = uri("https://artifact.bytedance.com/repository/pangle") }
      }
  }
  ```
</CodeGroup>

#### Build.gradle.kts

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

<CodeGroup>
  ```kotlin build.gradle.kts theme={null}
  dependencies {
      implementation("io.adrop:adrop-ads:1.11.1")
      implementation("io.adrop:adrop-ads-backfill:1.11.2")
  }
  ```

  ```groovy build.gradle theme={null}
  dependencies {
      implementation "io.adrop:adrop-ads:1.11.1"
      implementation "io.adrop:adrop-ads-backfill:1.11.2"
  }
  ```
</CodeGroup>

<Note>
  Check the latest version on [Maven Central](https://central.sonatype.com/artifact/io.adrop/adrop-ads).
</Note>

### AndroidManifest.xml Setup

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

```xml AndroidManifest.xml theme={null}
<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>
```

<Note>
  Please contact Adrop to get your App ID.
</Note>

***

## Initialization

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

<CodeGroup>
  ```kotlin Kotlin theme={null}
  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)
      }
  }
  ```

  ```java Java theme={null}
  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);
      }
  }
  ```
</CodeGroup>

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

<Tip>
  If your `adrop_service.json` contains multiple app configurations, use `tokenKey` to specify which key to use for initialization.
</Tip>

<Warning>
  Make sure to set `production = true` before release. Ads will not be displayed if set to `false` in production.
</Warning>

***

## User Settings

### Set UID

Set a user identifier for targeted advertising.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  Adrop.setUID("user_123")
  ```

  ```java Java theme={null}
  Adrop.INSTANCE.setUID("user_123");
  ```
</CodeGroup>

<Note>
  Set the UID before entering the ad placement for targeted ads to work properly.
</Note>

### Set Theme

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

<CodeGroup>
  ```kotlin Kotlin theme={null}
  // Light mode
  Adrop.setTheme(AdropTheme.LIGHT)

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

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

  ```java Java theme={null}
  // Light mode
  Adrop.INSTANCE.setTheme(AdropTheme.LIGHT);

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

  // Follow system setting (recommended)
  Adrop.INSTANCE.setTheme(AdropTheme.AUTO);
  ```
</CodeGroup>

<Note>
  `AUTO` mode automatically detects the system dark mode setting. When the theme changes, the splash ad cache is automatically cleared.
</Note>

***

## Deep Link Handling

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

<CodeGroup>
  ```kotlin Kotlin theme={null}
  override fun onNewIntent(intent: Intent?) {
      super.onNewIntent(intent)
      intent?.let { Adrop.handleDeepLink(it) }
  }
  ```

  ```java Java theme={null}
  @Override
  protected void onNewIntent(Intent intent) {
      super.onNewIntent(intent);
      if (intent != null) {
          Adrop.INSTANCE.handleDeepLink(intent);
      }
  }
  ```
</CodeGroup>

***

## Test Unit IDs

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

### Banner Ads

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

### Popup Ads

| 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](/sdk/android/reference#adroperrorcode).

***

## Table of Contents

<CardGroup cols={2}>
  <Card title="Banner Ads" href="/sdk/android/banner">
    Implement banner ads
  </Card>

  <Card title="Native Ads" href="/sdk/android/native">
    Implement native ads
  </Card>

  <Card title="Interstitial Ads" href="/sdk/android/interstitial">
    Implement interstitial ads
  </Card>

  <Card title="Rewarded Ads" href="/sdk/android/rewarded">
    Implement rewarded ads
  </Card>

  <Card title="Popup Ads" href="/sdk/android/popup">
    Implement popup ads
  </Card>

  <Card title="Splash Ads" href="/sdk/android/splash">
    Implement splash ads
  </Card>

  <Card title="WebView Guide" href="/sdk/android/webview">
    Display web ads in WebView
  </Card>

  <Card title="Targeting" href="/sdk/android/targeting">
    User properties and context targeting
  </Card>

  <Card title="Reference" href="/sdk/android/reference">
    Classes, listeners, and error codes
  </Card>

  <Card title="Examples" href="/sdk/android/examples">
    Example repository
  </Card>
</CardGroup>