> ## 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="파일 다운로드">
    [애드컨트롤 콘솔](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 발급은 에이드랍에 문의해주세요.
</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`          | 백필 광고 없음           |

자세한 설명은 [레퍼런스](/ko/sdk/android/reference#adroperrorcode)를 참조하세요.

***

## 목차

<CardGroup cols={2}>
  <Card title="배너 광고" href="/ko/sdk/android/banner">
    배너 광고 구현하기
  </Card>

  <Card title="네이티브 광고" href="/ko/sdk/android/native">
    네이티브 광고 구현하기
  </Card>

  <Card title="전면 광고" href="/ko/sdk/android/interstitial">
    전면 광고 구현하기
  </Card>

  <Card title="보상형 광고" href="/ko/sdk/android/rewarded">
    보상형 광고 구현하기
  </Card>

  <Card title="팝업 광고" href="/ko/sdk/android/popup">
    팝업 광고 구현하기
  </Card>

  <Card title="스플래시 광고" href="/ko/sdk/android/splash">
    스플래시 광고 구현하기
  </Card>

  <Card title="WebView 가이드" href="/ko/sdk/android/webview">
    WebView에서 웹 광고 표시
  </Card>

  <Card title="UMP 연동" href="/ko/sdk/android/ump">
    GDPR/CCPA 동의 관리
  </Card>

  <Card title="타겟팅 설정" href="/ko/sdk/android/targeting">
    사용자 속성 및 문맥 타겟팅
  </Card>

  <Card title="레퍼런스" href="/ko/sdk/android/reference">
    클래스, 리스너, 에러 코드
  </Card>

  <Card title="예제" href="/ko/sdk/android/examples">
    예제 레포지토리
  </Card>
</CardGroup>