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 in die datenschutzfreundlichen APIs der Privacy Sandbox (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.

AdServices API-spezifische Berechtigungen deklarieren

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

Attribution Reporting API:

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

Attribution Reporting API (mit Debugging-Berichten):

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

Wenn Sie Debugging-Berichte über die Attribution Reporting API erhalten möchten, können Sie optional die Berechtigung „AD_ID“ hinzufügen:

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

Wenn in Ihrem Projekt Abhängigkeiten von Modulen oder SDKs bestehen, werden die erforderlichen Ad Services-Berechtigungen möglicherweise bereits in ihren Manifestdateien deklariert. Standardmäßig führt der Gradle-Build alle Manifestdateien in einer einzigen Manifestdatei zusammen, die in Ihre App gepackt ist. In der Ansicht Merged Manifest können Sie prüfen, ob die richtigen Berechtigungen verwendet werden.

Wenn Sie verhindern möchten, dass eine Berechtigung über Abhängigkeiten wie SDKs in Ihrer App zusammengeführt wird, fügen Sie die Knotenmarkierung remove für die jeweiligen Berechtigungen ein. Das folgende Beispiel zeigt, wie Sie die Zusammenführung der Berechtigung „Topics“ verhindern können.

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

API-spezifische Ad Services 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, genau steuern.

Hinweis :Die Konfiguration bestimmter Anzeigendienste ist optional und nur erforderlich, wenn ein App-Entwickler den Zugriff auf eine API ändern oder einschränken möchte, da der gesamte Zugriff standardmäßig gewährt wird.

Geben Sie in Ihrem Manifest das Attribut adservicesConfig 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 die Anzeigendienste an, auf die im Manifest verwiesen wird, z. B. res/xml/ad_services_config.xml. Setzen Sie für jede datenschutzfreundliche API, die für Ihre App (oder das eingebettete SDK) gilt, das Attribut allowAllToAccess auf true, um allen Aufrufern Zugriff zu gewähren.

Alternativ können Sie das Attribut allowAdPartnersToAccess verwenden, um für jede Anzeigentechnologie detailgenauen API-Zugriff zu gewähren. Sie müssen eine Liste der im Rahmen der Registrierung abgerufenen Konto-IDs für die Entwicklerregistrierung bereitstellen. Wenn das Attribut allowAllToAccess auf true gesetzt ist, hat dieses Attribut Vorrang vor allen im Attribut allowAdPartnersToAccess angegebenen Registrierungskonto-IDs.

Hinweis: Damit Sie auf die Privacy Sandbox APIs im aktuellen AdServices SDK Extension-Release und in der Entwicklervorschau zugreifen können, müssen Sie die Registrierung abschließen.

Werbetechnologie-Plattformen müssen außerdem dafür sorgen, dass ihre App-Clients den erforderlichen Zugriff auf die erforderlichen datenschutzfreundlichen APIs in der Konfiguration der Werbedienste gewähren.

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

Das folgende Beispiel zeigt, wie Sie den umfassenden Zugriff festlegen, damit jeder Registrierungskonto-ID Zugriff auf alle datenschutzfreundlichen APIs gewährt wird:

<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 für bestimmte Konto-IDs für die Registrierung einen detaillierten Zugriff auf jede datenschutzfreundliche API festlegen:

<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 festgelegten 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. Mit dieser Bibliothek können Sie Ihre App von Details auf Plattformebene abstrahieren und die Einbindung datenschutzfreundlicher APIs vereinfachen.

1. Fügen Sie Ihrem Projekt ein Maven-Repository hinzu.
2. Sie müssen in der Datei build.gradle für Ihre App oder Ihr Modul die Abhängigkeiten der Jetpack-Bibliothek von Ads-adservices deklarieren.
3. Verwenden Sie APIs aus den androidx.privacysandbox.ads.adservices.*-Paketen.
4. Die Jetpack-Bibliothek für ads-adservices bietet integrierte Unterstützung für Kotlin-Koroutinen. Möglicherweise müssen Sie die entsprechenden Lebenszyklusabhängigen Abhängigkeiten einbinden, die für Ihr Projekt geeignet sind, um Koroutinebereiche zu verwalten.

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

Wenn du die Jetpack-Bibliothek für Anzeigendienste zur Einbindung in datenschutzfreundliche APIs verwendest, prüft sie die Verfügbarkeit der angeforderten APIs in der Funktion obtain(). Die Funktion gibt null zurück, wenn die angeforderte API auf dem Gerät nicht verfügbar ist. Das folgende Beispiel zeigt, wie TopicsManager für die Topics API initialisiert wird. Ähnlich funktioniert der 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 Sie die AdServices APIs direkt im Extension SDK verwenden, prüfen Sie die AdServices Extensions-Version, die die AdServices APIs enthält, die Sie verwenden möchten. In der API-Referenz können Sie die Version angeben, in der eine bestimmte AdServices API eingeführt wird. Beispielsweise zeigt die API-Referenz für die Klasse TopicsManager an, dass sie in Ad Services Extensions 4 hinzugefügt wurde. 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.
...
}

Zugriffsbeschränkung im Vordergrund

Aus Gründen der Transparenz ist der Zugriff auf die SDK Runtime und datenschutzfreundlichen APIs auf Apps mit einer sichtbaren Aktivität oder mit einem RunningAppProcessInfo von IMPORTANCE_FOREGROUND beschränkt.