Attribution Reporting API: przewodnik po integracji

Podczas czytania dokumentacji Piaskownicy prywatności na Androida używaj przycisku Wersja przedpremierowa dla programistów lub Beta, aby wybrać wersję programu, z której korzystasz, ponieważ instrukcje mogą się różnić.

Interfejs Attribution Reporting API ma obsługiwać najważniejsze przypadki użycia związane z przypisywaniem udziału w konwersji i pomiarem konwersji w aplikacjach i internecie bez zależności od identyfikatorów użytkowników pochodzących od różnych podmiotów. W porównaniu z obecnie stosowanymi rozwiązaniami osoby wdrażające interfejs Attribution Reporting API powinny wziąć pod uwagę kilka ważnych kwestii ogólnych:

• Raporty na poziomie zdarzenia zawierają dane o konwersjach o niskiej dokładności. Wystarczy niewielka liczba wartości konwersji.
• Raporty z możliwością agregacji zawierają dane o konwersjach o większej dokładności. Twoje rozwiązania powinny projektować klucze agregacji na podstawie wymagań biznesowych i limitu 128 bitów.
• Modele danych i przetwarzanie w Twoim rozwiązaniu powinny uwzględniać limity liczby wywołań dostępnych wyzwalaczy, opóźnienia w wysyłaniu zdarzeń wyzwalających oraz szum dodawany przez interfejs API.

Aby ułatwić Ci planowanie integracji, ten przewodnik zawiera kompleksowy opis, który może obejmować funkcje, które nie zostały jeszcze wdrożone na obecnym etapie wersji testowej Piaskownicy prywatności na Androida dla deweloperów. W takich przypadkach podajemy wskazówki dotyczące harmonogramu.

Na tej stronie używamy terminu źródło na określenie kliknięcia lub wyświetlenia, a terminu wyzwalacz na określenie konwersji.

Wykres poniżej przedstawia różne opcje przepływu pracy w przypadku integracji atrybucji. Sekcje wymienione w tej samej kolumnie (zaznaczone na zielono) można realizować równolegle. Na przykład zaangażowanie partnera można przeprowadzić w tym samym czasie co atrybucję na poziomie zdarzeń w przypadku aplikacji.

Wymagania wstępne i konfiguracja

Wykonaj czynności opisane w tej sekcji, aby lepiej poznać interfejs Attribution Reporting API. Te czynności pomogą Ci uzyskać przydatne wyniki podczas korzystania z interfejsu API w ekosystemie technologii reklamowych.

Zapoznaj się z interfejsem API

1. Zapoznaj się z propozycją projektu, aby dowiedzieć się więcej o interfejsie Attribution Reporting API i jego możliwościach.
2. Więcej informacji o tym, jak włączyć kod i wywołania interfejsu API potrzebne w Twoich zastosowaniach, znajdziesz w przewodniku dla deweloperów.
3. Zarejestruj się, aby otrzymywać aktualności dotyczące interfejsu Attribution Reporting API. Dzięki temu będziesz na bieżąco z nowymi funkcjami, które zostaną wprowadzone w przyszłych wersjach.

Konfigurowanie i testowanie aplikacji próbnej

1. Gdy będziesz gotowy(-a) do rozpoczęcia integracji, skonfiguruj najnowszą wersję Developer Preview w Android Studio.
2. Skonfiguruj punkty końcowe serwera testowego na potrzeby rejestracji zdarzeń i dostarczania raportów. Udostępniliśmy makiety, których możesz używać w połączeniu z narzędziami dostępnymi online.
3. Pobierz i uruchom kod w naszej przykładowej aplikacji, aby zapoznać się z rejestrowaniem źródeł i wyzwalaczy.
1. Ustaw przedział czasu wysyłania raportów. Interfejs API obsługuje okresy 2-dniowe, 7-dniowe lub niestandardowe okresy od 2 do 30 dni.
2. Po zarejestrowaniu źródeł i reguł przez uruchomienie i użycie aplikacji przykładowej oraz po upływie określonego czasu sprawdź, czy otrzymano raport na poziomie zdarzenia i zaszyfrowany raport zbiorczy. Jeśli chcesz debugować raporty, możesz je generować szybciej, wymuszając uruchomienie zadań raportowania.
3. Sprawdź wyniki atrybucji w przypadku aplikacji. Sprawdź, czy dane w tych wynikach są zgodne z oczekiwaniami w przypadku atrybucji do ostatniego kliknięcia i po instalacji.
4. Gdy zrozumiesz, jak współpracują ze sobą interfejs API klienta i serwer, użyj przykładowej aplikacji jako wzorca, który pomoże Ci w integracji. Skonfiguruj własny serwer produkcyjny i dodaj do aplikacji wywołania rejestracji zdarzeń.

