Omówienie interfejsu Topics API for Mobile

Uwaga: ten artykuł odzwierciedla aktualną wersję Piaskownicy prywatności na Androida i może ulec zmianie. Zachęcamy do przesyłania opinii i komentarzy, które mogą nam pomóc w tych działaniach.

Przesłać opinię

Informacje o interfejsie Topics API

W reklamach mobilnych reklamodawcy chcą wyświetlać trafne reklamy związane z zainteresowaniami użytkownika. Jeśli np. użytkownik jest zainteresowany informacjami o gotowaniu, reklamy związane z gotowaniem mogą być dla niego bardziej trafne niż te, które nie są związane z jego zainteresowaniami.

Reklama kontekstowa opiera się wyłącznie na zainteresowaniach powiązanych z aktualnymi treściami (i reklamami). Jedną z zalet interfejsu Topics API jest to, że umożliwia on aplikacjom, które są przydatne dla użytkowników, ale być może nie można łatwo zarabiać za pomocą reklam kontekstowych, na wyświetlanie użytkownikom trafniejszych reklam, niż by mogły. Pozwala to na finansowanie aplikacji, z których korzysta.

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, będą udostępniane reklamodawcom, ponieważ obsługują sygnały kontekstowe i inne sygnały własne, bez konieczności śledzenia poszczególnych użytkowników w różnych aplikacjach.

Interfejs Topics API służy do obsługi zewnętrznych pakietów SDK do wyświetlania reklam, które zwykle działają w wielu aplikacjach. Pomoc ta polega na pokazywaniu pewnych zainteresowań w różnych aplikacjach, które pakiety SDK normalnie obserwowałyby. Poszczególni deweloperzy aplikacji nie powinni spodziewać się dodatkowych informacji o użytkownikach.

Kluczowe pojęcia

• Temat to zrozumiały dla człowieka temat zainteresowania danego użytkownika. Jest on częścią mapy kategorii Topics.
• Temat jest obserwowany przez element wywołujący (aplikację lub zewnętrzny pakiet SDK używany w aplikacji), jeśli w ciągu ostatnich 3 etapów wywołujący wysłał żądanie do interfejsu Topics API z aplikacji powiązanej z tym tematem.
• Epoka to okres obliczania tematu, np. tydzień.

Jak to działa

W ramach tej oferty interfejs Topics API ma zapewniać osobom dzwoniącym szczegółowe interesujące ich tematy reklamowe na podstawie danych o tym, jak użytkownicy korzystają z aplikacji. Tematy te mogą uzupełniać wszelkie informacje kontekstowe związane z aplikacją, która chce wyświetlić reklamę, a także łączyć je, aby znaleźć odpowiednią reklamę dla użytkownika.

W przewodniku dla programistów po interfejsie Topics API znajdziesz przykłady kodu, które pokazują, jak skonfigurować możliwość pobierania tematów na potrzeby reklam opartych na zainteresowaniach. Uwaga: interfejsy API nie są jeszcze ukończone.

Tematy są wybierane ze wstępnie zdefiniowanej mapy kategorii typu open source.

Do wnioskowania tematów platforma korzysta z modelu klasyfikatora. Wdrożenie interfejsu Topics API oraz zastosowanie przez niego klasyfikatora będzie częścią projektu Android Open Source Project i z czasem zostanie udoskonalone.

W celach ilustracyjnych poniżej znajdziesz przykładowy kod pokazujący, jak korzystać z tematów do pobierania reklamy opartej na zainteresowaniach. Używane tutaj interfejsy API nie są ostateczne.

// Initialize the Topics API.
…
topicsFuture = AdvertisingTopicsClient.getTopics();

// Retrieve Topics and use them in Ad request.
Futures.addCallback(
    topicsFuture,
    new FutureCallback<AdvertisingTopicsInfo>() {
        @Override
        public void onSuccess(@Nullable AdvertisingTopicsInfo topicsInfo) {
            // Sanitize Topics result.
            ...
            // Initialize ad request with Topics obtained.
            AdRequest adRequest = AdRequest.initialize(topicsInfo);
        }

        @Override
        public void onFailure(Throwable t) {
            // Handle error.
            ...
        }
});

