Configura AdServices per Android

Segui le istruzioni riportate di seguito per dichiarare autorizzazioni specifiche per l'API e configurare l'accesso SDK alle risorse gestite dall'API target.

Nota: è disponibile una nuova libreria Jetpack che consente l'integrazione con le API Privacy Sandbox di Privacy Sandbox (Topics, Protected Audience e Attribution Reporting. Puoi utilizzare questa libreria come sostituto delle API Privacy Sandbox fornite nell'SDK delle estensioni.

Dichiara autorizzazioni specifiche per l'API AdServices

L'accesso a ogni PPAPI richiede un'autorizzazione normal dei servizi pubblicitari. Nel file manifest, dichiara le autorizzazioni di accesso appropriate che corrispondono alle API necessarie nell'app o nell'SDK.

API Attribution Reporting:

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

API Attribution Reporting (con report di debug):

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

API Protected Audience / Custom Audience:

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

API Topics:

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

Se vuoi, per ricevere report di debug con l'API Attribution Reporting, includi l'autorizzazione AD_ID:

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

Se il progetto ha dipendenze da moduli o SDK, questi potrebbero già dichiarare le autorizzazioni necessarie per i servizi pubblicitari nei file manifest. Per impostazione predefinita, la build di Gradle unisce tutti i file manifest in un unico file manifest pacchettizzato nella tua app. Utilizza la visualizzazione Manifest unito per verificare che vengano utilizzate le autorizzazioni corrette.

Se devi impedire che alcune autorizzazioni vengano unite nella tua app tramite dipendenze come gli SDK, includi l'indicatore di nodo remove per le autorizzazioni specifiche. L'esempio seguente mostra come impedire l'unione dell'autorizzazione Topics.

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

Configura servizi pubblicitari specifici per API

Analogamente alle autorizzazioni di accesso PPAPI, ogni API ha una voce corrispondente nella configurazione dei servizi pubblicitari. Questa configurazione ti offre un controllo granulare dell'accesso alle risorse gestite dalle API nella tua app o nell'SDK incorporato. Nel file manifest, specifica una proprietà adservicesConfig come mostrato nel seguente esempio:

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

      ...
</application>

Specifica la risorsa XML dei servizi pubblicitari a cui viene fatto riferimento nel manifest, ad esempio res/xml/ad_services_config.xml. Per ogni API incentrata sulla tutela della privacy applicabile alla tua app (o all'SDK incorporato), imposta l'attributo allowAllToAccess su true per concedere l'accesso a tutti i chiamanti.

In alternativa, puoi utilizzare l'attributo allowAdPartnersToAccess per concedere un accesso API granulare a ogni ad tech. Dovrai fornire un elenco di ID account di registrazione sviluppatori ottenuti tramite registrazione. Se l'attributo allowAllToAccess è impostato su true, questo ha la precedenza su qualsiasi ID account di registrazione specificato nell'attributo allowAdPartnersToAccess.

Nota: per accedere alle API Privacy Sandbox nell'ultima release dell'estensione SDK AdServices e nella release Anteprima sviluppatore, devi completare il processo di registrazione.

Le piattaforme ad tech devono inoltre assicurarsi che i client delle app concedano correttamente l'accesso alle API incentrate sulla tutela della privacy richieste nella configurazione dei servizi pubblicitari.

Nota: a causa di un bug noto, devi impostare allowAllToAccess su true per i test in locale.

L'esempio seguente mostra come specificare l'accesso ampio per consentire a qualsiasi ID account di registrazione di accedere a tutte le API incentrate sulla tutela della privacy:

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

L'esempio seguente mostra come specificare l'accesso granulare a ogni API che garantisce la tutela della privacy per ID account di registrazione specifici:

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

Nota: se la registrazione è disabilitata per l'API Topics o l'API Protected Audience utilizzando i comandi adb, l'app potrà accedere alle API correlate indipendentemente dai controlli di accesso specificati in ad-services-config.

Dichiarare le dipendenze della libreria Jetpack

Utilizza la libreria Jetpack ads-adservices 1.0.0-beta01 o successiva per l'integrazione con le API incentrate sulla tutela della privacy di Privacy Sandbox. Puoi utilizzare questa libreria per astrarre la tua app dai dettagli a livello di piattaforma e semplificare l'integrazione con API incentrate sulla tutela della privacy.

1. Aggiungi un repository Maven al progetto.
2. Dichiara le dipendenze della libreria Jetpack ads-adservices nel file build.gradle per l'app o il modulo.
3. Utilizza le API dei pacchetti androidx.privacysandbox.ads.adservices.*.
4. La libreria Jetpack di annunci e servizi offre supporto integrato per le coroutine Kotlin. Per gestire gli ambiti delle coroutine, potresti dover incorporare le dipendenze sensibili al ciclo di vita appropriate per il tuo progetto.

Verifica la disponibilità della versione delle estensioni dei servizi pubblicitari

Se utilizzi la libreria Jetpack degli annunci dei servizi per l'integrazione con le API incentrate sulla tutela della privacy, la libreria controlla la disponibilità delle API richieste nella funzione obtain(). La funzione restituisce null se l'API richiesta non è disponibile sul dispositivo. L'esempio seguente illustra come inizializzare TopicsManager per l'API Topics. Funziona in modo simile per l'accesso ad altre API incentrate sulla tutela della privacy.

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

Se utilizzi le API AdServices direttamente nell'SDK Extension, controlla la versione delle estensioni AdServices che includa le API AdServices che vuoi utilizzare. Nel riferimento API, puoi identificare la versione in cui viene introdotta una determinata API AdServices. Ad esempio, il riferimento API per la classe TopicsManager indica che è "Aggiunto nelle estensioni dei servizi pubblicitari 4". Utilizza i seguenti controlli condizionali per convalidare le estensioni SDK che contengono API AdServices.

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

Limitazione dell'accesso in primo piano

Per garantire trasparenza, l'accesso a SDK Runtime e alle API incentrate sulla tutela della privacy è limitato alle app con un'attività visibile o con RunningAppProcessInfo pari a IMPORTANCE_FOREGROUND.