Przed integracją

Zarejestruj swoją organizację w Piaskownicy prywatności na Androida. Rejestracja ma zapobiegać niepotrzebnemu powielaniu platform technologii reklamowych, co umożliwiałoby dostęp do większej ilości informacji o aktywności użytkownika niż jest to konieczne.

Zaangażowanie partnera

Partnerzy technologii reklamowych (MMP/SSP/DSP) często tworzą zintegrowane rozwiązania do atrybucji. Czynności opisane w tej sekcji pomogą Ci przygotować się do skutecznej współpracy z partnerami technologii reklamowych.

1. Zaplanuj rozmowę z najważniejszymi partnerami w zakresie pomiarów, aby omówić testowanie i wdrażanie interfejsu Attribution Reporting API. Partnerzy pomiarowi mogą obejmować sieci technologii reklamowych, platformy SSP, platformy DSP, reklamodawców lub innych partnerów, z którymi współpracujesz lub chcesz współpracować.
2. Współpracuj z partnerami świadczącymi usługi pomiaru, aby określić harmonogram integracji, od wstępnych testów po wdrożenie.
3. Skonsultuj się z partnerami świadczącymi usługi pomiarowe, które obszary każdy z Was będzie obejmować w projekcie atrybucji.
4. Ustanów kanały komunikacji między partnerami pomiarowymi, aby synchronizować harmonogramy i przeprowadzać kompleksowe testy.
5. Projektowanie przepływów danych na wysokim poziomie między partnerami świadczącymi usługi pomiaru. Najważniejsze kwestie to:
   • Jak partnerzy pomiarowi będą rejestrować źródła atrybucji w interfejsie Attribution Reporting API?
   • Jak sieci technologii reklamowych będą rejestrować wyzwalacze w interfejsie Attribution Reporting API?
   • W jaki sposób każda platforma reklamowa będzie weryfikować żądania interfejsu API i zwracać odpowiedzi, aby dokończyć rejestrację źródła i wyzwalacza?
   • Czy są jakieś raporty, które należy udostępniać partnerom poza interfejsem Attribution Reporting API?
   • Czy są jakieś inne punkty integracji lub wymagane dostosowania między partnerami? Na przykład czy Ty i Twoi partnerzy musicie pracować nad usuwaniem duplikatów konwersji lub uzgadnianiem kluczy agregacji?
6. Jeśli atrybucja z aplikacji do internetu ma zastosowanie, umów się na rozmowę z partnerami ds. pomiarów w internecie, aby omówić projektowanie, testowanie i wdrażanie interfejsu Attribution Reporting API. Rozpoczynając rozmowy z partnerami internetowymi, odwołuj się do pytań z poprzedniego kroku.

Prototyp atrybucji na poziomie zdarzenia przy przechodzeniu z aplikacji do aplikacji

W tej sekcji znajdziesz informacje o konfigurowaniu podstawowego atrybucji w przypadku aplikacji z raportami na poziomie zdarzenia w aplikacji lub pakiecie SDK. Wypełnienie tej sekcji jest wymagane, zanim zaczniesz prototypować atrybucję serwera agregacji.

