Android용 AdServices 구성

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

참고: 개인 정보 보호와 통합할 수 있는 새로운 Jetpack 라이브러리가 있습니다. 샌드박스의 개인 정보 보호 API (Topics, Protected Audience 및 기여도 보고. 이 라이브러리를 삽입형으로 사용할 수 있습니다. Extension SDK에 제공된 개인 정보 보호 샌드박스 API를 대체합니다.

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에는 광고 서비스 구성에 상응하는 항목이 있습니다. 이 구성을 사용하면 앱의 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). 적용 가능한 각 개인 정보 보호 API에 대해 앱 (또는 삽입된 SDK)에서 allowAllToAccess 속성을 true로 설정하여 모든 호출자에게 액세스 권한을 부여할 수 있습니다.

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

참고: 최신 AdServices SDK 확장 프로그램 버전 및 개발자 프리뷰 버전에서 개인 정보 보호 샌드박스 API에 액세스하려면 등록 프로세스를 완료해야 합니다.

또한 광고 기술 플랫폼은 앱 클라이언트가 광고 기술 제공업체에게 광고 서비스 구성에서 필수 개인 정보 보호 API에 대한 액세스

참고: 알려진 버그로 인해 로컬에서 테스트할 때는 allowAllToAccess를 true로 설정해야 합니다.

다음 예시에서는 모든 등록을 허용하기 위해 광범위한 액세스 권한을 지정하는 방법을 보여줍니다. 계정 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>

참고: Topics API 또는 Protected Audience API 등록이 사용 중지된 경우 adb 명령어를 사용하면 앱이 다른 애플리케이션과 상관없이 관련 API에 액세스할 수 있습니다. ad-services-config에 지정된 액세스 제어

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

개인 정보 보호 샌드박스의 개인 정보 보호 API와 통합하려면 ads-adservices Jetpack 라이브러리 1.0.0-beta01 이상을 사용합니다. 이 라이브러리를 사용하여 플랫폼 수준 세부정보에서 앱을 분리하고 개인 정보 보호 API에 대해 알아봅니다.

1. 프로젝트에 Maven 저장소를 추가합니다.
2. 앱 또는 모듈의 build.gradle 파일에 ads-adservices Jetpack 라이브러리 종속 항목을 선언합니다.
3. androidx.privacysandbox.ads.adservices.* 패키지의 API를 사용합니다.
4. 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가 사용하는 버전을 식별할 수 있습니다. 자세히 알아보겠습니다 예를 들어 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에 대한 액세스 가시적인 활동이 있거나 RunningAppProcessInfo/IMPORTANCE_FOREGROUND