AdServices für Android konfigurieren

Folgen Sie der Anleitung unten, um API-spezifische Berechtigungen zu deklarieren und den SDK-Zugriff auf Ressourcen zu konfigurieren, die von der Ziel-API verwaltet werden.

Hinweis :Es gibt eine neue Jetpack-Bibliothek, die die Einbindung der datenschutzfreundlichen APIs Topics, Protected Audience und Attribution Reporting ermöglicht. Sie können diese Bibliothek als Drop-in-Ersatz für die Privacy Sandbox APIs verwenden, die im Extension SDK enthalten sind.

Spezifische Berechtigungen für AdServices API deklarieren

Für den Zugriff auf die einzelnen PPAPI ist die Berechtigung normal von Ad Services erforderlich. Deklariere in deinem Manifest die entsprechenden Zugriffsberechtigungen, die den in deiner App oder deinem SDK erforderlichen APIs entsprechen.

Attribution Reporting API:

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

Attribution Reporting API (mit Berichten zur Fehlerbehebung):

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

Protected Audience API / Custom Audience API:

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

Topics API:

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

Optional: Um Debug-Berichte mit der Attribution Reporting API zu erhalten, schließen Sie die Berechtigung AD_ID ein:

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

Wenn Ihr Projekt Abhängigkeiten von Modulen oder SDKs hat, deklarieren diese die erforderlichen Ad Services-Berechtigungen möglicherweise bereits in ihren Manifestdateien. Standardmäßig führt der Gradle-Build alle Manifestdateien in einer Manifestdatei zusammen, die in Ihre App verpackt ist. Prüfen Sie in der Ansicht Merged Manifest, ob die richtigen Berechtigungen verwendet wurden.

Wenn Sie verhindern möchten, dass Berechtigungen über Abhängigkeiten wie SDKs mit Ihrer App zusammengeführt werden, fügen Sie für die jeweiligen Berechtigungen die Knotenmarkierung remove ein. Das folgende Beispiel zeigt, wie Sie das Zusammenführen der Berechtigung „Themen“ verhindern.

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

API-spezifische Anzeigendienste konfigurieren

Ähnlich wie bei den PPAPI-Zugriffsberechtigungen hat jede API einen entsprechenden Eintrag in der Konfiguration der Anzeigendienste. Mit dieser Konfiguration können Sie den Zugriff auf Ressourcen, die von den APIs in Ihrer App oder im eingebetteten SDK verwaltet werden, detailliert steuern. Geben Sie in Ihrem Manifest ein adservicesConfig-Attribut an, wie im folgenden Beispiel gezeigt:

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

      ...
</application>

Geben Sie die XML-Ressource für Anzeigendienste an, auf die im Manifest verwiesen wird, z. B. res/xml/ad_services_config.xml. Setze für jede datenschutzfreundliche API, die für deine App (oder eingebettetes SDK) gilt, das Attribut allowAllToAccess auf true, um allen Aufrufern Zugriff zu gewähren.

Alternativ können Sie das Attribut allowAdPartnersToAccess verwenden, um einzelnen Anzeigentechnologien detaillierten API-Zugriff zu gewähren. Sie müssen eine Liste der Registrierungskonto-IDs von Entwicklern angeben, die Sie über die Registrierung erhalten haben. Wenn das Attribut allowAllToAccess auf true gesetzt ist, hat dieses Attribut Vorrang vor allen Registrierungskonto-IDs, die im Attribut allowAdPartnersToAccess angegeben sind.

Hinweis :Für den Zugriff auf die Privacy Sandbox APIs in der neuesten Version der AdServices SDK-Erweiterung und in der Entwicklervorschau müssen Sie sich registrieren.

AdTech-Plattformen sollten außerdem dafür sorgen, dass ihre App-Clients in der Konfiguration der Anzeigendienste ordnungsgemäß Zugriff auf die erforderlichen datenschutzfreundlichen APIs gewähren.

Hinweis: Aufgrund eines bekannten Programmfehlers sollten Sie allowAllToAccess bei lokalen Tests auf true setzen.

Das folgende Beispiel zeigt, wie Sie einen umfassenden Zugriff festlegen, um jeder Registrierungskonto-ID Zugriff auf alle datenschutzfreundlichen APIs zu gewähren:

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

Das folgende Beispiel zeigt, wie Sie einen detaillierten Zugriff auf jede datenschutzfreundliche API für bestimmte Registrierungskonto-IDs angeben können:

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

Hinweis :Wenn die Registrierung für die Topics API oder die Protected Audience API mithilfe von ADB-Befehlen deaktiviert ist, kann die App unabhängig von den in ad-services-config angegebenen Zugriffssteuerungen auf zugehörige APIs zugreifen.

Abhängigkeiten der Jetpack-Bibliothek deklarieren

Verwenden Sie die ads-adservices Jetpack-Bibliothek 1.0.0-beta01 oder höher, um die datenschutzfreundlichen APIs der Privacy Sandbox einzubinden. Sie können diese Bibliothek verwenden, um Ihre App von Details auf Plattformebene zu abstrahieren und die Integration mit datenschutzfreundlichen APIs zu vereinfachen.

1. Fügen Sie Ihrem Projekt ein Maven-Repository hinzu.
2. Deklarieren Sie Abhängigkeiten der Ads-adservices Jetpack-Bibliothek in der Datei build.gradle für Ihre App oder Ihr Modul.
3. Verwenden Sie APIs aus den androidx.privacysandbox.ads.adservices.*-Paketen.
4. Die Jetpack-Bibliothek „ads-adservices“ bietet integrierte Unterstützung für die Kotlin-Koroutine. Möglicherweise müssen Sie die auf den Lebenszyklus berücksichtigenden Abhängigkeiten für Ihr Projekt einbinden, um Koroutinenbereiche zu verwalten.

Verfügbarkeit der Version der Anzeigendienste-Erweiterungen prüfen

Wenn Sie die Jetpack-Bibliothek für Anzeigendienste für die Einbindung datenschutzfreundlicher APIs verwenden, prüft die Bibliothek in der Funktion obtain() die Verfügbarkeit der angeforderten APIs. Die Funktion gibt null zurück, wenn die angeforderte API nicht auf dem Gerät verfügbar ist. Das folgende Beispiel zeigt, wie TopicsManager für die Topics API initialisiert wird. Ähnlich funktioniert es beim Zugriff auf andere datenschutzfreundliche APIs.

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

Wenn du die AdServices APIs direkt im Extension SDK verwendest, prüfe die AdServices Extensions-Version, die die AdServices APIs enthält, die du verwenden möchtest. In der API-Referenz kannst du die Version angeben, in der eine bestimmte AdServices API eingeführt wird. Die API-Referenz für die Klasse TopicsManager weist beispielsweise darauf hin, dass sie "In Ad Services Extensions 4 hinzugefügt" lautet. Mit den folgenden bedingten Prüfungen können Sie SDK-Erweiterungen validieren, die AdServices APIs enthalten.

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

Beschränkung des Zugriffs im Vordergrund

Aus Gründen der Transparenz ist der Zugriff auf die SDK Runtime und datenschutzfreundliche APIs auf Apps mit einer sichtbaren Activity bzw. mit einem RunningAppProcessInfo von IMPORTANCE_FOREGROUND beschränkt.