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

# はじめに

> AndroidプロジェクトにAdrop SDKを連携する方法をご案内します。

## 概要

Adrop Android SDKを使用して、さまざまな広告フォーマットをアプリに表示できます。

### 対応広告フォーマット

| フォーマット         | 説明                     |
| -------------- | ---------------------- |
| **バナー**        | 画面の一部に表示される矩形広告        |
| **ネイティブ**      | アプリのUIに合わせてカスタマイズ可能な広告 |
| **インタースティシャル** | 画面全体を覆うフルスクリーン広告       |
| **リワード**       | 視聴完了時にリワードを提供する動画広告    |
| **ポップアップ**     | 特定のタイミングでポップアップ表示される広告 |
| **スプラッシュ**     | アプリ起動時にロゴと一緒に表示される広告   |

### 要件

* Android 6.0（API Level 23）以上
* Gradle 8.7以上
* Kotlin 2.1.0以上
* compileSdkVersion 34以上
* Jetpack（AndroidX）対応

***

## 事前準備

### 1. adrop\_service.jsonファイルの追加

<Steps>
  <Step title="ファイルをダウンロード">
    [Ad Controlコンソール](https://console.adrop.io) > **Admin** > **App** から`adrop_service.json`ファイルをダウンロードします。
  </Step>

  <Step title="プロジェクトに追加">
    ダウンロードしたファイルを`app/src/main/assets/`フォルダに追加します。
  </Step>
</Steps>

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

<Warning>
  `adrop_service.json`ファイルがないとSDKは正常に動作しません。
</Warning>

### 2. ユニットIDの確認

コンソールの**Ad Unit**タブで、広告枠に該当するユニットIDを確認します。

***

## インストール

### Gradle設定

#### Settings.gradle.kts

プロジェクトレベルの`settings.gradle.kts`ファイルにリポジトリを追加します：

<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

アプリレベルの`build.gradle`または`build.gradle.kts`ファイルに依存関係を追加します：

<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>
  最新バージョンは[Maven Central](https://central.sonatype.com/artifact/io.adrop/adrop-ads)でご確認ください。
</Note>

### AndroidManifest.xml設定

バックフィル広告のために`AndroidManifest.xml`にApp IDを追加します：

```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>
  App IDの発行についてはAdropにお問い合わせください。
</Note>

***

## 初期化

`Application`クラスの`onCreate()`でSDKを初期化します。

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

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

          // SDK初期化
          Adrop.INSTANCE.initialize(this, false, new String[]{});
          Adrop.INSTANCE.setTheme(AdropTheme.AUTO);
      }
  }
  ```
</CodeGroup>

### 初期化パラメータ

| パラメータ             | タイプ             | デフォルト   | 説明                                 |
| ----------------- | --------------- | ------- | ---------------------------------- |
| `context`         | `Application`   | -       | アプリのApplicationインスタンス（必須）          |
| `production`      | `Boolean`       | `false` | プロダクションモード。リリース時は`true`に設定         |
| `targetCountries` | `Array<String>` | `[]`    | ターゲット国コード（ISO 3166 alpha-2）        |
| `tokenKey`        | `String?`       | `null`  | `adrop_service.json`のアプリトークンキー（任意） |

<Tip>
  `adrop_service.json`に複数のアプリ設定が含まれている場合、`tokenKey`を使用して初期化に使用するキーを指定します。
</Tip>

<Warning>
  リリース前に必ず`production = true`に設定してください。`false`のままリリースすると広告が表示されません。
</Warning>

***

## ユーザー設定

### UID設定

ターゲティング広告のためにユーザー識別子を設定します。

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

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

<Note>
  ターゲティング広告が正常に動作するには、広告をロードする前にUIDを設定してください。
</Note>

### テーマ設定

ダークモード対応広告のためにテーマを設定します。`initialize()`呼び出し後に設定する必要があります。

<CodeGroup>
  ```kotlin Kotlin theme={null}
  // ライトモード
  Adrop.setTheme(AdropTheme.LIGHT)

  // ダークモード
  Adrop.setTheme(AdropTheme.DARK)

  // システム設定に従う（推奨）
  Adrop.setTheme(AdropTheme.AUTO)
  ```

  ```java Java theme={null}
  // ライトモード
  Adrop.INSTANCE.setTheme(AdropTheme.LIGHT);

  // ダークモード
  Adrop.INSTANCE.setTheme(AdropTheme.DARK);

  // システム設定に従う（推奨）
  Adrop.INSTANCE.setTheme(AdropTheme.AUTO);
  ```
</CodeGroup>

<Note>
  `AUTO`モードはシステムのダークモード設定を自動的に検出します。テーマが変更されると、スプラッシュ広告のキャッシュは自動的にクリアされます。
</Note>

***

## ディープリンク処理

外部リンクからアプリが起動された場合、ディープリンクを処理します。

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

***

## テストユニットID

開発中はテストユニットIDを使用してください。本番リリース前に実際のユニットIDに置き換える必要があります。

### バナー広告

| フォーマット       | テストユニットID                               |
| ------------ | --------------------------------------- |
| バナー（320x50）  | `PUBLIC_TEST_UNIT_ID_320_50`            |
| バナー（320x100） | `PUBLIC_TEST_UNIT_ID_320_100`           |
| カルーセルバナー     | `PUBLIC_TEST_UNIT_ID_CAROUSEL`          |
| バナー動画（16:9）  | `PUBLIC_TEST_UNIT_ID_BANNER_VIDEO_16_9` |
| バナー動画（9:16）  | `PUBLIC_TEST_UNIT_ID_BANNER_VIDEO_9_16` |

### ネイティブ広告

| フォーマット        | テストユニットID                               |
| ------------- | --------------------------------------- |
| ネイティブ（画像）     | `PUBLIC_TEST_UNIT_ID_NATIVE`            |
| ネイティブ動画（16:9） | `PUBLIC_TEST_UNIT_ID_NATIVE_VIDEO_16_9` |
| ネイティブ動画（9:16） | `PUBLIC_TEST_UNIT_ID_NATIVE_VIDEO_9_16` |

### インタースティシャル/リワード広告

| フォーマット     | テストユニットID                          |
| ---------- | ---------------------------------- |
| インタースティシャル | `PUBLIC_TEST_UNIT_ID_INTERSTITIAL` |
| リワード       | `PUBLIC_TEST_UNIT_ID_REWARDED`     |

### ポップアップ広告

| フォーマット           | テストユニットID                                     |
| ---------------- | --------------------------------------------- |
| ポップアップ（下部）       | `PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM`            |
| ポップアップ（中央）       | `PUBLIC_TEST_UNIT_ID_POPUP_CENTER`            |
| ポップアップ動画下部（16:9） | `PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM_VIDEO_16_9` |
| ポップアップ動画下部（9:16） | `PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM_VIDEO_9_16` |
| ポップアップ動画中央（16:9） | `PUBLIC_TEST_UNIT_ID_POPUP_CENTER_VIDEO_16_9` |
| ポップアップ動画中央（9:16） | `PUBLIC_TEST_UNIT_ID_POPUP_CENTER_VIDEO_9_16` |

### スプラッシュ広告

| フォーマット | テストユニットID                    |
| ------ | ---------------------------- |
| スプラッシュ | `PUBLIC_TEST_UNIT_ID_SPLASH` |

***

## エラーコード

広告のロードまたは表示が失敗した場合に返されるエラーコードです。

| エラーコード                                    | 説明              |
| ----------------------------------------- | --------------- |
| `ERROR_CODE_NETWORK`                      | ネットワークエラー       |
| `ERROR_CODE_INTERNAL`                     | 内部エラー           |
| `ERROR_CODE_INITIALIZE`                   | SDK初期化エラー       |
| `ERROR_CODE_INVALID_UNIT`                 | 無効なユニットID       |
| `ERROR_CODE_NOT_TARGET_COUNTRY`           | ターゲット国ではない      |
| `ERROR_CODE_AD_INACTIVE`                  | 非アクティブな広告       |
| `ERROR_CODE_AD_NO_FILL`                   | 表示可能な広告なし       |
| `ERROR_CODE_AD_LOAD_DUPLICATED`           | 重複広告ロードリクエスト    |
| `ERROR_CODE_AD_LOADING`                   | 広告ロード中          |
| `ERROR_CODE_AD_EMPTY`                     | 広告が空            |
| `ERROR_CODE_AD_SHOWN`                     | 広告は既に表示済み       |
| `ERROR_CODE_AD_HIDE_FOR_TODAY`            | 「今日は表示しない」が設定済み |
| `ERROR_CODE_ACCOUNT_USAGE_LIMIT_EXCEEDED` | アカウント使用量の上限超過   |
| `ERROR_CODE_LANDSCAPE_UNSUPPORTED`        | 横向きモード非対応       |
| `ERROR_CODE_AD_BACKFILL_NO_FILL`          | バックフィル広告なし      |

詳細な説明は[リファレンス](/ja/sdk/android/reference#adroperrorcode)を参照してください。

***

## 目次

<CardGroup cols={2}>
  <Card title="バナー広告" href="/ja/sdk/android/banner">
    バナー広告を実装する
  </Card>

  <Card title="ネイティブ広告" href="/ja/sdk/android/native">
    ネイティブ広告を実装する
  </Card>

  <Card title="インタースティシャル広告" href="/ja/sdk/android/interstitial">
    インタースティシャル広告を実装する
  </Card>

  <Card title="リワード広告" href="/ja/sdk/android/rewarded">
    リワード広告を実装する
  </Card>

  <Card title="ポップアップ広告" href="/ja/sdk/android/popup">
    ポップアップ広告を実装する
  </Card>

  <Card title="スプラッシュ広告" href="/ja/sdk/android/splash">
    スプラッシュ広告を実装する
  </Card>

  <Card title="WebViewガイド" href="/ja/sdk/android/webview">
    WebViewでウェブ広告を表示
  </Card>

  <Card title="UMP連携" href="/ja/sdk/android/ump">
    GDPR/CCPA同意管理
  </Card>

  <Card title="ターゲティング設定" href="/ja/sdk/android/targeting">
    ユーザー属性とコンテキストターゲティング
  </Card>

  <Card title="リファレンス" href="/ja/sdk/android/reference">
    クラス、リスナー、エラーコード
  </Card>

  <Card title="サンプル" href="/ja/sdk/android/examples">
    サンプルリポジトリ
  </Card>
</CardGroup>