Wdrażanie interfejsu Topics API na Androidzie

Konfiguracja

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

  1. Użyj najnowszej wersji pakietu SDK Piaskownicy prywatności na Androida, aby uzyskać najnowszą wersję interfejsów API zapewniających ochronę prywatności.

  2. Dodaj do pliku manifestu:

    • Uprawnienia: 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 pliku manifestu w elemencie <application> odwołuj się do pliku konfiguracji usług reklamowych.

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

      Wskazać zasób XML Usług reklamowych, na który wskazuje manifest, 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 usług reklamowych i kontroli dostępu do pakietu SDK.

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

  3. Zarejestruj swoją technologię reklamową w Piaskownicy prywatności, aby wywoływać interfejs Topics API w swoim pakiecie SDK. Aby przeprowadzić testowanie lokalnie, możesz wyłączyć sprawdzanie rejestracji w programie Topics 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. Rozpocznij implementację, tworząc wersję przykładowej aplikacji w języku Java lub Kotlin, aby zapoznać się z metodami pobierania tematów na urządzeniu.

Prośba o zestaw tematów

Podstawowa funkcjonalność interfejsu Topics API znajduje się w metodie 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 potrzebne do odbierania danych tematów. GetTopicsRequest przekazuje potrzebne informacje do pobrania danych z interfejsu Topics API, w tym flagę wskazującą, czy wywołujący ma działać jako obserwator. Jeśli nie działasz jako obserwator, wywołanie getTopics zwraca temat z poprzedniej epoki, ale nie wpływa na dane dotyczące tematów w następnej epoce. Wywołanie OutcomeReceiver asynchronicznie obsługuje wynik. 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 zostanie zakończona, możesz zadzwonić, aby otrzymać GetTopicsResponse w ramach metody getTopics():

Kotlin 

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

Java 

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

Ten wywołanie zwróci listę obiektów Topics zawierających wartości identyfikatorów odpowiadających tematom w mapie kategorii open source, które są istotne dla użytkownika, lub odpowiedni błąd. Tematy będą wyglądać mniej więcej tak:

/Internet & Telecom/Text & Instant Messaging

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

Testowanie

Interfejs Topics API dostarcza aktualnych tematów na podstawie korzystania z aplikacji. Ta wstępna wersja zawiera podgląd zachowania interfejsu API. W przyszłych wersjach poprawimy jakość tematów.

Aby uzyskać jak najwięcej informacji, zalecamy środowisko testowe z kilkoma aplikacjami, w których wywołujesz funkcję getTopics(), aby zobaczyć, jak są wybierane tematy. Repozytorium interfejsów API do ochrony prywatności i środowiska wykonawczego SDK na GitHubie zawiera zestaw poszczególnych projektów Android Studio, które pomogą Ci zacząć, w tym przykłady pokazujące, jak inicjować i wywoływać interfejs Topics API.

Obliczenie tematów następuje na końcu okresu. Domyślnie każdy okres epoch trwa 7 dni, ale możesz zmodyfikować ten interwał, aby uzyskać wynik. To polecenie Android Debug Bridge w powłoce powoduje skrócenie długości ery 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 wywołać obliczanie epoki, uruchom to polecenie:

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

Oprócz przykładowej aplikacji możesz też skorzystać z platformy Colab, aby testować różne kombinacje informacji o aplikacji w powiązaniu z klasyfikatorem tematów. Użyj tego colab, aby zobaczyć, jakie wyniki prawdopodobnie uzyska Twoja aplikacja po wywołaniu funkcji getTopics.

Szczegóły szyfrowania

Wraz z wprowadzeniem szyfrowania wywołania do 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 obiekt Topic.

Interfejs Topics API obsługuje jednorazową implementację szyfrowania hybrydowego kluczem publicznym (HPKE). Oczekujemy, że zarejestrowany dzwoniący będzie hostować 32-bitowy klucz publiczny na publicznym adresie URL szyfrowania podanym podczas rejestracji. Te klucze powinny być zakodowane w formacie Base64.

Obiekt EncryptedTopic ma 3 pola. Listę zwróconych tematów można uzyskać, używając klucza prywatnego odpowiadającego kluczowi publicznemu.

Na potrzeby programowania możesz przetestować szyfrowanie interfejsu Topics API, wyłączając weryfikację 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 interfejsu Topics API, które są w trakcie opracowywania, znajdziesz w informacjach o wersji.

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

Twoja opinia jest bardzo ważna dla Piaskownicy prywatności na Androida. Poinformuj nas o problemach, które zauważysz, lub o swoich pomysłach na udoskonalenie 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.