Mengonfigurasi AdServices untuk Android

Ikuti petunjuk di bawah ini untuk mendeklarasikan izin khusus API, dan mengonfigurasi akses SDK ke resource yang dikelola oleh API yang ditargetkan.

Mendeklarasikan izin khusus API AdServices

Akses ke setiap PPAPI memerlukan izin normal Layanan Iklan. Di manifes, deklarasikan izin akses yang tepat, yang sesuai dengan API yang diperlukan di aplikasi atau SDK Anda.

Attribution Reporting API:

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

Attribution Reporting API (dengan laporan debug):

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

Protected Audience/custom audience API:

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

Topics API:

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

Secara opsional, sertakan izin AD_ID untuk menerima laporan debug dengan Attribution Reporting API:

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

Jika project Anda memiliki dependensi pada modul atau SDK, izin tersebut mungkin sudah mendeklarasikan izin Layanan Iklan yang diperlukan dalam file manifesnya. Secara default, build Gradle menggabungkan semua file manifes ke dalam satu file manifes yang dikemas ke dalam aplikasi Anda. Gunakan tampilan Manifes Gabungan untuk memverifikasi bahwa telah menggunakan izin yang benar.

Jika Anda perlu mencegah izin apa pun agar tidak digabungkan ke aplikasi melalui dependensi seperti SDK, sertakan penanda node remove untuk izin tertentu. Contoh berikut menunjukkan cara mencegah penggabungan izin Topics.

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

Mengonfigurasi Layanan Iklan khusus API

Serupa dengan izin akses PPAPI, setiap API memiliki entri yang sesuai dalam konfigurasi layanan iklan. Konfigurasi ini memberi Anda akses kontrol yang terperinci ke resource yang dikelola oleh API di aplikasi Anda atau SDK tersemat. Dalam manifes, tentukan properti adservicesConfig seperti yang ditunjukkan pada contoh berikut:

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

      ...
</application>

Tentukan resource XML layanan iklan yang dirujuk dalam manifes, seperti res/xml/ad_services_config.xml. Untuk setiap API perlindungan privasi yang berlaku untuk aplikasi Anda (atau SDK tersemat), tetapkan atribut allowAllToAccess ke true untuk memberikan akses ke pemanggil apa pun.

Atau, Anda dapat menggunakan atribut allowAdPartnersToAccess untuk memberikan akses API yang lebih mendetail untuk setiap teknologi iklan. Anda harus memberikan daftar ID akun pendaftaran developer yang diperoleh melalui pendaftaran. Jika atribut allowAllToAccess ditetapkan ke true, atribut ini lebih diprioritaskan daripada ID akun pendaftaran yang ditentukan dalam atribut allowAdPartnersToAccess.

Platform teknologi iklan juga harus memastikan bahwa klien aplikasi mereka memberikan akses dengan benar ke API perlindungan privasi yang diperlukan dalam konfigurasi layanan iklan.

Contoh berikut menunjukkan cara menentukan akses secara luas untuk mengizinkan akses ID akun pendaftaran ke semua API perlindungan privasi:

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

Contoh berikut menunjukkan cara menentukan akses yang lebih mendetail ke setiap API perlindungan privasi untuk ID akun pendaftaran tertentu:

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

Mendeklarasikan dependensi library Jetpack

Gunakan library Jetpack ads-adservices 1.0.0-beta01 atau yang lebih tinggi untuk berintegrasi dengan API perlindungan privasi Privacy Sandbox. Anda dapat menggunakan library ini untuk memisahkan aplikasi Anda dari detail tingkat platform dan menyederhanakan integrasi dengan API perlindungan privasi.

1. Tambahkan repositori Maven ke project Anda.
2. Deklarasikan dependensi library Jetpack ads-adservices di file build.gradle untuk aplikasi atau modul Anda.
3. Gunakan API dari paket androidx.privacysandbox.ads.adservices.*.
4. Library Jetpack ads-adservices menyediakan dukungan coroutine Kotlin bawaan. Anda mungkin perlu menyertakan dependensi berbasis siklus proses yang sesuai agar project dapat mengelola cakupan coroutine.

Memeriksa ketersediaan versi Ekstensi Layanan Iklan

Jika Anda menggunakan library Jetpack ads-services untuk berintegrasi dengan API perlindungan privasi, library akan memeriksa ketersediaan API yang diminta dalam fungsi obtain(). Fungsi ini menampilkan null jika API yang diminta tidak tersedia di perangkat. Contoh berikut menggambarkan cara melakukan inisialisasi TopicsManager untuk Topics API. Cara kerjanya sama seperti mengakses API perlindungan privasi lain.

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)

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

Jika Anda menggunakan AdServices API secara langsung di SDK Ekstensi, periksa versi Ekstensi AdServices yang menyertakan AdServices API yang ingin Anda gunakan. Dalam referensi API, Anda dapat mengidentifikasi versi tempat AdServices API tertentu diperkenalkan. Misalnya, referensi API untuk class TopicsManager menunjukkan bahwa class tersebut "Ditambahkan dalam Ekstensi Layanan Iklan 4". Gunakan pemeriksaan bersyarat berikut untuk memvalidasi ekstensi SDK yang berisi AdServices API.

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

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

Batasan akses latar depan

Untuk memberikan transparansi, akses ke Runtime SDK dan API yang menjaga privasi dibatasi untuk aplikasi dengan Aktivitas yang terlihat, atau dengan RunningAppProcessInfo dari IMPORTANCE_FOREGROUND.