1. Skonfiguruj serwer zbierania rekordów zdarzeń. Możesz to zrobić, korzystając z podanej specyfikacji, aby wygenerować serwer testowy, lub skonfigurować własny serwer za pomocą przykładowego kodu serwera.
2. Dodaj do pakietu SDK lub aplikacji wywołania zdarzenia rejestracji źródła, gdy wyświetlają się reklamy.
   • Kluczowe kwestie to:
     • Sprawdź, czy identyfikatory zdarzeń źródłowych są dostępne i prawidłowo przekazywane do wywołań interfejsu API rejestracji źródła.
     • Sprawdź, czy możesz też przekazać element `InputEvent`, aby zarejestrować źródła kliknięć.
     • Określ, jak skonfigurujesz priorytet źródła dla różnych typów zdarzeń. Możesz na przykład przypisać wysoki priorytet zdarzeniom, które są uznawane za wartościowe, np. kliknięciom zamiast wyświetleń.
     • Domyślna wartość wygaśnięcia jest odpowiednia do testowania. Możesz też skonfigurować różne okresy ważności.
     • Na potrzeby testowania możesz pozostawić domyślne filtry i okna atrybucji.
   • Opcjonalne kwestie do rozważenia:
     • Zaprojektuj klucze agregacji, jeśli są Ci potrzebne.
     • Określając, jak chcesz współpracować z innymi partnerami świadczącymi usługi pomiaru, weź pod uwagę strategię przekierowań.
3. Dodaj do pakietu SDK lub aplikacji zdarzenia wywołujące rejestrację, aby rejestrować zdarzenia prowadzące do konwersji.
   • Kluczowe kwestie to:
     • Określ dane wywołujące, biorąc pod uwagę ograniczoną dokładność zwracanych danych: jak zamierzasz zmniejszyć liczbę typów konwersji, których reklamodawcy potrzebują w przypadku 3 bitów dostępnych dla kliknięć i 1 bitu dostępnego dla wyświetleń?
     • Limity dostępnych wyzwalaczy w raportach zdarzeń: jak zamierzasz zmniejszyć łączną liczbę konwersji z poszczególnych źródeł, które możesz otrzymywać w raportach zdarzeń?
   • Opcjonalne kwestie do rozważenia:
     • Nie twórz kluczy deduplikacji, dopóki nie przeprowadzisz testów dokładności.
     • Nie twórz kluczy i wartości agregacji, dopóki nie będzie dostępna obsługa testowania symulacji.
     • Pomiń przekierowania, dopóki nie ustalisz, jak chcesz współpracować z innymi partnerami pomiarowymi.
     • Priorytet wyzwalacza nie jest niezbędny do testowania.
     • Podczas wstępnych testów filtry można prawdopodobnie zignorować.
4. Sprawdź, czy dla reklam są generowane zdarzenia źródłowe i czy wyzwalacze prowadzą do tworzenia raportów o zdarzeniach.

Testowanie symulacyjne

W tej sekcji dowiesz się, jak sprawdzić, jaki wpływ na systemy raportowania i optymalizacji będzie miało przeniesienie obecnych konwersji do raportów o zdarzeniach i raportów z możliwością agregacji. Dzięki temu możesz rozpocząć testowanie wpływu przed zakończeniem integracji.

Testowanie polega na symulowaniu generowania raportów o zdarzeniach i raportów z możliwością agregacji na podstawie historycznych rekordów konwersji, a następnie na uzyskiwaniu zagregowanych wyników z symulowanego serwera agregacji. Te wyniki można porównać z historycznymi danymi o konwersjach, aby sprawdzić, jak zmieni się dokładność raportowania.

Na podstawie tych raportów można trenować modele optymalizacji, np. obliczenia przewidywanego współczynnika konwersji, aby porównać dokładność tych modeli z modelami utworzonymi na podstawie bieżących danych. To także okazja do eksperymentowania z różnymi strukturami kluczy agregacji i ich wpływem na wyniki.