Aby lepiej zrozumieć, jak działa model klasyfikatora, możesz za pomocą usługi Android Topics Classifier Colab sprawdzić, jak różne dane aplikacji reagują w systemie.

Dostęp do interfejsów Topics API

Aby uzyskać dostęp do interfejsu Topics API, platformy technologii reklamowych muszą się zarejestrować. Więcej informacji znajdziesz w artykule Rejestrowanie konta Piaskownicy prywatności.

Szczegóły

• Po każdej epoki (np. raz w tygodniu) 5 najpopularniejszych tematów użytkownika jest obliczane na podstawie informacji z urządzenia.

  • Po wywołaniu interfejsu Topics API platforma sprawdzi, czy temat został przypisany do aplikacji, która wywołuje interfejs API. Jeśli nie ma żadnych przypisanych tematów, zostaną one wybrane w następujący sposób, a wybrany temat zostanie przypisany do aplikacji do końca tej epoki.
    • Prawdopodobieństwo wynoszące 95% oznacza, że temat jest wybierany losowo z listy 5 najpopularniejszych tematów dla danej epoki.
    • Prawdopodobieństwo wynoszące 5% oznacza, że temat jest wybierany losowo z taksonomii.
    • Element wywołujący może określić, że chce pobierać tematy bez zmieniania stanu, wywołując getTopics za pomocą parametru shouldRecordObservation = false. Oznacza to, że tematy mogą być zwracane, ale wywołanie nie będzie uwzględniane w obliczeniach tygodniowej epoki ani nie aktualizuje listy tematów zaobserwowanych w przypadku rozmówcy.
  • Każda aplikacja ma jeden z kilku tematów, ponieważ różne aplikacje powinny omawiać różne tematy, co utrudnia aplikacjom powiązanie tego samego użytkownika.
    • Na przykład aplikacja A może mieć dla użytkownika temat T1, ale aplikacja B – temat T2. Utrudnia to obu aplikacjom ustalenie, czy informacje te są powiązane z tym samym użytkownikiem.

• Topics API zwraca listę maksymalnie 3 tematów, po 1 w każdej z 3 ostatnich epoki.

  • Jeśli podasz maksymalnie 3 tematy, rzadko używane aplikacje będą miały wystarczającą liczbę tematów, aby wyświetlić odpowiednie reklamy, ale często używane aplikacje poznają maksymalnie 1 nowy temat tygodniowo.
  • Zwracane informacje o temacie obejmują identyfikator tematu (int) odpowiadający wpisowi w taksonomii, wersji taksonomii i wersji modelu klasyfikatora.
  • Temat mogą otrzymać tylko osoby, które w ciągu ostatnich 3 epoki zaobserwowały użycie aplikacji powiązanej z danym tematem.
  • Wszystkie zwracane tematy odpowiadają zainteresowaniom użytkownika. Możesz wybrać niektóre lub wszystkie z nich na potrzeby personalizacji reklam w żądaniu reklamy.

