Entwicklerleitfaden für die Topics API

Beim Lesen der Privacy Sandbox für Android Dokumentation auswählen, klicken Sie auf die Schaltfläche Vorschau für Entwickler oder Beta, um Programmversion, mit der Sie arbeiten, da die Anleitung variieren kann.

Feedback geben

Einrichtung

Verwende das neueste Android Privacy Sandbox SDK, um die App auf dem neuesten Stand zu halten. Version der datenschutzfreundlichen APIs. Sie müssen eine Berechtigung und Erstellen Sie in Ihrem Manifest eine Konfiguration für Anzeigendienste, damit Ihre App die Funktion Topics API:

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

Verweisen Sie im <application>-Element Ihrer Manifest:

<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, um 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 Anzeigendienste und zum SDK-Zugriff steuern können.

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

Außerdem müssen Sie den Zugriff auf die Topics API aktivieren (deaktiviert durch Standard) mit diesen ADB-Befehlen.

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 befindet sich in der Methode getTopics() innerhalb des TopicsManager-Objekts, wie hier gezeigt. Beispiel:

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 Pässe erforderlich um Daten der Topics API abzurufen, einschließlich eines Flags, das angibt, ob der Aufrufer ob sie als Beobachter fungieren 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. Der OutcomeReceiver-Callback und verarbeitet das Ergebnis asynchron. Beispiel:

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");
    }
};

Themengruppe anfordern

Sobald die Einrichtung abgeschlossen ist, kannst du anrufen, um ein GetTopicsResponse zu erhalten als Ergebnis der Methode getTopics():

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

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

Der obige Aufruf liefert eine Liste von Topics-Objekten mit ID-Werten die den Themen in der Open-Source-Taxonomie entsprechen, Fehler oder einen relevanten Fehler. Die Themen sehen in etwa so aus:

/Internet & Telecom/Text & Instant Messaging

In der Taxonomie finden Sie eine Liste möglicher Themen, auf die zurückgegeben. Diese Taxonomie ist Open Source und Änderungsvorschläge können über über die Feedback-Schaltfläche oben auf dieser Seite.

Test

Die Topics API bietet relevante und aktuelle Themen basierend auf der App-Nutzung. So früh gibt eine Vorschau auf das API-Verhalten, und wir werden die Qualität der in zukünftigen Releases. Für eine optimale Nutzung empfehlen wir eine Testumgebung mit mehreren Apps, bei denen du getTopics() anrufst, um zu sehen, wie Themen ausgewählt werden Das SDK Das Repository für Runtime and Privacy Preserving APIs auf GitHub enthält eine Reihe von einzelne Android Studio-Projekte, um Ihnen den Einstieg zu erleichtern, einschließlich Beispielen wie die Topics API initialisiert und aufgerufen wird.

Die Berechnung von 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. Dieses Der Shell-Befehl Android Debug Bridge verkürzt die Epoche auf 5 Minuten:

adb shell device_config put adservices topics_epoch_job_period_ms 300000

Sie können den topics_epoch_job_period_ms-Wert 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.

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.