1. Skonfiguruj bibliotekę symulacji pomiarów na komputerze lokalnym.
2. Zapoznaj się ze specyfikacją formatu danych o konwersjach, aby były one zgodne z generatorem symulowanych raportów.
3. Zaprojektuj klucze agregacji na podstawie wymagań biznesowych.
   • Kluczowe kwestie to:
     • Weź pod uwagę kluczowe wymiary, które Twoi klienci lub partnerzy muszą agregować, i skup się na nich podczas oceny.
     • Określ minimalną liczbę wymiarów zbiorczych i ich liczności, które są potrzebne do spełnienia Twoich wymagań.
     • Sprawdź, czy kluczowe elementy po stronie źródła i po stronie wywołującej nie przekraczają 128 bitów.
     • Jeśli Twoje rozwiązania obejmują przypisywanie wielu wartości do każdego zdarzenia wywołującego, pamiętaj, aby skalować wartości w stosunku do maksymalnego budżetu na przypisywanie, L1. Pomoże to zminimalizować wpływ szumu.
     • Oto przykład, który szczegółowo opisuje ustawienie klucza do zbierania zagregowanych liczb konwersji na poziomie kampanii oraz klucza do zbierania zagregowanych wartości zakupu na poziomie geograficznym.
4. Uruchom generator raportów, aby utworzyć raporty o zdarzeniach i raporty z możliwością agregacji.
5. Uruchom raporty z możliwością agregacji na symulowanych serwerach agregacji, aby uzyskać raporty podsumowujące.
6. Przeprowadzanie eksperymentów dotyczących narzędzi:
   • Porównaj łączne liczby konwersji z raportów na poziomie zdarzenia i raportów podsumowujących z historycznymi danymi o konwersjach, aby określić dokładność raportowania konwersji. Aby uzyskać najlepsze wyniki, przeprowadzaj testy raportowania i porównania na szerokiej, reprezentatywnej grupie reklamodawców.
   • Ponownie trenuj modele na podstawie danych z raportów na poziomie zdarzenia, a także danych z raportów zbiorczych. Porównaj dokładność z modelami utworzonymi na podstawie historycznych danych treningowych.
   • Wypróbuj różne strategie grupowania i sprawdź, jak wpływają one na wyniki.
     • Najważniejsze kwestie to:
     • Aktualność raportów podsumowujących na potrzeby dostosowywania stawek.
     • Średnie częstotliwości zdarzeń, które można przypisać do urządzenia. Na przykład na podstawie danych o historycznych zdarzeniach zakupu możesz przewidywać, którzy nieaktywni użytkownicy powrócą.
     • Poziom hałasu. Więcej partii oznacza mniejszą agregację, a mniejsza agregacja oznacza większy szum.

Atrybucja serwera agregacji prototypu: konfiguracja

Dzięki tym czynnościom będziesz otrzymywać raporty zbiorcze dotyczące zdarzeń źródłowych i wyzwalających.

1. Skonfiguruj serwer agregacji:
   • Skonfiguruj konto AWS.
   • Zarejestruj się w usłudze agregacji u koordynatora.
   • Skonfiguruj serwer agregacji w AWS za pomocą dostarczonych plików binarnych.
2. Zaprojektuj klucze agregacji na podstawie wymagań biznesowych. Jeśli to zadanie zostało już wykonane w sekcji dotyczącej zdarzeń na poziomie aplikacji, możesz pominąć ten krok.
3. Skonfiguruj serwer zbierania raportów podlegających agregacji. Jeśli masz już utworzony taki warunek w sekcji zdarzeń na poziomie aplikacji, możesz go użyć ponownie.

Atrybucja prototypowego serwera agregacji: integracja

Aby przejść dalej, musisz wykonać czynności opisane w sekcji Atrybucja za pomocą serwera agregacji prototypu: konfiguracja lub w sekcji Atrybucja na poziomie zdarzenia w przypadku prototypu aplikacji**.

1. Dodaj dane klucza agregacji do źródła i zdarzeń wywołujących. Prawdopodobnie będzie to wymagać przekazywania do pakietu SDK lub aplikacji większej ilości danych o zdarzeniu reklamy, np. identyfikatora kampanii, aby uwzględnić je w kluczu agregacji.
2. Zbieraj z źródła raporty z możliwością agregacji dotyczące komunikacji między aplikacjami i wywołuj zdarzenia zarejestrowane z danymi klucza agregacji.
3. Testuj różne strategie przetwarzania wsadowego podczas generowania tych raportów z możliwością agregacji na serwerze agregacji i sprawdzaj, jak wpływają one na wyniki.

