Wdrażanie interfejsu Topics API na Androidzie

Konfiguracja

Aby zaimplementować interfejs Topics API, musisz najpierw skonfigurować środowisko programistyczne. Wykonaj te czynności:

  1. Użyj najnowszego pakietu SDK Piaskownicy prywatności Androida, aby uzyskać najbardziej aktualną wersję chroniących prywatność interfejsów API.

  2. Dodaj do pliku manifestu te elementy:

    • Uprawnienie: dodaj uprawnienie ACCESS_ADSERVICES_TOPICS, aby umożliwić aplikacji dostęp do interfejsu Topics API.

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

    • Konfiguracja usług reklamowych: w elemencie <application> w pliku manifestu dodaj odwołanie do pliku konfiguracyjnego usług reklamowych.

      <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łujesz się w pliku manifestu, np. res/xml/ad_services_config.xml. Aby przyznać dostęp do wszystkich pakietów SDK, użyj atrybutu allowAllToAccess, a aby przyznać dostęp do poszczególnych pakietów SDK, użyj atrybutu allowSdksToAccess. Więcej informacji o uprawnieniach usług reklamowych i kontroli dostępu do pakietu SDK.

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

  3. Zarejestruj technologię reklamową w Piaskownicy prywatności, aby wywoływać interfejs Topics API w pakiecie SDK. Aby przeprowadzić testy lokalne, możesz wyłączyć sprawdzanie rejestracji w interfejsie Topics API za pomocą tych poleceń:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. Włącz dostęp do interfejsu Topics API. Domyślnie interfejs Topics API jest wyłączony. Musisz go włączyć za pomocą poleceń ADB:

    adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  5. Zacznij implementację, tworząc fork wersji przykładowej aplikacji w języku Java lub Kotlin, aby zapoznać się z tym, jak pobierać tematy na urządzeniu.

Wysyłanie prośby o zestaw tematów

Główna funkcja interfejsu Topics API znajduje się w metodzie getTopics() w obiekcie TopicsManager, jak pokazano 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 otrzymywania danych o tematach. GetTopicsRequest przekazuje informacje potrzebne do pobrania danych z interfejsu Topics API, w tym flagę wskazującą, czy wywołujący będzie działać jako obserwator. Jeśli nie działa jako obserwator, wywołanie getTopics zwraca temat z poprzedniej epoki, ale nie wpłynie na dane o tematach w następnej epoce. Wywołanie zwrotne obsługuje wynik asynchronicznie.OutcomeReceiver 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");
    }
};

Gdy konfiguracja będzie gotowa, 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);

To wywołanie zwróci listę obiektów Topics zawierających wartości identyfikatorów odpowiadające tematom w taksonomii open source taxonomy, które są istotne dla użytkownika, lub odpowiedni błąd. Tematy będą podobne do tych w tym przykładzie:

/Internet & Telecom/Text & Instant Messaging

Listę możliwych tematów, które mogą zostać zwrócone, znajdziesz w taksonomii. Ta taksonomia jest dostępna na licencji open source, a sugerowane zmiany można zgłaszać za pomocą przycisku opinii u góry tej strony.

Testowanie

Interfejs Topics API udostępnia odpowiednie i aktualne tematy na podstawie korzystania z aplikacji. Ta wczesna wersja zawiera podgląd zachowań interfejsu API, a w przyszłych wersjach poprawimy jakość tematów.

Aby uzyskać jak najlepsze wrażenia, zalecamy korzystanie ze środowiska testowego z wieloma aplikacjami, w którym wywołujesz metodę getTopics(), aby sprawdzić, jak wybierane są tematy. Repozytorium środowiska wykonawczego SDK i chroniących prywatność interfejsów API na GitHubie zawiera zestaw pojedynczych projektów Android Studio, które pomogą Ci zacząć, w tym przykłady pokazujące, 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 uzyskać wynik. To polecenie powłoki Android Debug Bridge skraca długość epoki do 5 minut:

adb shell device_config put adservices topics_epoch_job_period_ms 300000

Możesz potwierdzić wartość topics_epoch_job_period_ms za pomocą polecenia get:

adb shell device_config get adservices topics_epoch_job_period_ms

Aby ręcznie uruchomić obliczanie epoki, wykonaj to polecenie:

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

Oprócz korzystania z przykładowej aplikacji możesz użyć Colaba, aby przetestować różne kombinacje informacji o aplikacji w klasyfikatorze tematów. Użyj tego Colaba, aby zobaczyć, jakie wyniki prawdopodobnie otrzyma Twoja aplikacja po wywołaniu metody getTopics.

Szczegóły szyfrowania

Wraz z wprowadzeniem szyfrowania wywołania metody GetTopics() będą teraz generować odpowiedź z listą obiektów EncryptedTopic. Odszyfrowanie tych wyników spowoduje utworzenie obiektu w tym samym formacie JSON co poprzedni Topic obiekt.

Interfejs Topics API obsługuje jednorazową implementację HPKE (Hybrid Public Key Encryption). Oczekujemy, że zarejestrowany wywołujący będzie hostować 32-bitowy klucz publiczny w punkcie końcowym publicznego adresu URL szyfrowania podanym podczas rejestracji. Te klucze powinny być zakodowane w formacie Base64.

Obiekty EncryptedTopic mają 3 pola. Listę zwróconych tematów można uzyskać za pomocą odpowiedniego klucza prywatnego do klucza publicznego.

Na potrzeby programowania możesz przetestować szyfrowanie w interfejsie Topics API, wyłączając sprawdzanie rejestracji. Spowoduje to, że interfejs API będzie używać testowego klucza publicznego do szyfrowania odpowiedzi. Zaszyfrowane tematy możesz odszyfrować za pomocą odpowiedniego klucza prywatnego.

Ograniczenia

Listę funkcji, nad którymi pracujemy w przypadku interfejsu Topics API, znajdziesz w informacjach o wersji.

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

Twoja opinia jest ważną częścią Piaskownicy prywatności na Androida. Poinformuj nas o wszelkich problemach lub pomysłach na ulepszenie Piaskownicy prywatności na Androida.

Dalsze kroki

Dowiedz się, jak użytkownicy i deweloperzy mogą zarządzać interfejsem Topics API i dostosowywać go do swoich potrzeb i preferencji.
Dowiedz się, jak działa interfejs Topics na Androidzie i poznaj podstawowe kroki procesu interfejsu API.

Zobacz też

Zapoznaj się z naszymi materiałami, aby lepiej zrozumieć interfejs Topics API na Androida.