Topics API unter Android implementieren

Einrichtung

Um die Topics API zu implementieren, müssen Sie zuerst Ihre Entwicklungsumgebung einrichten. Führen Sie dazu die folgenden Schritte aus:

  1. Verwenden Sie das neueste Android Privacy Sandbox SDK, um die aktuellste Version der datenschutzfreundlichen APIs zu erhalten.

  2. Fügen Sie Ihrem Manifest Folgendes hinzu:

    • Berechtigung:Fügen Sie die Berechtigung ACCESS_ADSERVICES_TOPICS hinzu, damit Ihre App auf die Topics API zugreifen kann:

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

    • Konfiguration der Anzeigendienste: Verweisen Sie im Element <application> Ihres Manifests auf eine Konfigurationsdatei für Anzeigendienste.

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

      Geben Sie die XML-Ressource für Anzeigendienste an, auf die im Manifest verwiesen wird, z. B. res/xml/ad_services_config.xml. Verwenden Sie entweder das Attribut allowAllToAccess, um allen SDKs Zugriff zu gewähren, oder das Attribut allowSdksToAccess, um einzelnen SDKs Zugriff zu gewähren. Weitere Informationen zu Berechtigungen für Anzeigendienste und zur SDK-Zugriffssteuerung.

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

  3. Registrieren Sie Ihre AdTech bei der Privacy Sandbox, um die Topics API in Ihrem SDK aufzurufen. Für lokale Tests können Sie die Überprüfung der Topics-Registrierung mit den folgenden Befehlen deaktivieren:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. Aktivieren Sie den Zugriff auf die Topics API. Standardmäßig ist die Topics API deaktiviert. Sie müssen sie mit ADB-Befehlen aktivieren:

    adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  5. Beginnen Sie mit der Implementierung, indem Sie unsere Java- oder Kotlin-Version der Beispiel-App forken, um sich mit dem Abrufen von Themen auf einem Gerät vertraut zu machen.

Themen anfordern

Die Hauptfunktion der Topics API befindet sich in der getTopics() Methode im TopicsManager Objekt, 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)

Um diese Methode zu verwenden, initialisieren Sie das Objekt TopicsManager und die Parameter, die zum Empfangen von Themendaten erforderlich sind. GetTopicsRequest übergibt die erforderlichen Informationen zum Abrufen von Topics API-Daten, einschließlich eines Flags, das angibt, ob der Aufrufer als Beobachter fungiert. Wenn Sie nicht als Beobachter fungieren, gibt der Aufruf getTopics ein Thema aus der vorherigen Epoche zurück, hat aber keinen Einfluss auf die Themendaten für die nächste Epoche. 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");
    }
};

Sobald Ihre Einrichtung abgeschlossen ist, können Sie einen Aufruf ausführen, um GetTopicsResponse als Ergebnis der Methode getTopics() zu erhalten:

Kotlin 

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

Java 

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

Dieser 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 entsprechenden Fehler. Die Themen sehen in etwa so aus:

/Internet & Telecom/Text & Instant Messaging

Eine Liste der möglichen Themen, die zurückgegeben werden können, finden Sie in der Taxonomie. Diese Taxonomie ist Open Source. Vorschläge für Änderungen können Sie über die Feedback-Schaltfläche oben auf dieser Seite einreichen.

Test

Die Topics API liefert relevante und aktuelle Themen basierend auf der App-Nutzung. Diese frühe Version bietet eine Vorschau des API-Verhaltens. Wir werden die Qualität der Themen in zukünftigen Versionen verbessern.

Um alle Funktionen nutzen zu können, empfehlen wir eine Testumgebung mit mehreren Apps, in der Sie getTopics() aufrufen, um zu sehen, wie Themen ausgewählt werden. Das GitHub-Repository für die SDK-Laufzeit und datenschutzfreundliche APIs enthält eine Reihe einzelner Android Studio-Projekte, die Ihnen den Einstieg erleichtern, einschließlich Beispielen, die zeigen, wie Sie die Topics API initialisieren und aufrufen.

Die Themenberechnung erfolgt am Ende einer Epoche. Standardmäßig dauert jede Epoche 7 Tage. Sie können dieses Intervall jedoch ändern, um ein Ergebnis zu erhalten. Mit diesem Android Debug Bridge Shellbefehl wird die Epochenlänge auf 5 Minuten verkürzt:

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

Neben der Beispiel-App gibt es ein Colab, mit dem Sie verschiedene Kombinationen von App-Informationen mit dem Themen Klassifikator testen können. In diesem Colab können Sie sehen, welche Arten von Ergebnissen Ihre App wahrscheinlich erhält, wenn Sie getTopics aufruft.

Verschlüsselungsdetails

Mit der Einführung der Verschlüsselung generieren Aufrufe von GetTopics() jetzt eine Antwort mit einer Liste von EncryptedTopic-Objekten. Wenn Sie diese Ergebnisse entschlüsseln, erhalten Sie ein Objekt mit demselben JSON-Format wie das vorherige Topic Objekt.

Die Topics API unterstützt die einmalige Implementierung von HPKE (Hybrid Public Key Encryption). Wir erwarten, dass der registrierte Aufrufer einen 32-Bit-öffentlichen Schlüssel am öffentlichen Verschlüsselungs-URL-Endpunkt hostet, der bei der Registrierung angegeben wurde. Diese Schlüssel müssen Base64-codiert sein.

EncryptedTopic-Objekte haben drei Felder. Die Liste der zurückgegebenen Themen kann mit dem entsprechenden privaten Schlüssel für den öffentlichen Schlüssel abgerufen werden.

Zu Entwicklungszwecken können Sie die Verschlüsselung der Topics API testen, indem Sie die Überprüfung der Registrierung deaktivieren. Dadurch wird die API gezwungen, den öffentlichen Testschlüssel zum Verschlüsseln Ihrer Antworten zu verwenden. Sie können die verschlüsselten Themen mit dem entsprechenden privaten Schlüssel entschlüsseln.

Beschränkungen

Eine Liste der Funktionen, die für die Topics API in Arbeit sind, finden Sie in den Versionshinweisen.

Fehler und Probleme melden

Ihr Feedback ist ein wichtiger Bestandteil der Privacy Sandbox für Android. Teilen Sie uns alle Probleme mit, die Sie finden, oder Ideen zur Verbesserung der Privacy Sandbox für Android.

Nächste Schritte

Hier erfahren Sie, wie Nutzer und Entwickler die Topics API verwalten und an die Vorlieben und Anforderungen der Nutzer anpassen können.
Informationen zur Funktionsweise von Topics auf Android-Geräten und zu den wichtigsten Schritten des API-Ablaufs

Weitere Informationen

In unseren Ressourcen finden Sie weitere Informationen zur Topics API für Android.