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 Einrichtungsschritte 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 von Anzeigendiensten:Verweise im <application>-Element deines 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 Zugriff auf alle SDKs zu gewähren, oder das Attribut allowSdksToAccess, um Zugriff auf einzelne SDKs zu gewähren. Weitere Informationen zu Berechtigungen für Werbedienste und SDK-Zugriffssteuerung

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

  3. Melden Sie Ihre Anzeigentechnologie für die Privacy Sandbox an, um die Topics API in Ihrem SDK aufzurufen. Für lokale Tests können Sie die Themenregistrierungsüberprüfung mit den folgenden Befehlen deaktivieren:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. Aktivieren Sie den Zugriff auf die Topics API. Die Topics API ist standardmäßig deaktiviert. Sie müssen es 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 Hauptfunktionen der Topics API befinden sich in der Methode getTopics() innerhalb des Objekts TopicsManager, 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)

Wenn Sie diese Methode verwenden möchten, müssen Sie das TopicsManager-Objekt und die Parameter initialisieren, die zum Empfang von Themendaten erforderlich sind. GetTopicsRequest gibt die erforderlichen Informationen zum Abrufen von Topics API-Daten weiter, einschließlich eines Flags, das angibt, ob der Aufrufer als Beobachter agieren wird oder nicht. Wenn Sie nicht als Beobachter agieren, gibt der getTopics-Aufruf ein Thema aus der vorherigen Epoche zurück, hat aber keinen Einfluss auf die Themendaten für die nächste Epoche. Das Ergebnis wird asynchron über den OutcomeReceiver-Callback verarbeitet. 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 die Einrichtung abgeschlossen ist, können Sie einen Anruf starten, um eine 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);

Diese Aufrufe liefern 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

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

Test

Die Topics API liefert relevante und aktuelle Themen basierend auf der App-Nutzung. Diese frühe Version gibt einen ersten Eindruck von den API-Verhaltensweisen. Wir werden die Qualität der Themen in zukünftigen Releases weiter verbessern.

Für optimale Ergebnisse empfehlen wir eine Testumgebung mit mehreren Apps, in der Sie getTopics() aufrufen, um zu sehen, wie Themen ausgewählt werden. Das Repository für SDK-Laufzeit und APIs zur Wahrung der Privatsphäre auf GitHub enthält eine Reihe von einzelnen Android Studio-Projekten, die Ihnen den Einstieg erleichtern. Dazu gehören Beispiele, 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-Shell-Befehl 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 auch ein Colab, mit dem Sie verschiedene Kombinationen von App-Informationen mit dem Themenklassifikator testen können. In diesem Colab sehen Sie, welche Ergebnisse Ihre App wahrscheinlich beim Aufrufen von getTopics erhält.

Verschlüsselungsdetails

Durch die Einführung der Verschlüsselung wird bei Aufrufen von GetTopics() jetzt eine Antwort mit einer Liste von EncryptedTopic-Objekten generiert. Die Entschlüsselung dieser Ergebnisse führt zu einem Objekt mit demselben JSON-Format wie das vorherige Topic-Objekt.

Die Topics API unterstützt die einmalige Implementierung von HPKE (Hybrid Public Key Encryption). Der registrierte Aufrufer muss einen 32‑Bit-öffentlichen Schlüssel auf dem öffentlichen Verschlüsselungs-URL-Endpunkt hosten, 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 Registrierungsüberprüfung 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 in der Entwicklung befindlichen Funktionen für die Topics API finden Sie in den Versionshinweisen.

Fehler und Probleme melden

Ihr Feedback ist ein wichtiger Bestandteil der Privacy Sandbox für Android. Teilen Sie uns Probleme oder Verbesserungsvorschläge für die Privacy Sandbox für Android mit.

Next steps

Learn how users and developers can manage and customize the Topics API to suit user's preferences and needs.
Understand how Topics works on Android and lear about the core steps of the API flow.

See also

Check out our resources to better understand the Topics API on Android.