Entwicklerleitfaden für die Topics API

Wählen Sie beim Lesen der Dokumentation zur Privacy Sandbox für Android über die Schaltfläche Entwicklervorschau oder Beta die Programmversion aus, mit der Sie arbeiten. Die genaue Vorgehensweise kann variieren.

Feedback geben

Die Topics API leitet aus der App-Nutzung eines Nutzers grobe Signale zu seinen Interessen auf dem Gerät ab. Diese Signale, die als Themen bezeichnet werden, werden mit Werbetreibenden geteilt, um interessenbezogene Werbung zu unterstützen, ohne einzelne Nutzer appübergreifend zu erfassen. Weitere Informationen zur Topics API finden Sie im Designvorschlag. Wichtig:Klicken Sie auf die Schaltfläche „SDK Extensions Release“ oder „Developer Preview“, um die Programmversion auszuwählen, mit der Sie arbeiten. Die Anleitung kann variieren.

Einrichtung

Verwenden Sie das neueste Android Privacy Sandbox SDK, um die aktuelle Version der datenschutzfreundlichen APIs zu erhalten. Damit Ihre App die Topics API verwenden kann, müssen Sie in Ihrem Manifest eine Berechtigung hinzufügen und eine Anzeigendienste-Konfiguration erstellen:

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

Verweisen Sie im Element <application> Ihres Manifests auf eine Anzeigendienste-Konfiguration:

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

Geben Sie die Ad Services-XML-Ressource an, auf die im Manifest verwiesen wird, z. B. res/xml/ad_services_config.xml. Verwenden Sie entweder das Attribut allowAllToAccess, um Zugriff auf alle SDKs zu gewähren, oder das Attribut allowSdksToAccess, um Zugriff auf einzelne SDKs zu gewähren. Weitere Informationen zu Ad Services-Berechtigungen und SDK-Zugriffssteuerung

<ad-services-config>
    <topics allowAllToAccess="true" />
</ad-services-config>

Außerdem müssen Sie mit diesen ADB-Befehlen den Zugriff auf die Topics API (standardmäßig deaktiviert) aktivieren.

adb shell device_config put adservices ppapi_app_signature_allow_list \"*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

Die Hauptfunktion der Topics API liegt in der getTopics()-Methode innerhalb des TopicsManager-Objekts, wie in diesem Beispiel gezeigt:

Kotlin 

fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

Java 

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

Initialisieren Sie das TopicsManager-Objekt und die Parameter, die zum Empfangen von Themendaten erforderlich sind, um diese Methode zu verwenden. GetTopicsRequest übergibt die erforderlichen Informationen zum Abrufen von Topics API-Daten, einschließlich eines Flags, mit dem angegeben wird, ob der Aufrufer als Beobachter fungieren soll. Wenn er nicht als Beobachter fungiert, gibt der Aufruf getTopics ein Thema aus der vorherigen Epoche zurück, beeinflusst aber die Themendaten der folgenden Epoche nicht. Der OutcomeReceiver-Callback verarbeitet das Ergebnis asynchron. Beispiel:

Kotlin 

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val shouldRecordObservation = false
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation)
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, Exception>)
}
private var mCallback: OutcomeReceiver<GetTopicsResponse, java.lang.Exception> =
object : OutcomeReceiver<GetTopicsResponse, java.lang.Exception> {
    override fun onResult(result: GetTopicsResponse) {
        // handle successful result
        val topicsResult = result.topics
        for (i in topicsResult.indices) {
            Log.i("Topic", topicsResult[i].getTopicId().toString())
        }
        if (topicsResult.size == 0) {
            Log.i("Topic", "Returned Empty")
        }
    }
    override fun onError(error: java.lang.Exception) {
        // handle error
        Log.i("Topic", "Error, did not return successfully")
    }
}

Java 

