Topics API unter Android implementieren

Einrichtung

Zum Implementieren der Topics API müssen Sie zuerst Ihre Entwicklungsumgebung einrichten. um die folgenden Einrichtungsschritte auszuführen:

  1. Verwende das neueste Android Privacy Sandbox SDK, um die App auf dem neuesten Stand zu halten. Version der datenschutzfreundlichen APIs.

  2. Füge deinem 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:Im <application>-Element Ihres Manifests können Sie auf eine Konfigurationsdatei für Anzeigendienste verweisen.

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

      Geben Sie die XML-Ressource von Ad Services an, auf die im Manifest verwiesen wird, z. B.: res/xml/ad_services_config.xml Verwenden Sie entweder das Attribut allowAllToAccess für Zugriff auf alle SDKs zu gewähren oder das Attribut allowSdksToAccess, um Zugriff zu gewähren bis hin zu individuellen SDKs. Weitere Informationen zu Berechtigungen für Werbedienste und zur SDK-Zugriffssteuerung

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

  3. Registrieren Sie Ihre Anzeigentechnologie bei der Privacy Sandbox, um die Topics API in Ihrem SDK aufzurufen. Für lokale Tests können Sie die Topics-Registrierungsprü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 sie mithilfe von 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 abspalten, 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 Java 
fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

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

Um diese Methode zu verwenden, initialisieren Sie das TopicsManager-Objekt und die Parameter die für den 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, Der getTopics-Aufruf gibt ein Thema aus der vorherigen Epoche zurück, die Themendaten für die folgende. Die OutcomeReceiver verarbeitet das Ergebnis asynchron. Beispiel:

Kotlin Java 
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")
    }
}

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 Java 
mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

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 bietet 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. Die SDK-Laufzeit und datenschutzfreundliches API-Repository auf GitHub enthält eine Reihe einzelner Android Studio-Projekte, mit denen Sie einschließlich Beispielen, die zeigen, wie die Topics API initialisiert und aufgerufen wird.

Die Berechnung der Themen erfolgt am Ende einer Epoche. Standardmäßig werden alle Epoche ist 7 Tage lang, aber Sie können dieses Intervall ä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

Zusätzlich zur Beispiel-App gibt es ein Colab, das können Sie verschiedene App-Informationen-Kombinationen anhand der Themen testen, Klassifikator. Verwenden Sie dieses Colab, um die Ergebnisse zu sehen, die Ihre App wahrscheinlich liefert erhalten, wenn getTopics aufgerufen wird.

Verschlüsselungsdetails

Mit der Einführung der Verschlüsselung generieren Aufrufe an GetTopics() mit einer Liste von EncryptedTopic-Objekten. 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 würde die API gezwungen werden, den öffentlichen Testschlüssel für durch die Verschlüsselung Ihrer Antworten. Sie können die verschlüsselten Themen mit der für den entsprechenden privaten Schlüssel.

Beschränkungen

Eine Liste der laufenden Funktionen für die Topics API finden Sie in der Versionshinweise.

Fehler und Probleme melden

Ihr Feedback ist ein wichtiger Teil der Privacy Sandbox für Android. Geben Sie uns Feedback. von Problemen, 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 Anforderungen und Bedürfnisse der Nutzer anpassen können.
Hier erfahren Sie, wie Topics auf Android-Geräten funktioniert und welche Schritte beim API-Ablauf entscheidend sind.

Weitere Informationen

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