이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Android용 AdServices 구성

아래 안내에 따라 API별 권한을 선언하고 타겟팅된 API에서 관리하는 리소스에 대한 SDK 액세스를 구성합니다.

AdServices API 관련 권한 선언

각 PPAPI에 액세스하려면 광고 서비스 normal 권한이 필요합니다. 매니페스트에서 앱 또는 SDK에 필요한 API에 상응하는 적절한 액세스 권한을 선언합니다.

Attribution Reporting API:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />

Attribution Reporting API(디버그 보고서 포함):

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

Protected Audience/ 맞춤 잠재고객 API:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />

Topics API:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />

필요한 경우 Attribution Reporting API를 사용하여 디버그 보고서를 수신하려면 AD_ID 권한을 포함합니다.

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

프로젝트에 모듈 또는 SDK에 대한 종속 항목이 있는 경우 필요한 광고 서비스 권한을 매니페스트 파일에서 이미 선언했을 수 있습니다. 기본적으로 Gradle 빌드는 모든 매니페스트 파일을 앱에 패키징되는 단일 매니페스트 파일로 병합합니다. 병합된 매니페스트 뷰를 사용하여 올바른 권한이 사용되고 있는지 확인합니다.

SDK와 같은 종속 항목을 통해 권한이 앱에 병합되지 않도록 해야 하는 경우 특정 권한에 대해 remove 노드 마커를 포함하세요. 다음 예는 Topics 권한의 병합을 방지하는 방법을 보여줍니다.

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS"
    tools:node="remove" />

API 관련 광고 서비스 구성

PPAPI 액세스 권한과 마찬가지로 각 API에는 광고 서비스 구성에 상응하는 항목이 있습니다. 이 구성을 사용하면 앱 또는 삽입된 SDK의 API에서 관리하는 리소스에 대한 액세스를 세부적으로 제어할 수 있습니다. 다음 예와 같이 매니페스트에서 adservicesConfig 속성을 지정합니다.

<application ...>
      ...
    <property android:name="android.adservices.AD_SERVICES_CONFIG"
        android:resource="@xml/ad_services_config" />

      ...
</application>

매니페스트에 참조된 광고 서비스 XML 리소스를 지정합니다(예: res/xml/ad_services_config.xml). 앱 (또는 삽입된 SDK)에 적용할 수 있는 개인 정보 보호 API마다 allowAllToAccess 속성을 true로 설정하여 모든 호출자에게 액세스 권한을 부여합니다.

또는 allowAdPartnersToAccess 속성을 사용하여 각 광고 기술에 세분화된 API 액세스 권한을 부여할 수 있습니다. 등록을 통해 얻은 개발자 등록 계정 ID 목록을 제공해야 합니다. allowAllToAccess 속성이 true로 설정되면 이 속성이 allowAdPartnersToAccess 속성에 지정된 등록 계정 ID보다 우선 적용됩니다.

또한 광고 기술 플랫폼은 앱 클라이언트가 광고 서비스 구성에서 필수 개인 정보 보호 API에 대한 액세스 권한을 올바르게 부여하도록 해야 합니다.

다음 예는 모든 등록 계정 ID에서 모든 개인 정보 보호 API에 액세스할 수 있도록 광범위한 액세스를 지정하는 방법을 보여줍니다.

<ad-services-config>
   <!-- Attribution API -->
   <attribution allowAllToAccess="true" />

   <!-- Topics API -->
   <topics allowAllToAccess="true" />

   <!-- Protected Audience on Android API -->
   <custom-audiences allowAllToAccess="true" />
</ad-services-config>

다음 예는 특정 등록 계정 ID에 각 개인 정보 보호 API에 대한 세분화된 액세스 권한을 지정하는 방법을 보여줍니다.

<ad-services-config>
    <!-- Attribution API -->
    <attribution allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Topics API -->
    <includes-sdk-library name="ENROLLMENT-ID" />
    <topics allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Protected Audience on Android API -->
    <custom-audiences allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />
</ad-services-config>

Jetpack 라이브러리 종속 항목 선언

개인 정보 보호 샌드박스의 개인 정보 보호 API와 통합하려면 ads-adservices Jetpack 라이브러리 1.0.0-beta01 이상을 사용합니다. 이 라이브러리를 사용하면 앱을 플랫폼 수준 세부정보에서 추상화하고 개인 정보 보호 API와의 통합을 간소화할 수 있습니다.

프로젝트에 Maven 저장소를 추가합니다.
앱 또는 모듈의 build.gradle 파일에 ads-adservices Jetpack 라이브러리 종속 항목을 선언합니다.
androidx.privacysandbox.ads.adservices.* 패키지의 API를 사용합니다.
ads-adservices Jetpack 라이브러리는 내장된 Kotlin 코루틴 지원을 제공합니다. 코루틴 범위를 관리하기 위해 프로젝트에 적합한 수명 주기 인식 종속 항목을 통합해야 할 수 있습니다.

광고 서비스 확장 프로그램 버전의 사용 가능 여부 확인

ads-services Jetpack 라이브러리를 사용하여 개인 정보 보호 API와 통합하는 경우 라이브러리는 obtain() 함수에서 요청된 API의 사용 가능 여부를 확인합니다. 요청된 API를 기기에서 사용할 수 없으면 함수는 null을 반환합니다. 다음 예는 Topics API의 TopicsManager를 초기화하는 방법을 보여줍니다. 다른 개인 정보 보호 API에 액세스하는 경우에도 비슷하게 작동합니다.

Kotlin

import androidx.privacysandbox.ads.adservices.topics.TopicsManager

// The initialization function will return null if the requested
// functionality is not available on the device.
val topicsManager = TopicsManager.obtain(context)

Java

import androidx.privacysandbox.ads.adservices.topics.TopicsManager;

// The initialization function will return null if the requested
// functionality is not available on the device.
TopicsManager topicsManager = TopicsManager.obtain(context);

확장 프로그램 SDK에서 직접 AdServices API를 사용하고 있다면 사용할 AdServices API가 포함된 AdServices 확장 프로그램 버전을 확인합니다. API 참조에서 특정 AdServices API가 도입된 버전을 확인할 수 있습니다. 예를 들어 TopicsManager 클래스의 API 참조는 '광고 서비스 확장 프로그램 4에 추가됨'을 나타냅니다. AdServices API를 포함하는 SDK 확장 프로그램의 유효성을 검사하려면 다음 조건부 검사를 사용합니다.

Kotlin

import android.os.ext.SdkExtensions

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

Java

import android.os.ext.SdkExtensions;

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

포그라운드 액세스 제한

투명성을 제공하기 위해 SDK 런타임 및 개인 정보 보호 API에 대한 액세스는 활동이 표시되거나 IMPORTANCE_FOREGROUND의 RunningAppProcessInfo가 있는 앱으로 제한됩니다.