Configura AdServices per Android

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

Nota: è disponibile una nuova libreria Jetpack che consente l'integrazione con le API incentrate sulla tutela della privacy di Privacy Sandbox (Topics, Protected Audience e Attribution Reporting. Puoi utilizzare questa libreria come sostituzione diretta per le API Privacy Sandbox fornite nell'SDK estensione.

Dichiara le autorizzazioni specifiche dell'API AdServices

L'accesso a ogni PPAPI richiede un'autorizzazione normal per i servizi pubblicitari. Nel file manifest, dichiara le autorizzazioni di accesso appropriate che corrispondono alle API necessarie nella tua 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" />

Facoltativamente, 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 richieste per i servizi pubblicitari nei propri file manifest. Per impostazione predefinita, la build di Gradle unisce tutti i file manifest in un unico file manifest incluso nella tua app. Utilizza la vista File 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" />

Configurare 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 consente di avere un accesso con controllo granulare alle risorse gestite dalle API nella tua app o nell'SDK incorporato.

Nota: la configurazione di servizi pubblicitari specifici è facoltativa ed è necessaria solo quando uno sviluppatore di app vuole modificare o limitare l'accesso a un'API, poiché tutti gli accessi sono concessi per impostazione predefinita.

Nel file manifest, specifica una proprietà adservicesConfig come mostrato nell'esempio seguente:

<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 file 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 all'API granulare per ogni tecnologia pubblicitaria. Dovrai fornire un elenco di ID account di registrazione sviluppatori ottenuti tramite la registrazione. Se l'attributo allowAllToAccess è impostato su true, questo attributo ha la precedenza su qualsiasi ID account di registrazione specificato nell'attributo allowAdPartnersToAccess.

Nota: per accedere alle API Privacy Sandbox nella più recente release dell'estensione SDK AdServices e nella versione Anteprima per gli sviluppatori, devi completare la procedura di registrazione.

Le piattaforme ad tech devono anche assicurarsi che i client delle app concedano correttamente l'accesso alle API che tutelano la privacy richieste nella configurazione dei servizi pubblicitari.

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

L'esempio seguente mostra come specificare l'accesso ampio per consentire a qualsiasi ID account di registrazione l'accesso 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 un accesso granulare a ogni API che tutela la 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 viene disattivata per l'API Topics o per l'API Protected Audience utilizzando i comandi adb, l'app può accedere alle API correlate indipendentemente dai controlli dell'accesso specificati in ad-services-config.

Dichiara le dipendenze della libreria Jetpack

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

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

Verifica la disponibilità della versione delle estensioni dei servizi pubblicitari

Se utilizzi la libreria Jetpack di Google Ads per i servizi per l'integrazione con API che tutelano la 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 accedere ad altre API che tutelano la 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 di AdServices Extensions che include le API AdServices che vuoi utilizzare. Nel riferimento dell'API, puoi identificare la versione in cui viene introdotta una determinata API AdServices. Ad esempio, il riferimento API per la classe TopicsManager indica che la classe è "Aggiunto in Ad Services Extensions 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 che tutelano la privacy è limitato alle app con un'attività visibile o con RunningAppProcessInfo di IMPORTANCE_FOREGROUND.