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 najnowszego pakietu SDK Piaskownicy prywatności na Androida, aby mieć aktualne informacje do ochrony prywatności.

  2. Dodaj do pliku manifestu te elementy:

    • 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, do którego odwołuje się 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 do usług reklamowych i kontroli dostępu do pakietów 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 pakiecie SDK. Aby przeprowadzić testy lokalne, możesz wyłączyć sprawdzanie rejestracji w Topics za pomocą tych poleceń:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. Włącz dostęp do Topics API. Domyślnie interfejs Topics API jest wyłączony. Musisz go włączyć, używając 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ę od skopiowania wersji przykładowej aplikacji w języku Java lub Kotlin, aby zapoznać się z metodami pobierania tematów na urządzeniu.

Poproś o zestaw tematów

Podstawowa funkcjonalność interfejsu Topics API znajduje się w metodie getTopics() w obiekcie TopicsManager, jak w tym przykładzie:

Kotlin Java 
fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

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ędnych do otrzymywania danych dotyczących tematów. GetTopicsRequest przekazuje potrzebne informacje 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 pełnisz roli obserwatora, Wywołanie getTopics zwraca temat z poprzedniej epoki, ale nie zwraca wpływa na dane dotyczące kolejnego. Wywołanie OutcomeReceiver obsługuje wynik asynchronicznie. Na przykład:

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

Po skonfigurowaniu urządzenia możesz zadzwonić, aby otrzymać GetTopicsResponse w ramach metody getTopics():

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

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

To wywołanie wyświetli listę obiektów Topics zawierających wartości identyfikatorów odpowiadające tematom z mapy kategorii open source, które są istotne w danej kategorii użytkownika lub występujący błąd. Tematy będą podobne do tego:

/Internet & Telecom/Text & Instant Messaging

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

Testowanie

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

Aby uzyskać pełnię wrażeń, zalecamy środowisko testowe z wieloma w których dzwonisz pod numer getTopics(), by zobaczyć, jak wybierane są tematy. Repozytorium interfejsów API środowiska wykonawczego pakietu SDK i interfejsów API chroniących prywatność na GitHubie zawiera zestaw poszczególnych projektów Android Studio, które pomogą Ci zacząć, w tym przykłady pokazujące, jak zainicjować i wywoływać interfejs Topics API.

Obliczenie tematów następuje na końcu okresu. Domyślnie każda epoka trwa 7 dni, ale możesz go zmienić, aby otrzymać wynik. To polecenie w powłoce Android Debug Bridge skraca długość 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 aktywować obliczenie epoki, uruchom następujące polecenie:

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

Oprócz przykładowej aplikacji możesz też skorzystać z kompilacji, aby testować różne kombinacje informacji o aplikacji w powiązaniu z klasyfikatorem tematów. Użyj tej usługi Colab, aby wyświetlać rodzaje wyników, jakie może uzyskać Twoja aplikacja otrzymasz, dzwoniąc pod numer 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 otrzymasz obiekt z tym samym formatem JSON co poprzedni obiekt Topic.

Interfejs Topics API obsługuje jednorazową implementację szyfrowania hybrydowego kluczem publicznym (HPKE). Oczekujemy, że zarejestrowany element wywołujący będzie hostować 32-bitowy klucz publiczny w publiczny punkt końcowy szyfrowania URL podany 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.

Do celów programistycznych możesz przetestować szyfrowanie interfejsu Topics API, wyłączając sprawdzić rejestrację. Spowoduje to, że interfejs API będzie używać testowego klucza publicznego do szyfrowania odpowiedzi. Zaszyfrowane tematy możesz odszyfrować za pomocą odpowiadający kluczowi prywatnemu.

Ograniczenia

Listę opracowywanych funkcji interfejsu Topics API znajdziesz w informacjami 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 Androida.

Dalsze kroki

Dowiedz się, jak użytkownicy i deweloperzy mogą zarządzać interfejsem Topics API i dostosowywać go do preferencji i potrzeb użytkowników.
Dowiedz się, jak działa interfejs Topics na Androidzie, i poznaj podstawowe czynności związane z obsługą interfejsu API.

Zobacz też

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