Wdrażanie interfejsu Topics API na Androidzie

Konfiguracja

Aby wdrożyć interfejs Topics API, musisz najpierw skonfigurować środowisko deweloperskie. W tym celu wykonaj te czynności:

  1. Używaj najnowszego pakietu SDK Piaskownicy prywatności na Androida, aby mieć dostęp do najbardziej aktualnej wersji interfejsów API chroniących prywatność.

  2. Dodaj do pliku manifestu te elementy:

    • Uprawnienia: dodaj uprawnienie ACCESS_ADSERVICES_TOPICS, aby zezwolić aplikacji na dostęp do interfejsu Topics API:

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

    • Konfiguracja usług reklamowych: odwołaj się do pliku konfiguracyjnego usług reklamowych w elemencie <application> 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ę 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 zestawie SDK. Aby przetestować interfejs Topics lokalnie, możesz wyłączyć sprawdzanie rejestracji za pomocą tych poleceń:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. Włącz dostęp do interfejsu Topics API. Interfejs Topics API jest domyślnie wyłączony. Musisz włączyć go 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ę od skopiowania naszej przykładowej aplikacji w Javie lub Kotlin, aby dowiedzieć się, jak pobierać tematy na urządzeniu.

Prośba 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 niezbędne informacje do pobierania danych z interfejsu Topics API, w tym flagę wskazującą, czy wywołujący będzie pełnić rolę obserwatora. Gdy nie działa jako obserwator, wywołanie getTopics zwraca temat z poprzedniej epoki, ale nie ma wpływu na dane dotyczące tematów w kolejnej epoce. 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");
    }
};

Gdy konfiguracja będzie gotowa, możesz zadzwonić, aby otrzymać GetTopicsResponse w wyniku działania metody getTopics():

Kotlin 

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

Java 

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

Wywołanie zwróci listę obiektów Topics zawierających wartości identyfikatorów, które odpowiadają tematom w taksonomii o otwartym kodzie źródłowym, które są istotne dla użytkownika, lub odpowiedni błąd. Tematy będą wyglądać podobnie jak w tym przykładzie:

/Internet & Telecom/Text & Instant Messaging

Listę możliwych tematów, które mogą być zwracane, 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 działania interfejsu API. W przyszłych wersjach poprawimy jakość tematów.

Aby w pełni wykorzystać możliwości tej funkcji, zalecamy środowisko testowe z wieloma aplikacjami, w których możesz wywołać getTopics(), aby sprawdzić, jak wybierane są tematy. Repozytorium SDK Runtime i chroniących prywatność interfejsów API 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.

Obliczanie tematów odbywa się na koniec epoki. Domyślnie każdy okres trwa 7 dni, ale możesz go zmienić, 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

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 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ć Colabu, aby przetestować różne kombinacje informacji o aplikacji w porównaniu z klasyfikatorem tematów. Skorzystaj z tego notatnika Colab, aby zobaczyć rodzaje wyników, które prawdopodobnie uzyskasz w aplikacji podczas wywoływania funkcji getTopics.

Szczegóły szyfrowania

Wraz z wprowadzeniem szyfrowania wywołania 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 jednorazowe wdrożenie HPKE (Hybrid Public Key Encryption). Oczekujemy, że zarejestrowany rozmówca 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ć, używając odpowiedniego klucza prywatnego do klucza publicznego.

Na potrzeby programowania możesz przetestować szyfrowanie interfejsu Topics API, wyłączając sprawdzanie rejestracji. Wymusi to użycie przez interfejs API testowego klucza publicznego do szyfrowania odpowiedzi. Zaszyfrowane tematy możesz odszyfrować za pomocą odpowiedniego klucza prywatnego.

Ograniczenia

Listę funkcji interfejsu Topics API, nad którymi trwają prace, znajdziesz w informacjach o wersji.

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

Twoje opinie są kluczowym elementem Piaskownicy prywatności na Androida. Daj nam znać o wszelkich problemach, które napotkasz, lub o pomysłach na ulepszenie Piaskownicy prywatności na Androida.

Next steps

Learn how users and developers can manage and customize the Topics API to suit user's preferences and needs.
Understand how Topics works on Android and lear about the core steps of the API flow.

See also

Check out our resources to better understand the Topics API on Android.