Iteracyjne projektowanie z użyciem funkcji opcjonalnych

Oto dodatkowe funkcje, które możesz uwzględnić w swoim rozwiązaniu pomiarowym.

Użyj interfejsu Debug API, aby wygenerować klucze debugowania (zdecydowanie zalecane)

1. Ustawienie klucza debugowania umożliwi Ci otrzymywanie niezmienionego raportu o zdarzeniu źródłowym lub wywołującym wraz z raportami generowanymi przez interfejs Attribution Reporting API. Klucze debugowania umożliwiają porównywanie raportów i wykrywanie błędów podczas integracji.

Dostosowywanie zachowań atrybucji

1. Atrybucja w przypadku reguł po instalacji
   • Tej funkcji można używać w przypadku, gdy wyzwalacze po instalacji muszą być przypisane do tego samego źródła atrybucji, które spowodowało instalację, nawet jeśli występują inne kwalifikujące się źródła atrybucji, które pojawiły się później.
   • Może się na przykład zdarzyć, że użytkownik kliknie reklamę, która spowoduje instalację. Po zainstalowaniu użytkownik klika inną reklamę i dokonuje zakupu. W takim przypadku firma z branży technologii reklamowych może chcieć przypisać zakup do pierwszego kliknięcia, a nie do kliknięcia ponownego zaangażowania.
2. Używanie filtrów do dostosowywania danych w raportach na poziomie zdarzenia
   • Filtry konwersji można skonfigurować tak, aby ignorowały wybrane wyzwalacze i wykluczały je z raportów o zdarzeniach. Ze względu na limity liczby wywołań na źródło atrybucji filtry umożliwiają uwzględnianie w raportach o zdarzeniach tylko tych wywołań, które dostarczają najbardziej przydatnych informacji.
   • Filtry można też stosować do selektywnego odfiltrowywania niektórych wyzwalaczy, co pozwala je ignorować. Jeśli na przykład masz kampanię kierowaną na instalacje aplikacji, możesz odfiltrować wyzwalacze po instalacji, aby nie były przypisywane do źródeł z tej kampanii.
   • Filtry można też stosować do dostosowywania danych wywołujących na podstawie danych źródłowych. Na przykład źródło może określić "product" : ["1234"], gdzie product jest kluczem filtra, a 1234 jest wartością. Każdy wyzwalacz z kluczem filtra „product” o wartości innej niż „1234” jest ignorowany.
3. Dostosowany priorytet źródła i wyzwalacza
   • Jeśli z regułą może być powiązanych kilka źródeł atrybucji lub do źródła można przypisać kilka reguł, możesz użyć 64-bitowej liczby całkowitej ze znakiem, aby nadać priorytet określonym źródłom lub regułom atrybucji.

Współpraca z platformami MMP i innymi podmiotami

1. Przekierowania do innych firm w przypadku zdarzeń źródłowych i wywołujących
   • Możesz ustawić adresy URL przekierowania, aby umożliwić rejestrowanie żądań przez wiele platform technologii reklamowych. Może to służyć do włączania usuwania duplikatów w atrybucji w różnych sieciach.
2. Klucze deduplikacji
   • Gdy reklamodawca używa kilku platform technologii reklamowych do rejestrowania tego samego zdarzenia wywołującego, można użyć klucza deduplikacji, aby odróżnić te powtarzające się raporty. Jeśli nie podasz klucza deduplikacji, zduplikowane wywołania mogą być zgłaszane każdej platformie technologii reklamowej jako unikalne.

Praca z pomiarami na różnych platformach

1. Atrybucja w wielu aplikacjach i w internecie (dostępna pod koniec IV kwartału)
   • Obsługuje przypadki, w których użytkownik widzi reklamę w aplikacji, a potem dokonuje konwersji w przeglądarce mobilnej lub przeglądarce w aplikacji, albo odwrotnie.