Przewodnik dla programistów interfejsu Topics API

Podczas czytania dokumentacji Piaskownicy prywatności na Androida wybierz odpowiednią wersję programu, korzystając z przycisku Podgląd dla programistów lub Beta. Instrukcje mogą się różnić.

Przesłać opinię

Interfejs Topics API ustala przybliżone sygnały dotyczące zainteresowań na urządzeniu na podstawie tego, jak użytkownik korzysta z aplikacji. Sygnały te, nazywane tematami, są udostępniane reklamodawcom, aby umożliwić wyświetlanie reklam opartych na zainteresowaniach bez śledzenia poszczególnych użytkowników w aplikacjach. Więcej informacji o interfejsie Topics API znajdziesz w ofercie pakietowej. Ważne: kliknij przycisk Wersja rozszerzenia pakietu SDK lub przycisk podglądu dewelopera, aby wybrać wersję programu, nad którą pracujesz, bo instrukcje mogą się różnić.

Konfiguracja

Użyj najnowszego pakietu SDK Piaskownicy prywatności na Androida, aby korzystać z najnowszej wersji interfejsów API chroniących prywatność. Aby aplikacja mogła korzystać z interfejsu Topics API, musisz dodać odpowiednie uprawnienia i utworzyć w pliku manifestu konfigurację usług reklamowych:

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

Odwołaj się do konfiguracji usług reklamowych w elemencie <application> pliku manifestu:

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

Określ zasób XML usług reklamowych, do którego odwołuje się plik manifestu, np. res/xml/ad_services_config.xml. Użyj atrybutu allowAllToAccess, aby przyznać dostęp do wszystkich pakietów SDK, lub atrybutu allowSdksToAccess, aby przyznać dostęp do poszczególnych pakietów SDK. Dowiedz się więcej o uprawnieniach w usługach reklamowych i kontroli dostępu do pakietów SDK.

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

Dodatkowo za pomocą tych poleceń adb musisz włączyć dostęp do interfejsu Topics API (domyślnie wyłączonego).

adb shell device_config put adservices ppapi_app_signature_allow_list \"*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

Główna funkcjonalność interfejsu Topics API ma swoje działanie getTopics() w obiekcie TopicsManager, jak w tym przykładzie:

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)

Aby użyć tej metody, zainicjuj obiekt TopicsManager i parametry niezbędne do odbierania danych dotyczących tematów. GetTopicsRequest przekazuje informacje potrzebne do pobrania danych interfejsu Topics API, w tym flagę wskazującą, czy element wywołujący będzie działać w roli obserwatora. Jeśli nie występujesz jako obserwator, wywołanie getTopics zwraca temat z poprzedniej epoki, ale nie wpływa na dane dotyczące tematów dla kolejnego. Wywołanie zwrotne OutcomeReceiver obsługuje wynik asynchronicznie. Na przykład:

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

Poproś o zestaw tematów

Po zakończeniu konfiguracji możesz wywołać metodę getTopics(), aby otrzymać GetTopicsResponse:

Kotlin 

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

Java 

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

Powyższe wywołanie wyświetli listę obiektów Topics zawierających wartości identyfikatorów, które odpowiadają tematom w taksonomii open source, które są istotne dla użytkownika, lub wyświetli się odpowiedni błąd. Tematy będą podobne do tego przykładu:

/Internet & Telecom/Text & Instant Messaging

Listę tematów, które można zwrócić, znajdziesz w mapie kategorii. Ta taksonomia jest oprogramowaniem typu open source, a sugerowane zmiany można wprowadzić za pomocą przycisku przesyłania opinii u góry strony.

Testowanie

Interfejs Topics API dostarcza trafne i aktualne tematy na podstawie danych o korzystaniu z aplikacji. Ta wczesna wersja zawiera podgląd sposobu działania interfejsu API, dzięki czemu z kolejnych wersji będziemy ulepszać jakość tematów. Aby w pełni wykorzystać możliwości usługi, zalecamy środowisko testowe z wieloma aplikacjami, w którym wywołujesz funkcję getTopics() w celu sprawdzenia, jak wybierane są tematy. Repozytorium interfejsów API środowiska wykonawczego i zachowania prywatności na GitHubie zawiera zestaw poszczególnych projektów Android Studio, które ułatwiają rozpoczęcie pracy, w tym przykłady, które pokazują, jak zainicjować i wywołać interfejs Topics API.

Obliczanie tematów odbywa się na końcu „epoki”. Domyślnie każda epoka trwa 7 dni, ale możesz zmienić ten interwał, aby otrzymać takie wyniki. To polecenie powłoki Android Debug Bridge skraca czas trwania epoki do 5 minut:

adb shell device_config put adservices topics_epoch_job_period_ms 300000

Wartość topics_epoch_job_period_ms możesz potwierdzić za pomocą get:

adb shell device_config get adservices topics_epoch_job_period_ms

Aby ręcznie aktywować obliczenie epoki, uruchom to polecenie:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

Oprócz przykładowej aplikacji dostępna jest też narzędzie Colab, za pomocą którego możesz testować różne kombinacje informacji o aplikacji w porównaniu z klasyfikatorem tematów. Skorzystaj z tej współpracy, aby zobaczyć rodzaje wyników, jakie może uzyskać Twoja aplikacja przy wywoływaniu funkcji getTopics.

Ograniczenia

Listę bieżących funkcji interfejsu Topics API znajdziesz w informacjach o wersji.

Zgłaszanie błędów i problemów

Twoja opinia jest kluczowym elementem Piaskownicy prywatności na Androida. Daj nam znać o znalezionych problemach lub pomysłach na ulepszenie Piaskownicy prywatności na Androidzie.