시작하기 - Ad Control Help Center

개요

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 파일 추가

파일 다운로드

애드컨트롤 콘솔 > Admin > App 에서 adrop_service.json 파일을 다운로드합니다.

프로젝트에 추가

다운로드한 파일을 app/src/main/assets/ 폴더에 추가합니다.

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

adrop_service.json 파일이 없으면 SDK가 정상 동작하지 않습니다.

2. 유닛 ID 확인

콘솔의 Ad Unit 탭에서 광고 지면에 해당하는 유닛 ID를 확인합니다.

설치

Gradle 설정

Settings.gradle.kts

프로젝트 수준 settings.gradle.kts 파일에 저장소를 추가합니다:

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

앱 수준 build.gradle 또는 build.gradle.kts 파일에 의존성을 추가합니다:

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

최신 버전은 Maven Central에서 확인하세요.

AndroidManifest.xml 설정

백필 광고를 위해 AndroidManifest.xml에 App ID를 추가합니다:

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>

App ID 발급은 에이드랍에 문의해주세요.

초기화

Application 클래스의 onCreate()에서 SDK를 초기화합니다.

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

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

초기화 파라미터

파라미터	타입	기본값	설명
`context`	`Application`	-	앱의 Application 인스턴스 (필수)
`production`	`Boolean`	`false`	프로덕션 모드 여부. 배포 시 `true`로 설정
`targetCountries`	`Array<String>`	`[]`	타겟 국가 코드 목록 (ISO 3166 alpha-2)
`tokenKey`	`String?`	`null`	`adrop_service.json`의 앱 토큰 키 (선택)

adrop_service.json에 여러 앱 설정이 포함되어 있는 경우, tokenKey를 사용하여 초기화에 사용할 키를 지정합니다.

배포 전 반드시 production = true로 설정하세요. false로 배포하면 광고가 노출되지 않습니다.

사용자 설정

UID 설정

타겟팅 광고를 위해 사용자 식별자를 설정합니다.

Adrop.setUID("user_123")

Adrop.INSTANCE.setUID("user_123");

타겟팅 광고가 정상 동작하려면 광고 지면 진입 전에 UID를 설정하세요.

테마 설정

다크 모드를 지원하는 광고를 위해 테마를 설정합니다. initialize() 호출 후 설정해야 합니다.

// 라이트 모드
Adrop.setTheme(AdropTheme.LIGHT)

// 다크 모드
Adrop.setTheme(AdropTheme.DARK)

// 시스템 설정 따르기 (권장)
Adrop.setTheme(AdropTheme.AUTO)

// 라이트 모드
Adrop.INSTANCE.setTheme(AdropTheme.LIGHT);

// 다크 모드
Adrop.INSTANCE.setTheme(AdropTheme.DARK);

// 시스템 설정 따르기 (권장)
Adrop.INSTANCE.setTheme(AdropTheme.AUTO);

AUTO 모드는 시스템 다크 모드 설정을 자동으로 감지합니다. 테마가 변경되면 스플래시 광고 캐시가 자동으로 초기화됩니다.

딥링크 처리

외부 링크를 통해 앱이 실행된 경우 딥링크를 처리합니다.

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

테스트 유닛 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`	백필 광고 없음

자세한 설명은 레퍼런스를 참조하세요.

배너 광고

배너 광고 구현하기

네이티브 광고

네이티브 광고 구현하기

전면 광고

전면 광고 구현하기

보상형 광고

보상형 광고 구현하기

팝업 광고

팝업 광고 구현하기

스플래시 광고

스플래시 광고 구현하기

WebView 가이드

WebView에서 웹 광고 표시

UMP 연동

GDPR/CCPA 동의 관리

타겟팅 설정

사용자 속성 및 문맥 타겟팅

레퍼런스

클래스, 리스너, 에러 코드

예제

예제 레포지토리

​개요

​지원 광고 포맷

​요구 사항

​사전 준비

​1. adrop_service.json 파일 추가

​2. 유닛 ID 확인

​설치

​Gradle 설정

​Settings.gradle.kts

​Build.gradle.kts

​AndroidManifest.xml 설정

​초기화

​초기화 파라미터

​사용자 설정

​UID 설정

​테마 설정

​딥링크 처리

​테스트 유닛 ID

​배너 광고

​네이티브 광고

​전면/보상형 광고

​팝업 광고

​스플래시 광고

​에러 코드

​목차

배너 광고

네이티브 광고

전면 광고

보상형 광고

팝업 광고

스플래시 광고

WebView 가이드

UMP 연동

타겟팅 설정

레퍼런스

예제

개요

지원 광고 포맷

요구 사항

사전 준비

1. adrop_service.json 파일 추가

2. 유닛 ID 확인

설치

Gradle 설정

Settings.gradle.kts

Build.gradle.kts

AndroidManifest.xml 설정

초기화

초기화 파라미터

사용자 설정

UID 설정

테마 설정

딥링크 처리

테스트 유닛 ID

배너 광고

네이티브 광고

전면/보상형 광고

팝업 광고

스플래시 광고

에러 코드

목차