운영 키와 콜백 URL은 운영 콘솔에서 설정합니다. 공통 GAD 매체사 계정으로 로그인하며 운영 데이터와 설정은 스테이징과 분리됩니다.

Android SDK 빠른 시작

GAD Android SDK 0.9.0 을 앱에 넣고 프로덕션 서버의 광고 목록을 띄웁니다.

운영 콘솔에서 Android SDK 매체를 등록하고 운영 미디어키를 확보한 뒤 아래 설치를 진행하세요. 운영 매체 등록과 키 확인은 운영 콘솔에서 진행합니다.

1. 설치

프로젝트 수준 Gradle 설정에 JitPack 저장소를 더합니다. SDK 가 끌어오는 AndroidX·Material·Play 서비스 라이브러리를 받으려면 google() 과 mavenCentral() 도 있어야 합니다.

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

최근 Android Studio 템플릿처럼 settings.gradle 의 dependencyResolutionManagement 로 저장소를 관리하는 프로젝트는(FAIL_ON_PROJECT_REPOS 이면 위 allprojects 블록이 빌드 오류를 냅니다) 같은 저장소를 거기에 적습니다.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

모듈 수준 build.gradle 에 의존성을 더합니다.

dependencies {
    implementation 'com.github.koreagpa-dev:gad:0.9.0'
}

2. Gradle 설정

같은 모듈의 android 블록에 데이터 바인딩과 Java 8 설정을 넣습니다.

android {
    buildFeatures {
        dataBinding = true
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

• 앱 모듈의 compileSdk 는 34 이상이어야 합니다. SDK 가 끌어오는 androidx 라이브러리(appcompat 1.7.1, constraintlayout 2.2.1)의 요건입니다. SDK 자체는 compileSdk 35 로 빌드됩니다.

프로젝트의 gradle.properties에 AndroidX와 Jetifier를 켭니다. SDK의 전이 의존성에 포함된 이전 support 라이브러리를 AndroidX로 변환합니다.

android.useAndroidX=true
android.enableJetifier=true

3. 매니페스트 권한

targetSdkVersion 이 33(Android 13) 이상이면 매니페스트에 광고 ID 권한을 선언합니다.

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

공개 SDK 0.9.0 AAR의 매니페스트에는 AD_ID와 android.permission.GET_ACCOUNTS가 선언되어 앱의 병합 매니페스트에 반영됩니다. READ_EXTERNAL_STORAGE는 주석 처리되어 있어 이 AAR에서 권한으로 추가되지 않습니다. 출시 전 앱의 최종 병합 매니페스트와 스토어 개인정보 신고 항목을 확인하세요.

4. 초기화와 환경 지정

매체 앱의 사용자 로그인을 마친 뒤 미디어키와 사용자 ID 로 한 번 초기화합니다. 네 번째 인자로 환경을 넘깁니다.

import com.gad.sdk.Gad;
import com.gad.sdk.GadEnvironment;

// 프로덕션 서버로 초기화
Gad.init(this, mediaKey, userId, GadEnvironment.PRODUCTION);

• 환경 인자를 주지 않는 Gad.init(context, mediaKey, userId) 는 운영 서버로 접속합니다.
• 이 문서의 초기화 예제는 GadEnvironment.PRODUCTION 을 사용합니다. 운영 API 주소는 https://gad.api.gpakorea.com 입니다. 앱의 초기화 설정과 실제 요청 대상을 함께 확인하세요.
• 공개 SDK 0.9.0은 광고 목록·상세 화면이 활성화될 때 FLAG_SECURE를 설정해 캡처를 차단하고, 화면을 떠날 때 해제합니다. 앱 자체가 디버그 빌드여도 이 공개 SDK의 차단은 적용됩니다.
• 스테이징으로 초기화한 뒤 환경 인자가 없는 초기화를 다시 부르면 운영으로 바뀝니다. 초기화 호출은 한 곳에만 둡니다.
• Gad.useDebugServer 는 폐기 예정입니다. 환경을 지정한 초기화 뒤에 부르면 고른 서버를 덮어쓰므로 함께 쓰지 않습니다.
• 출시 빌드에는 스테이징 지정을 남기지 않습니다.

5. 광고 목록 띄우기

새 화면(액티비티)으로 띄우거나, 앱 화면 안에 프래그먼트로 넣습니다.

// 새 화면으로 띄우기
Gad.showAdList(this);

// 프래그먼트로 넣기
getSupportFragmentManager().beginTransaction()
        .replace(R.id.fragment, Gad.getAdListFragment(this))
        .commitAllowingStateLoss();

사용자의 성별과 나이를 알고 있으면 초기화 뒤에 넘겨 맞는 광고를 받을 수 있습니다(선택).

Gad.setUserInfo("M", 22);

6. 확인

1. 운영 콘솔에서 발급한 Android SDK 미디어키를 사용합니다. 스테이징 키와 구분하세요.
2. 초기화 환경이 GadEnvironment.PRODUCTION 으로 지정되어 있고 요청 대상이 https://gad.api.gpakorea.com 인지 확인합니다. 광고 목록에서 운영 광고가 표시되는지 확인합니다.
3. 포스트백 수신 서버의 운영 콜백 URL과 중복 지급 방지 처리가 준비되어 있는지 확인합니다.

테스트 광고로 연동을 검증하려면 상단 환경 이동 버튼으로 스테이징으로 전환하세요.

운영 수신 서버의 본문과 재전송 처리는 포스트백 규격을 보세요. 테스트 광고의 검증 절차는 상단 환경 이동 버튼으로 스테이징으로 전환한 뒤 확인합니다.