• Po przypisaniu tematu do aplikacji, która wywołuje interfejs Topics API, platforma określi, czy ten temat może go odebrać.

  • Temat mogą otrzymywać tylko osoby, które w ciągu ostatnich 3 epoki zaobserwowały zaangażowanie użytkowników w aplikację powiązaną z danym tematem.
  • Jeśli element wywołujący w przeszłości nie wywołał dla danego użytkownika interfejsu API w aplikacji dotyczącej tego tematu, temat nie zostanie uwzględniony na liście zwracanej przez interfejs API.
  • Jeśli element wywołujący nie otrzymał żadnych tematów w ciągu ostatnich 3 epoz, interfejs Topics API zwróci pustą listę.

  Załóżmy, że na urządzeniu użytkownika jest zainstalowanych 7 aplikacji: A, B, C, D, E, F i G. Załóżmy, że klasyfikacja tematów aplikacji i pakietów SDK technologii reklamowych w tych aplikacjach wygląda tak:

  Aplikacja	Klasyfikacja tematów	Pakiet SDK technologii reklamowych
  O	T1 i T5	pakiet-sdk1, ad-sdk2
  B	T2	pakiet-SDK2
  C	T3 i T6	pakiet-sdk3, ad-sdk4
  D	T1 i T4	pakiet-SDK1
  E	T5	pakiet-sdk4, ad-sdk5
  F	T6	ad-sdk2, ad-sdk3, ad-sdk4
  G	T7	pakiet-SDK2

  • Koniec 1. tygodnia: interfejs Topics API generuje 5 najpopularniejszych tematów użytkownika w danej epoki.

  Najpopularniejszy temat	Osoby, które mogą dowiedzieć się więcej na dany temat
  T1	pakiet-sdk1, ad-sdk2
  T2	pakiet-SDK2
  T3	pakiet-sdk3, ad-sdk4
  T4	pakiet-SDK1
  T5	ad-sdk1, ad-sdk2, ad-sdk4, ad-sdk5

  • Jeśli w tygodniu 2 rozmówca w dowolnej aplikacji wywołuje interfejs API, zwracana lista tematów będzie zawierać tylko te tematy, których element wywołujący znajduje się w kolumnie „Osoby, które mogą poznać temat” danego tematu w danej aplikacji w danej epoki.
  • Okno historii uwzględniane przy obliczaniu tematów dostępnych dla każdego rozmówcy wynosi 3 epoki (lub 3 tygodnie).
  • Używane są tylko tematy powiązane z aplikacjami, które wywołują interfejs Topics API za pomocą pakietów SDK reklam. Oznacza to, że jeśli aplikacja nie zawiera żadnych pakietów SDK reklam, które wywołują interfejs Topics API, tematy powiązane z tą aplikacją nie stanowią puli tematów dostępnych dla pakietów SDK reklam.
  • Aplikacja może również deklaratywnie zrezygnować z interfejsu Topics API za pomocą nowego pliku manifestu i elementów XML, aby uniemożliwić pakietom SDK reklam korzystanie z tego interfejsu. Tematy powiązane z aplikacjami, które zostały wyłączone, nie będą uwzględniane w tygodniowych obliczeniach dotyczących tematów. Ten dokument zostanie zaktualizowany o powiązane szczegóły implementacji.

• Jeśli wykorzystanie aplikacji jest niewystarczające, aby można było określić 5 tematów, platforma może rozważyć takie opcje jak losowe generowanie pozostałych tematów.

Taksonomia

• W obecnej ofercie początkowa taksonomia będzie obejmować od kilkuset do kilku tysięcy tematów. Wstępna propozycja taksonomii zostanie udostępniona w przyszłej aktualizacji tego dokumentu.
• Taksonomia zostanie wybrana przez człowieka, aby wrażliwe tematy nie zostały uwzględnione.
• Taksonomia będzie dostosowana do kategorii reklam, które mogą być wyświetlane w aplikacjach mobilnych na Androida.
• Mapa kategorii jest dostępna publicznie i może ulec zmianie. Sugestie można przesyłać za pomocą przycisku przesyłania opinii u góry tej strony.

Klasyfikator tematów

Interesujące tematy są określane na podstawie modelu klasyfikatora, który jest trenowany na publicznie dostępnych informacjach o aplikacji (takich jak jej nazwa, opis i nazwa pakietu).

• Gdy do wnioskowania używany jest model klasyfikatora do obliczania tematów dla danej epoki, używany zestaw sygnałów pozostaje na urządzeniu. Ten zestaw sygnałów może obejmować zainstalowane lub niedawno używane aplikacje, a później można go rozszerzyć, aby uwzględniał inne sygnały.
• Początkowe modele będą trenowane przez Google. Dane treningowe obejmują wybrane przez człowieka etykiety do publicznie dostępnych informacji o aplikacjach. Model będzie dostępny dla aplikacji w celu przetestowania, do jakich tematów klasyfikuje się aplikacja.
• Początkowe modele będą trenowane na publicznie dostępnych informacjach o aplikacjach z niektórych sklepów z aplikacjami, np. ze Sklepu Google Play.
• Możliwe, że aplikacja jest mapowana na więcej niż 1 temat, nie zawiera żadnych tematów lub nie dodaje nic do historii tematów użytkownika. Jeśli aplikacja jest mapowana na więcej niż 1 temat w taksonomii, liczba tematów wybranych dla tej aplikacji będzie ograniczona do 3 pierwszych.