public void TopicGetter() {
    @NonNull Context mContext = getBaseContext();
    TopicsManager mTopicsManager = mContext.getSystemService(TopicsManager.class);
    Executor mExecutor = Executors.newCachedThreadPool();
    boolean shouldRecordObservation = false;
    GetTopicsRequest.Builder mTopicsRequestBuilder = new GetTopicsRequest.Builder();
    mTopicsRequestBuilder.setAdsSdkName(getBaseContext().getPackageName());
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation);
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);
}
OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse, Exception>() {
    @Override
    public void onResult(@NonNull GetTopicsResponse result) {
        //Handle Successful Result
        List<Topic> topicsResult = result.getTopics();
        for (int i = 0; i < topicsResult.size(); i++) {
            Log.i("Topic", topicsResult.get(i).getTopicId().toString());
        }
        if (topicsResult.size() == 0) {
            Log.i("Topic", "Returned Empty");
        }
    }
    @Override
    public void onError(@NonNull Exception error) {
        // Handle error
        Log.i("Topic", "Experienced an error, and did not return successfully");
    }
};

Gruppe von Themen anfordern

Sobald die Einrichtung abgeschlossen ist, können Sie einen Aufruf starten, um ein GetTopicsResponse als Ergebnis der getTopics()-Methode zu erhalten:

Kotlin 

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

Java 

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);

Der obige Aufruf liefert eine Liste von Topics-Objekten mit ID-Werten, die Themen in der Open-Source-Taxonomie entsprechen, die für den Nutzer relevant sind, oder einen relevanten Fehler. Die Themen sehen in etwa so aus:

/Internet & Telecom/Text & Instant Messaging

In der Taxonomie finden Sie eine Liste der möglichen Themen, die zurückgegeben werden können. Diese Taxonomie ist Open Source. Änderungsvorschläge können über die Feedback-Schaltfläche oben auf dieser Seite eingereicht werden.

Testen

Die Topics API bietet relevante und aktuelle Themen basierend auf der App-Nutzung. Diese frühe Version bietet einen Vorgeschmack auf das API-Verhalten und wir werden die Qualität von Themen in zukünftigen Versionen verbessern. Für eine optimale Nutzung empfehlen wir eine Testumgebung mit mehreren Apps, in der Sie getTopics() aufrufen, um zu sehen, wie Themen ausgewählt werden. Das SDK Runtime and Privacy Preserving APIs Repository auf GitHub enthält eine Reihe einzelner Android Studio-Projekte, die Ihnen den Einstieg erleichtern, einschließlich Beispielen zum Initialisieren und Aufrufen der Topics API.

Die Themenberechnung erfolgt am Ende einer „Epoche“. Standardmäßig ist jede Epoche 7 Tage lang, aber Sie können dieses Intervall ändern, um ein Ergebnis zu erhalten. Der folgende Android Debug Bridge-Shell-Befehl verkürzt die Epochenlänge auf 5 Minuten:

adb shell device_config put adservices topics_epoch_job_period_ms 300000

Sie können den Wert topics_epoch_job_period_ms mit get bestätigen:

adb shell device_config get adservices topics_epoch_job_period_ms

Führen Sie den folgenden Befehl aus, um die Epochenberechnung manuell auszulösen:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

Zusätzlich zur Beispiel-App gibt es ein Colab, mit dem Sie verschiedene Kombinationen von App-Informationen mit dem Topics-Klassifikator testen können. Verwenden Sie dieses Colab, um die Arten von Ergebnissen anzusehen, die Ihre Anwendung wahrscheinlich erhält, wenn getTopics aufgerufen wird.

Beschränkungen

Eine Liste der aktuell verfügbaren Funktionen der Topics API finden Sie in den Versionshinweisen.

Fehler und Probleme melden

Dein Feedback ist wichtig für die Privacy Sandbox für Android. Melden Sie uns, wenn Sie Probleme feststellen, oder Ideen zur Verbesserung der Privacy Sandbox für Android haben.