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.
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.
Persönliche Empfehlungen
- Hinweis: Der Linktext wird angezeigt, wenn JavaScript deaktiviert ist.
- Entwicklerleitfaden für die Protected Audience API auf Android
- Versionshinweise
- AdServices konfigurieren {:#configure-adservices}