Kontrola użytkowników

• Jej celem jest umożliwienie użytkownikom wyświetlania i usuwania tematów powiązanych z korzystaniem z aplikacji. Obecnie pracujemy nad implementacją tej funkcji kontroli użytkowników i zostanie ona uwzględniona w przyszłej aktualizacji.
• Jeśli użytkownik odinstaluje aplikację, która przyczyniła się do wyboru tematu w ciągu ostatnich 3 epoz, temat ten nie zostanie usunięty z listy tematów zwróconych w ciągu ostatnich 3 etapów, aby uniknąć ujawnienia informacji o odinstalowaniu.

Aby ułatwić testowanie tego, jak będą wyglądać wrażenia użytkownika, możesz też uruchomić intencję w aplikacji, aby wyświetlić interfejs ustawień Topics w taki sam sposób jak użytkownik. Przykład tego połączenia jest widoczny poniżej:

//Button that launches settings UI
private Button mSettingsAppButton;
private static final String RB_SETTING_APP_INTENT = "android.adservices.ui.SETTINGS";


//Does setup for button on screen that will launch settings UI to observe Topics
private void registerLaunchSettingsAppButton() {
    mSettingsAppButton.setOnClickListener(
        new View.OnClickListener() {

            @Override
            public void onClick(View view) {
                Context context = getApplicationContext();
                Intent activity2Intent = new Intent(RB_SETTING_APP_INTENT);
                activity2Intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
                context.startActivity(activity2Intent);
            }
        });
}

Rejestrowanie platformy technologii reklamowych

Aby uzyskać dostęp do interfejsu Topics API, wszystkie platformy technologii reklamowych (w tym platformy Google) muszą przejść proces rejestracji.

Deweloperzy aplikacji mogą określać, którzy deweloperzy technologii reklamowych mają dostęp do interfejsów Topics API, umieszczając identyfikator rejestracji dewelopera w pliku manifestu aplikacji.

Szyfrowanie zwróconych tematów

Zarejestrowane platformy technologii reklamowych, które wywołują interfejs Topics API, muszą też dostarczać klucze szyfrowania, aby mieć pewność, że zwrócone tematy będą możliwe do odczytania tylko dla wywołującego.

Piaskownica prywatności pobierze te klucze z punktu końcowego udostępnionego technologii reklamowej. Zgodnie ze sprawdzoną metodą zalecamy częste aktualizowanie kluczy, ale nie później niż co 6 miesięcy.

Piaskownica prywatności poprosi technologie reklamowe o potwierdzenie dostępności punktu końcowego udostępnionego przez technologię reklamową. Więcej informacji o działaniach, które są wymagane przez obecne i nowo zarejestrowane technologie reklamowe, znajdziesz w przewodniku dla programistów dotyczącym rejestracji.

Szczegóły szyfrowania

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

Interfejs Topics API obsługuje jednorazową implementację HPKE (hybrydowe szyfrowanie klucza publicznego). Oczekujemy, że zarejestrowany element wywołujący będzie hostować 32-bitowy klucz publiczny w punkcie końcowym publicznego adresu URL szyfrowania, który został podany podczas rejestracji. Klucze te powinny być zakodowane w formacie Base64.

Obiekt EncryptedTopic ma 3 pola. Listę zwróconych tematów można uzyskać, używając odpowiedniego klucza prywatnego dla klucza publicznego.

Do celów programistycznych możesz przetestować szyfrowanie szyfrowania Topics API, wyłączając sprawdzanie rejestracji. Wymusi to użycie przez interfejs API testowego klucza publicznego do szyfrowania odpowiedzi. Możesz odszyfrować zaszyfrowane tematy za pomocą odpowiedniego klucza prywatnego.