Einrichtung
Wenn Sie die Topics API implementieren möchten, müssen Sie zuerst Ihre Entwicklungsumgebung einrichten. Führen Sie dazu die folgenden Einrichtungsschritte aus:
Verwenden Sie das aktuelle Android Privacy Sandbox SDK, um die aktuelle Version der datenschutzfreundlichen APIs zu erhalten.
Fügen Sie dem Manifest Folgendes hinzu:
Berechtigung:Fügen Sie die Berechtigung
ACCESS_ADSERVICES_TOPICShinzu, damit Ihre App auf die Topics API zugreifen kann:<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />Konfiguration der Anzeigen-Services:Verweisen Sie im
<application>-Element Ihres Manifests auf eine Konfigurationsdatei für Anzeigen-Services.<property android:name="android.adservices.AD_SERVICES_CONFIG" android:resource="@xml/ad_services_config" />Geben Sie die im Manifest referenzierte XML-Ressource für Anzeigendienste an, z. B.
res/xml/ad_services_config.xml. Verwenden Sie entweder das AttributallowAllToAccess, um Zugriff auf alle SDKs zu gewähren, oder das AttributallowSdksToAccess, 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>
Registrieren Sie Ihre Anzeigentechnologie für die Privacy Sandbox, um die Topics API in Ihrem SDK aufzurufen. Für lokale Tests können Sie die Überprüfung der Anmeldung für Topics mit den folgenden Befehlen deaktivieren:
adb shell setprop debug.adservices.disable_topics_enrollment_check trueZugriff auf die Topics API aktivieren Die Topics API ist standardmäßig 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 trueBeginnen Sie mit der Implementierung, indem Sie unsere Java- oder Kotlin-Version der Beispiel-App forken, um sich damit vertraut zu machen, wie Sie Themen auf einem Gerät abrufen.
Themen vorschlagen
Die primäre Funktion der Topics API befindet sich in der Methode getTopics() im Objekt 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)
Um diese Methode zu verwenden, müssen Sie das TopicsManager-Objekt und die Parameter initialisieren, die zum Empfangen von Themen-Daten erforderlich sind. GetTopicsRequest übergibt die erforderlichen Informationen zum Abrufen von Topics API-Daten, einschließlich eines Flags, das angibt, ob der Aufrufer als Beobachter fungieren soll oder nicht. Wenn nicht als Beobachter fungiert, gibt der getTopics-Aufruf ein Thema aus der vorherigen Epoche zurück, hat aber keinen Einfluss auf die Themadaten für die nächste Epoche. Der Callback OutcomeReceiver 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 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);
Dieser Aufruf gibt eine Liste von „Topics“-Objekten mit ID-Werten zurück, die den Themen in der Open-Source-Taxonomie entsprechen, die für den Nutzer relevant sind, oder einen relevanten Fehler. Die Themen sehen 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 ü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 bietet eine Vorschau des API-Verhaltens. Wir werden die Qualität der Themen in zukünftigen Releases 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 SDK Runtime and Privacy Preserving APIs Repository auf GitHub enthält eine Reihe von einzelnen Android Studio-Projekten, die Ihnen den Einstieg erleichtern. Dazu gehören auch Beispiele, die zeigen, wie die Topics API initialisiert und aufgerufen wird.
Die Berechnung der Themen 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 300000Sie können den Wert topics_epoch_job_period_ms mit get bestätigen:
adb shell device_config get adservices topics_epoch_job_period_msFühren Sie den folgenden Befehl aus, um die Epochenberechnung manuell auszulösen:
adb shell cmd jobscheduler run -f com.google.android.adservices.api 2Neben der Beispiel-App gibt es ein Colab, mit dem Sie verschiedene Kombinationen von App-Informationen mit dem Themen-Klassifizierer testen können. In diesem Colab können Sie sehen, welche Arten von Ergebnissen Ihre App wahrscheinlich erhält, wenn Sie getTopics aufrufen.
Verschlüsselungsdetails
Mit der Einführung der Verschlüsselung wird bei Aufrufen von GetTopics() jetzt eine Antwort mit einer Liste von EncryptedTopic-Objekten generiert. Durch das Entschlüsseln dieser Ergebnisse wird ein Objekt mit demselben JSON-Format wie das vorherige Topic-Objekt erstellt.
Die Topics API unterstützt die einmalige Implementierung von HPKE (Hybrid Public Key Encryption). Wir erwarten, dass der registrierte Anrufer 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 Registrierungsprüfung deaktivieren. Dadurch würde 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 laufenden 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 alle Probleme mit, die Sie finden, oder Ideen zur Verbesserung der Privacy Sandbox für Android.
Nächste Schritte
Kontrolle und Transparenz
Topics auf Android-Geräten
Weitere Informationen
In unseren Ressourcen finden Sie weitere Informationen zur Topics API für Android.
- Beispiel-Apps, Videos zu Gruppenarbeiten und Schritt-für-Schritt-Anleitungen
- Sehen Sie sich an, wie Nutzer und Entwickler die API steuern können.
- In den Supportressourcen kannst du Fragen stellen, mit anderen Nutzern interagieren und Feedback geben.