Omówienie raportów atrybucji dla urządzeń mobilnych

Uwaga: ten dokument odzwierciedla obecne propozycje dotyczące Piaskownicy prywatności na Androida i może ulec zmianie. Zachęcamy do przesyłania opinii i komentarzy, które pomogą nam w realizacji tych działań.

Ostatnie aktualizacje

• Zaktualizowaliśmy listę nadchodzących zmian i znanych problemów.
• Wprowadziliśmy elastyczną konfigurację na poziomie zdarzenia „Lite” jako pomost do pełnej elastycznej konfiguracji na poziomie zdarzenia.
• Od września 2023 r. platformy registerWebSource, registerWebTrigger, registerAppSource i registerAppTrigger muszą używać ciągów znaków w przypadku pól, które oczekują wartości liczbowej (np. priority, source_event_id, debug_key, trigger_data, deduplication_key itd.)
• W IV kwartale 2023 r. dodamy do interfejsu Attribution Reporting API w Google Cloud obsługę generowania raportów zbiorczych za pomocą usługi agregacji w Google Cloud. Szczegółowe informacje znajdziesz tutaj. Więcej informacji o konfigurowaniu usługi agregacji w Google Cloud znajdziesz w przewodniku wdrażania.
• Nowe limity stawek chroniące prywatność dla liczby unikalnych miejsc docelowych.
• Zaktualizowana funkcjonalność filtrów reguły okresu ważności zostanie udostępniona w I kwartale 2024 r. Więcej informacji na ten temat znajdziesz w uwagach.

Omówienie

Obecnie rozwiązania do atrybucji i pomiarów na urządzeniach mobilnych często wykorzystują pochodzące z różnych źródeł identyfikatory, np. identyfikator wyświetlania reklam. Interfejs Attribution Reporting API ma zapewniać lepszą ochronę prywatności użytkowników dzięki wyeliminowaniu zależności od takich identyfikatorów (własnych i pochodzących od firm zewnętrznych) oraz obsługiwać najważniejsze przypadki pomiaru konwersji i przypisywania udziału w konwersji w aplikacjach i w internecie.

Ten interfejs API zawiera poniższe mechanizmy strukturalne, które stanowią platformę do zwiększania prywatności. Opisaliśmy je bardziej szczegółowo w dalszej części tej strony:

• Ogranicza liczbę bitów dostępnych na potrzeby raportów na poziomie zdarzenia.
• Włącza bardziej precyzyjne dane o konwersjach tylko w raportach agregowanych.
• Wprowadza ograniczenia szybkości dla dostępnych wyzwalaczy (konwersji) i liczby technologii reklamowych, które można powiązać z pojedynczym źródłem atrybucji.
• Stosuje różne techniki dodawania szumów

Poprzednie mechanizmy ograniczają możliwość łączenia tożsamości użytkownika z 2 różnych aplikacji lub domen.

Interfejs Attribution Reporting API obsługuje te przypadki użycia:

• Raporty dotyczące konwersji: pomagają reklamodawcom mierzyć skuteczność kampanii, wyświetlając liczbę konwersji (reguł) i wartości konwersji (reguł) w różnych wymiarach, m.in. według kampanii, grupy reklam i kreacji reklamy.
• Optymalizacja: raporty na poziomie zdarzenia, które ułatwiają optymalizację wydatków na reklamę dzięki udostępnianiu danych atrybucji dotyczących poszczególnych wyświetleń, które można wykorzystać do trenowania modeli ML.
• Wykrywanie nieprawidłowej aktywności: tworzenie raportów, które można wykorzystać do wykrywania i analizowania nieprawidłowego ruchu oraz oszustw reklamowych.

Ogólnie interfejs Attribution Reporting API działa w ten sposób:

1. Technologie reklamowe ukończą proces rejestracji, aby móc korzystać z interfejsu Attribution Reporting API.
2. Technologia reklamowa rejestruje źródła atrybucji – kliknięcia lub wyświetlenia reklam – za pomocą Attribution Reporting API.
3. Technologia reklamowa rejestruje reguły (konwersje użytkowników w aplikacji lub witrynie reklamodawcy) za pomocą interfejsu Attribution Reporting API.
4. Interfejs Attribution Reporting API dopasowuje reguły do źródeł atrybucji – atrybucji konwersji – i co najmniej 1 reguła jest wysyłana z urządzenia za pomocą raportów na poziomie zdarzenia i zbiorczych raportów do działu technologii reklamowych.

Uwaga: aby dowiedzieć się więcej o tym, jak wdrożyć tę metodę w przypadku atrybucji między aplikacjami, przeczytaj sekcję dotyczącą atrybucji w różnych sieciach w Przewodniku dla deweloperów interfejsu Attribution Reporting API. Aby dowiedzieć się, jak wdrożyć przypadek użycia „aplikacja–strona internetowa” lub „strona internetowa–aplikacja”, przeczytaj propozycję projektu pomiarów obejmujących aplikacje i witryny internetowe.

Dostęp do interfejsów Attribution Reporting API

Aby uzyskać dostęp do interfejsów Attribution Reporting API, platformy technologii reklamowych muszą się zarejestrować. Więcej informacji znajdziesz w artykule Rejestracja na konto Piaskownicy prywatności.

Rejestrowanie źródła atrybucji (kliknięcie lub wyświetlenie)

Interfejs Attribution Reporting API nazywa kliknięcia i wyświetlenia reklam źródłami atrybucji. Aby zarejestrować kliknięcie lub wyświetlenie reklamy, wywołaj registerSource(). Ten interfejs API oczekuje tych parametrów:

• Identyfikator URI źródła atrybucji: platforma wysyła żądanie do tego identyfikatora URI, aby pobrać metadane powiązane ze źródłem atrybucji.
• Zdarzenie wejściowe:obiekt InputEvent (w przypadku zdarzenia kliknięcia) lub null (zdarzenia wyświetlenia).

Gdy interfejs API wysyła żądanie do identyfikatora URI źródła atrybucji, technologia reklamowa powinna w odpowiedzi odpowiedzieć na metadane źródła atrybucji w nowym nagłówku HTTP Attribution-Reporting-Register-Source, podając te pola:

• Identyfikator źródła zdarzenia: ta wartość reprezentuje dane na poziomie zdarzenia powiązane z tym źródłem atrybucji (kliknięcie lub wyświetlenie reklamy). Musi być 64-bitową liczbą bez znaku sformatowaną jako ciąg znaków.
• Miejsce docelowe: miejsce źródłowe z domeną eTLD+1 lub nazwą pakietu aplikacji, w której występuje zdarzenie aktywujące.
• Czas ważności (opcjonalnie): czas ważności w sekundach, po upływie którego źródło powinno zostać usunięte z urządzenia. Wartość domyślna to 30 dni, minimalna wartość to 1 dzień, a maksymalna – 30 dni. Ta wartość jest zaokrąglana do najbliższego dnia. Może być sformatowany jako 64-bitowa liczba całkowita bez znaku lub ciąg znaków.
• Okno raportowania zdarzeń (opcjonalnie): czas w sekundach po zarejestrowaniu źródła, w którym można tworzyć raporty zdarzeń dla tego źródła. Jeśli po upływie okna raportu o zdarzeniach data ważności jeszcze nie minęła, regułę nadal można dopasować do źródła, ale nie zostanie dla niej wysłany raport o zdarzeniach. Nie może być większa niż data ważności. Można ją sformatować jako 64-bitową nieoznaczoną liczbę całkowitą lub ciąg znaków.
• Okno raportowania umożliwiające agregację danych (opcjonalnie): czas w sekundach po zarejestrowaniu źródła, w którym można tworzyć raporty umożliwiające agregację danych z tego źródła. Nie może być większe niż data wygaśnięcia. Można ją sformatować jako 64-bitową nieoznaczoną liczbę całkowitą lub ciąg znaków.
• Priorytet źródła (opcjonalnie): służy do wybrania źródła atrybucji, z którym ma być powiązany dany element aktywatora, na wypadek, gdyby z tym elementem miało być powiązanych kilka źródeł atrybucji. Musi być 64-bitową liczbą całkowitą ze znakiem w postaci ciągu znaków.
  
  Gdy zostanie odebrany odpowiedni komunikat, interfejs API znajdzie pasujące źródło atrybucji o najwyższej wartości priorytetu źródła i wygeneruje raport. Każda platforma reklamowa może definiować własną strategię ustalania priorytetów. Więcej informacji o tym, jak priorytet wpływa na atrybucję, znajdziesz w sekcji Przykład ustalania priorytetów.
  
  Wyższe wartości oznaczają wyższe priorytety.
• Okna atrybucji instalacji i po instalacji (opcjonalnie): służą do określania atrybucji zdarzeń po instalacji opisanych poniżej.
• Dane filtra (opcjonalnie): służą do selektywnego filtrowania niektórych wyzwalaczy, co powoduje ich ignorowanie. Więcej informacji znajdziesz w sekcji Filtry wyzwalające na tej stronie.
• Klucze agregacji (opcjonalnie): określ podział na segmenty, który ma być używany w raportach agregowanych.

Opcjonalnie odpowiedź z metadanymi źródła atrybucji może zawierać dodatkowe dane w nagłówku przekierowań raportowania atrybucji. Dane zawierają adresy URL przekierowań, które umożliwiają wielu technologiom reklamowym zarejestrowanie żądania.

Przewodnik dla programistów zawiera przykłady, które pokazują, jak zaakceptować rejestrację źródła.

Poniżej znajduje się przykładowy przepływ pracy:

1. Pakiet SDK technologii reklamowej wywołuje interfejs API, aby zainicjować rejestrację źródła atrybucji, podając URI interfejsu API do wywołania:

   registerSource(
       Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
       myClickEvent);
   

2. Interfejs API wysyła żądanie do https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA przy użyciu jednego z tych nagłówków:

   <!-- For click events -->
   Attribution-Reporting-Source-Info: navigation
   
   <!-- For view events -->
   Attribution-Reporting-Source-Info: event
   

3. Serwer HTTPS tej technologii reklamowej odpowiada z nagłówkami zawierającymi:

   Attribution-Reporting-Register-Source: {
       "destination": "android-app://com.advertiser.example",
       "source_event_id": "234",
       "expiry": "60000",
       "priority": "5"
   }
   Attribution-Reporting-Redirect:
   https://adtechpartner1.example?their_ad_click_id=567
   Attribution-Reporting-Redirect:
   https://adtechpartner2.example?their_ad_click_id=890
   

4. Interfejs API wysyła żądanie do każdego adresu URL określonego w Attribution-Reporting-Redirect. W tym przykładzie podane są 2 adresy URL partnerów technologii reklamowych, więc interfejs API wysyła jedno żądanie do https://adtechpartner1.example?their_ad_click_id=567, a drugie do https://adtechpartner2.example?their_ad_click_id=890.

5. Serwer HTTPS tej technologii reklamowej odpowiada nagłówkami zawierającymi:

   Attribution-Reporting-Register-Source: {
       "destination": "android-app://com.advertiser.example",
       "source_event_id": "789",
       "expiry": "120000",
       "priority": "2"
   }
   

   Uwaga: odpowiedzi zespołów ds. technologii reklamowych mogą zawierać inne metadane w nagłówku Attribution-Reporting-Register-Source.

W przypadku żądań wyświetlonych w poprzednich krokach rejestrowane są 3 źródła atrybucji (kliknięcia).

Rejestrowanie źródła atrybucji z WebView

WebView obsługuje przypadki użycia, w których aplikacja renderuje reklamę w komponencie WebView. Jest to obsługiwane przez komponent WebView bezpośrednio wywołujący registerSource() jako żądanie w tle. Wywołanie wiąże źródło atrybucji z aplikacją zamiast z pierwotną organizacją najwyższego poziomu. Obsługiwana jest też rejestracja źródeł z wbudowanych treści internetowych w kontekście przeglądarki. Aby to zrobić, zarówno wywołujący interfejs API, jak i aplikacje muszą dostosować ustawienia. Więcej informacji o wywoływaniu interfejsu API znajdziesz w artykule Rejestrowanie źródła atrybucji i wyzwalacza z WebView, a o rejestrowaniu źródła atrybucji i wyzwalacza z WebView – w artykule Rejestrowanie źródła atrybucji i wyzwalacza z WebView.

Ponieważ technologie reklamowe używają wspólnego kodu w przypadku przeglądarki internetowej i WebView, WebView stosuje przekierowania HTTP 302 i przekazuje prawidłowe rejestracje na platformę. Nie planujemy obsługi nagłówka Attribution-Reporting-Redirect w tym scenariuszu, ale jeśli masz problem z takim przypadkiem użycia, skontaktuj się z nami.

Rejestrowanie reguły (konwersja)

Platformy technologiczne związane z reklamami mogą rejestrować wyzwalacze (konwersje takie jak instalacje lub zdarzenia po instalacji) za pomocą metody registerTrigger().

Metoda registerTrigger() oczekuje parametru Identyfikator URI aktywatora. Interfejs API wysyła żądanie do tego identyfikatora URI, aby pobrać metadane powiązane z wyzwalaczem.

Interfejs API śledzi przekierowania. Odpowiedź serwera technologii reklamowych powinna zawierać nagłówek HTTP o nazwie Attribution-Reporting-Register-Trigger, który zawiera informacje o co najmniej 1 zarejestrowanym czynniku uruchamiającym. Treść nagłówka powinna być zakodowana w formacie JSON i zawierać te pola:

• Dane reguły: dane służące do identyfikacji reguły reguły (3 bity w przypadku kliknięć i 1 bit w przypadku wyświetleń). Musi być 64-bitową liczbą całkowitą ze znakiem w formacie ciągu znaków.
• Priorytet reguły (opcjonalny): reprezentuje priorytet tej reguły w porównaniu z innymi aktywatorami z tym samym źródłem atrybucji. Musi być 64-bitową liczbą całkowitą ze znakiem w formacie ciągu znaków. Więcej informacji o tym, jak priorytety wpływają na raportowanie, znajdziesz w sekcji Ustalanie priorytetów.
• Klucz deduplikacji (opcjonalny): służy do identyfikowania przypadków, w których ta sama reguła jest zarejestrowana wiele razy przez tę samą platformę technologii reklamowych dla tego samego źródła atrybucji. Musi być 64-bitową liczbą całkowitą ze znakiem w formacie ciągu znaków.
• Klucze agregacji (opcjonalnie): lista słowników określająca klucze agregacji i raporty agregujące, które mają mieć zagregowaną wartość.
• Wartości agregujące (opcjonalne): lista wartości, które składają się na każdy klucz.
• Filtry (opcjonalnie): służą do selektywnego filtrowania reguł lub danych reguł. Więcej informacji znajdziesz w sekcji Filtry wyzwalające na tej stronie.

Opcjonalnie odpowiedź serwera technologii reklamowych może zawierać dodatkowe dane w nagłówku Przekierowania raportowania atrybucji. Dane zawierają przekierowania, które umożliwiają wielu technikom reklamowym rejestrowanie żądań.

Wiele technologii reklamowych może rejestrować to samo zdarzenie wywoławcze, korzystając z przekierowań w polu Attribution-Reporting-Redirect lub z wielu wywołań metody registerTrigger(). Zalecamy używanie pola klucza deduplikacji, aby uniknąć uwzględniania w raportach duplikatów zdarzeń wyzwalających w przypadku, gdy ta sama technologia reklamowa dostarcza wiele odpowiedzi na to samo zdarzenie uruchamiające. Dowiedz się więcej o tym, jak i kiedy używać klucza do usuwania duplikatów.

Przewodnik dla programistów zawiera przykłady, które pokazują, jak zaakceptować rejestrację aktywatora.

Poniżej znajduje się przykładowy przepływ pracy:

1. Pakiet AdTech SDK wywołuje interfejs API, aby zainicjować rejestrację aktywatora za pomocą wstępnie zarejestrowanego identyfikatora URI. Więcej informacji znajdziesz w artykule Rejestracja na konto w Piaskownicy prywatności.

   registerTrigger(
       Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
   

2. Interfejs API wysyła żądanie do https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA.

3. Serwer HTTPS tej technologii reklamowej odpowiada z nagłówkami zawierającymi:

   Attribution-Reporting-Register-Trigger: {
       "event_trigger_data": [{
       "trigger_data": "1122",
       // This returns 010 for click-through conversions (CTCs) and 0 for
       // view-through conversions (VTCs) in reports
       "priority": "3",
       "deduplication_key": "3344"
       }],
   }
   Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567
   

   Uwaga: tylko technologia reklamowa, która inicjuje wywołanie interfejsu API, może określać partnerów w Attribution-Reporting-Redirect.

4. Interfejs API wysyła żądanie do każdego adresu URL określonego w Attribution-Reporting-Redirect. W tym przykładzie podano tylko 1 adres URL, więc interfejs API wysyła żądanie do adresu https://adtechpartner.example?app_install=567.

5. Serwer HTTPS tej technologii reklamowej odpowiada z nagłówkami zawierającymi:

   Attribution-Reporting-Register-Trigger: {
   "event_trigger_data":[{
     "trigger_data": "5566",
     "priority": "3",
     "deduplication_key": "3344"
   }]
   }
   

   Zostały zarejestrowane 2 aktywatory na podstawie żądań z poprzednich kroków.

Funkcje atrybucji

W sekcjach poniżej wyjaśniamy, jak interfejs Attribution Reporting API dopasowuje reguły konwersji do źródeł atrybucji.

Zastosowano algorytm atrybucji z priorytetem źródeł

Interfejs Attribution Reporting API korzysta z algorytmu atrybucji z uwzględnieniem priorytetów źródeł, aby dopasować zdarzenie (konwersję) do źródła atrybucji.

Parametry priorytetu umożliwiają dostosowywanie atrybucji reguł do źródeł:

• Możesz przypisać reguły do określonych zdarzeń reklamowych. Możesz np. zwracać większą uwagę na kliknięcia niż na wyświetlenia lub skupiać się na zdarzeniach z określonych kampanii.
• Możesz skonfigurować źródło i regułę atrybucji w taki sposób, aby po osiągnięciu limitów stawek zwiększyć prawdopodobieństwo otrzymywania raportów, które są dla Ciebie ważniejsze. Możesz na przykład zadbać o to, aby w tych raportach częściej pojawiały się konwersje z możliwością określenia stawki lub konwersje o wysokiej wartości.

Jeśli kilka usług reklamowych rejestruje źródło atrybucji, jak opisano dalej na tej stronie, atrybucja następuje niezależnie dla każdej z nich. W przypadku każdej usługi reklamowej źródło atrybucji o najwyższej priorytecie jest przypisywane do zdarzenia reguły. Jeśli istnieje wiele źródeł atrybucji o tym samym priorytecie, interfejs API wybiera ostatnie zarejestrowane źródło atrybucji. Pozostałe źródła atrybucji, które nie zostały wybrane, są odrzucane i nie można ich już użyć do atrybucji przyszłych reguł.

Filtry reguł

Rejestrowanie źródła i aktywatorów obejmuje dodatkowe opcjonalne funkcje umożliwiające:

• Wybiórczo filtruj aktywatory, aby je ignorować.
• Wybierz dane reguły na potrzeby raportów na poziomie zdarzenia na podstawie danych źródłowych.
• Wyklucz z raportów na poziomie zdarzenia wybrany przez siebie reguł.

Aby selektywnie filtrować reguły, technika reklamowa może podczas rejestracji źródła i wyzwalacza określić dane filtra, w tym klucze i wartości. Jeśli dla źródła i wyzwalacza określono ten sam klucz, aktywator jest ignorowany, gdy przecięcie jest puste. Na przykład źródło może zawierać wartość "product": ["1234"], gdzie product jest kluczem filtra, a 1234 wartością. Jeśli filtr reguły jest ustawiony na "product": ["1111"], reguła jest ignorowana. Jeśli nie ma klucza filtra reguł pasującego do reguły product, filtry są ignorowane.

Innym scenariuszem, w którym platformy adtech mogą selektywnie filtrować wyzwalacze, jest wymuszenie krótszego okna wygaśnięcia. Podczas rejestrowania reguły dostawca technologii reklamowych może określić (w sekundach) okres ważności od daty konwersji. Na przykład 7-dniowy okres ważności można zdefiniować w ten sposób: "_lookback_window": 604800 // 7d

Aby ustalić, czy filtr pasuje, interfejs API najpierw sprawdza okres sprawdzania wstecznego. Jeśli czas trwania od momentu zarejestrowania źródła jest dostępny, musi być krótszy od okresu ważności lub od niego równy.

Uwaga: opisana logika filtra okresu ważności i opisane funkcje zaczną obowiązywać w I kwartale 2012 r. Więcej informacji o czasie publikacji znajdziesz tutaj. Wcześniejsza logika wymagała, aby okresy ważności były określane co godzinę, zarówno po stronie źródła, jak i wyzwalacza. Ta zaktualizowana logika funkcji jest niezgodna wstecznie, co oznacza, że źródła używające poprzedniego klucza „_lookback_window” nie zostaną zarejestrowane.

Platformy technologii reklamowych mogą też wybierać dane reguł na podstawie danych zdarzeń źródłowych. Na przykład source_type jest automatycznie generowany przez interfejs API jako navigation lub event. Podczas rejestracji reguły trigger_data może być ustawiony jako jedna wartość dla "source_type": ["navigation"] i jako inna wartość dla "source_type": ["event"].

Reguły są wykluczane z raportów na poziomie zdarzenia, jeśli jest spełniony którykolwiek z tych warunków:

• Nie podano wartości trigger_data.
• Źródło i reguła określają ten sam klucz filtra, ale wartości nie są zgodne. Pamiętaj, że w tym przypadku reguła jest ignorowana zarówno w przypadku raportów na poziomie zdarzenia, jak i raportów zbiorczych.

Atrybucja po instalacji

W niektórych przypadkach wyzwalacze po instalacji muszą być przypisane do tego samego źródła atrybucji, które spowodowało instalację, nawet jeśli istnieją inne kwalifikujące się źródła atrybucji, które wystąpiły później.

Interfejs API może obsługiwać ten przypadek użycia, umożliwiając firmom zajmującym się technologiami reklamowymi ustawienie okresu atrybucji po instalacji:

• Podczas rejestrowania źródła atrybucji określ okno atrybucji instalacji, w którym mają się pojawić instalacje (zwykle 2–7 dni, dopuszczalny zakres: 1–30 dni). Określ to okno czasowe jako liczbę sekund.
• Podczas rejestrowania źródła atrybucji określ przedział wyłączności atrybucji po instalacji, w którym wszystkie zdarzenia aktywujące po instalacji powinny zostać powiązane ze źródłem atrybucji, które doprowadziło do instalacji (zazwyczaj 7–30 dni, akceptowany zakres od 0 do 30 dni). Podaj ten przedział czasu jako liczbę sekund.
• Interfejs Attribution Reporting API sprawdza, kiedy ma miejsce instalacja aplikacji, i wewnętrznie przypisuje instalację do źródła atrybucji, które ma pierwszeństwo przed źródłem. Instalacja nie jest jednak wysyłana do technologii reklamowych i nie jest uwzględniana w ograniczeniach stawek na platformach.
• W przypadku każdej pobranej aplikacji dostępna jest weryfikacja instalacji aplikacji.
• Wszystkie przyszłe reguły, które wystąpią w oknie atrybucji po instalacji, będą przypisywane do tego samego źródła atrybucji co zweryfikowana instalacja, o ile to źródło atrybucji będzie się kwalifikować.

W przyszłości możemy rozszerzyć projekt, aby uwzględnić bardziej zaawansowane modele atrybucji.

W tabeli poniżej znajdziesz przykład tego, jak technologie reklamowe mogą korzystać z atrybucji po instalacji. Załóżmy, że wszystkie źródła i wyzwalacze atrybucji są rejestrowane przez tę samą sieć reklamową i mają te same priorytety.

Zdarzenie	Dzień, w którym wystąpiło zdarzenie	Uwagi
Kliknij 1	1	Parametr install_attribution_window jest ustawiony na 172800 (2 dni), a post_install_exclusivity_window ma wartość 864000 (10 dni)
Zweryfikowana instalacja	2	Interfejs API przypisuje zweryfikowane instalacje, ale nie są one uważane za wyzwalacze. Dlatego na razie nie wysyłamy żadnych raportów.
Aktywator 1 (pierwsze uruchomienie)	2	Pierwsze uruchomienie reguły zarejestrowane przez technikę reklamową. W tym przykładzie jest to pierwsze uruchomienie, ale może to być dowolny typ reguły. Przypisany do kliknięcia 1 (odpowiada atrybucji zweryfikowanej instalacji).
Kliknij 2	4	Używa tych samych wartości dla install_attribution_window i post_install_exclusivity_window co kliknięcie 1
Aktywator 2 (po instalacji)	5	Druga reguła zarejestrowana przez technikę reklamową. W tym przykładzie odpowiada ona konwersjom dokonywanej po zainstalowaniu aplikacji, takiej jak zakup. Przypisany do kliknięcia 1 (odpowiada atrybucji zweryfikowanej instalacji). Klik 2 jest odrzucany i nie kwalifikuje się do przyszłej atrybucji.

Na tej liście znajdziesz dodatkowe uwagi dotyczące atrybucji po instalacji:

• Jeśli zweryfikowana instalacja nie nastąpi w ciągu liczby dni podanej w zasadzie install_attribution_window, atrybucja po instalacji nie zostanie zastosowana.
• Zweryfikowane instalacje nie są rejestrowane przez technologie reklamowe i nie są wysyłane w raportach. Nie są one wliczane do limitów liczby żądań związanych z technologią reklamową. Zweryfikowane instalacje służą tylko do identyfikowania źródła atrybucji, które zostało przypisane do danej instalacji.
• W przykładzie w poprzedniej tabeli reguła 1 i reguła 2 odpowiadają odpowiednio konwersji po pierwszym uruchomieniu aplikacji i konwersji po zainstalowaniu aplikacji. Platformy technologii reklamowych mogą jednak rejestrować dowolny typ wyzwalacza. Inaczej mówiąc, pierwsza reguła nie musi być regułą uruchamianą jako pierwszy.
• Jeśli po wygaśnięciu reguły post_install_exclusivity_window zarejestrowane zostanie więcej reguł, kliknięcie 1 nadal będzie kwalifikować się do atrybucji, o ile nie wygasło i nie osiągnęło jeszcze limitu liczby żądań.
  • Kliknięcie 1 może zostać odrzucone, jeśli zarejestrowane zostanie źródło atrybucji o wyższym priorytecie.
• Jeśli aplikacja reklamodawcy zostanie odinstalowana i ponownie zainstalowana, ponowna instalacja zostanie uznana za nową zweryfikowaną instalację.
• Jeśli kliknięcie 1 było zdarzeniem obejrzenia, to do tego kliknięcia nadal będą przypisywane zarówno zdarzenia „pierwszego uruchomienia”, jak i wyzwalacze po zainstalowaniu. API ogranicza atrybucję do 1 wyzwalacza na obejrzenie, z wyjątkiem atrybucji po instalacji, gdzie dozwolone są maksymalnie 2 wyzwalacze na obejrzenie. W przypadku atrybucji po instalacji technologia reklamowa mogła otrzymać 2 różne okresy raportowania (na 2 dni lub u źródła).

Obsługiwane są wszystkie kombinacje ścieżek aktywatorów internetowych i aplikacji

Interfejs Attribution Reporting API umożliwia atrybucję ścieżek aktywacji na pojedynczym urządzeniu z Androidem:

• App-to-app: użytkownik widzi reklamę w aplikacji, a potem realizuje konwersję w tej lub innej zainstalowanej aplikacji.
• Przejście z aplikacji do przeglądarki: użytkownik widzi reklamę w aplikacji, a potem dokonuje konwersji w przeglądarce mobilnej lub w aplikacji.
• Przejście z internetu do aplikacji: użytkownik widzi reklamę w przeglądarce mobilnej lub w aplikacji, a potem dokonuje konwersji w aplikacji.
• Web-to-web: użytkownik widzi reklamę w przeglądarce mobilnej lub aplikacji, a potem realizuje konwersję w tej samej przeglądarce lub w innej przeglądarce na tym samym urządzeniu.

Umożliwiamy przeglądarkom internetowym obsługę nowych funkcji udostępnianych w internecie, takich jak funkcje podobne do tych dostępnych w interfejsie Attribution Reporting API w Piaskownicy prywatności w internecie, który może wywoływać interfejsy API Androida w celu umożliwienia atrybucji w aplikacjach i internecie.

Dowiedz się, jakie zmiany muszą wprowadzić dostawcy technologii reklamowych i aplikacje, aby obsługiwać ścieżki aktywacji w celu pomiaru w aplikacji i internecie.

Przypisywanie priorytetów wielu wywołaniom dla jednego źródła atrybucji

Pojedyncze źródło atrybucji może prowadzić do uruchomienia wielu inicjatorów. Na przykład proces zakupu może obejmować wyzwalacz „instalacja aplikacji”, co najmniej 1 wyzwalacz „dodaj do koszyka” oraz wyzwalacz „zakup”. Każda reguła jest przypisywana do co najmniej jednego źródła atrybucji zgodnie z algorytmem atrybucji z priorytetem źródła, który opisano później na tej stronie.

Istnieją limity liczby reguł, które można przypisać do jednego źródła atrybucji. Więcej informacji znajdziesz w dalszej części tej strony, w sekcji o wyświetlaniu danych pomiarowych w raportach atrybucji. Jeśli masz wiele reguł, które przekraczają te limity, warto wprowadzić logikę priorytetów, aby zachować te reguły, które są najbardziej wartościowe. Na przykład deweloperzy technologii reklamowej mogą chcieć priorytetowo traktować wyzwalacze „zakup” zamiast wyzwalaczy „dodaj do koszyka”.

Aby umożliwić działanie tej logiki, w przypadku reguły można ustawić osobne pole priorytetu, a w danym oknie raportowania reguły o najwyższym priorytecie są wybierane przed zastosowaniem limitów.

Uwaga: wyzwalacze o niższym priorytecie, które zostały już zgłoszone, zawsze wykorzystują budżet.

Zezwalaj wielu technikom reklamowym na rejestrowanie źródeł lub reguł atrybucji

Zwykle raporty atrybucji otrzymuje więcej niż 1 technologia reklamowa, zwykle w celu przeprowadzania deduplikacji między sieciami. Dlatego interfejs API pozwala wielu technikom reklamowym zarejestrować to samo źródło lub regułę atrybucji. Aby otrzymywać wywołania zwrotne z interfejsu API, technologia reklamowa musi zarejestrować zarówno źródła atrybucji, jak i jej wyzwalacze. Atrybucja jest przeprowadzana w ramach źródeł atrybucji i wyzwalaczy zarejestrowanych przez technologię reklamową w interfejsie API.

Reklamodawcy, którzy chcą korzystać z usług zewnętrznych firm w celu przeprowadzania deduplikacji w różnych sieciach, mogą nadal to robić, stosując technikę podobną do tej:

• Skonfiguruj serwer wewnętrzny, aby rejestrować i odbierać raporty z interfejsu API.
• dalsze korzystanie z dotychczasowego partnera świadczącego usługi pomiarów na urządzeniach mobilnych,

Źródła atrybucji

Przekierowania źródeł atrybucji są obsługiwane w metodach registerSource():

1. Technologia reklamowa, która wywołuje metodę registerSource(), może w odpowiedzi podać dodatkowe pole Attribution-Reporting-Redirect, które reprezentuje zestaw adresów URL przekierowań tej technologii reklamowej.
2. Interfejs API wywołuje następnie przekierowania, aby źródła atrybucji mogły zostać zarejestrowane przez partnerów ds. techn reklamowych reklamowych.

W polu Attribution-Reporting-Redirect możesz podać wiele adresów URL technologii reklamowych partnerów, którzy nie mogą jednak określać własnych pól Attribution-Reporting-Redirect.

Interfejs API umożliwia też stosowanie różnych technologii reklamowych do poszczególnych wywołań registerSource().

Reguły

W przypadku rejestracji reguł firmy zewnętrzne są obsługiwane w podobny sposób: firmy zajmujące się technologiami reklamowymi mogą używać dodatkowego pola Attribution-Reporting-Redirect lub wywoływać metodę registerTrigger().

Jeśli reklamodawca używa wielu technologii reklamowych do rejestrowania tego samego zdarzenia uruchamiającego, powinien użyć klucza deduplikacji. Klucz deduplikacji służy do rozróżniania tych powtarzających się raportów o tym samym zdarzeniu zarejestrowanym przez tę samą platformę technologiczną reklam. Na przykład pakiet SDK może bezpośrednio wywoływać interfejs API w celu zarejestrowania reguły i umieścić adres URL w polu przekierowania wywołania innej technologii reklamowej. Jeśli nie podasz klucza deduplikacji, zduplikowane reguły mogą zostać zgłoszone do każdej technologii reklamowej jako unikalne.

Obsługa zduplikowanych reguł

Firma zajmująca się technologiami reklamowymi może zarejestrować ten sam element uruchamiający w interfejsie API wiele razy. Możliwe scenariusze:

• Użytkownik wykonuje to samo działanie (regułę) wiele razy. Na przykład użytkownik przegląda tę samą usługę wiele razy w tym samym oknie raportowania.
• Aplikacja reklamodawcy używa do pomiaru konwersji kilku pakietów SDK, które przekierowują do tej samej technologii reklamowej. Na przykład aplikacja reklamodawcy korzysta z 2 partnerów pomiarowych, MMP 1 i MMP 2. Obie platformy MMP przekierowują do technologii reklamowej nr 3. W przypadku reguły obie platformy MMP rejestrują ją za pomocą interfejsu Attribution Reporting API. Następnie usługa adtech 3 otrzymuje 2 osobne przekierowania – jedno z MMP 1 i jedno z MMP 2 – dla tego samego wyzwalacza.

W takich przypadkach możesz zablokować raporty na poziomie zdarzenia dotyczące duplikatów reguł, aby zmniejszyć prawdopodobieństwo przekroczenia limitów częstotliwości raportów na poziomie zdarzenia. Zalecanym sposobem jest użycie klucza do deduplikacji.

Zalecana metoda: klucz deduplikacji

Zalecaną metodą jest przekazanie przez aplikację reklamodawcy unikalnego klucza do usuwania duplikatów do wszystkich technologii reklamowych lub pakietów SDK, których używa do pomiaru konwersji. Gdy następuje konwersja, aplikacja przekazuje klucz usuwania duplikatów do technologii reklamowych lub pakietów SDK. Te technologie reklamowe lub pakiety SDK będą nadal przekazywać klucz deduplikacji do przekierowań, korzystając z parametru w adresach URL określonych w polu Attribution-Reporting-Redirect.

Specjaliści ds. technologii reklamowych mogą zarejestrować tylko pierwszą regułę z danym kluczem deduplikacji albo zarejestrować wiele reguł lub wszystkie reguły. Specjaliści ds. technologii reklamowych mogą podać wartość deduplication_key podczas rejestrowania zduplikowanych wyzwalaczy.

Jeśli usługa reklamowa rejestruje kilka wyzwalaczy z tym samym kluczem deduplikacji i przypisanym źródłem, w raportach na poziomie zdarzenia jest wysyłany tylko pierwszy zarejestrowany wyzwalacz. Zduplikowane aktywatory są nadal wysyłane w zaszyfrowanych raportach zbiorczych.

Metoda alternatywna: technologie reklamowe uzgadniają typy reguł reklamowych dla poszczególnych reklamodawców

W sytuacjach, gdy dostawcy technologii reklamowych nie chcą używać klucza do usuwania duplikatów lub gdy aplikacja reklamodawcy nie może przekazać klucza do usuwania duplikatów, dostępna jest inna opcja. Wszystkie technologie reklamowe, które mierzą konwersje dla danego reklamodawcy, muszą współpracować, aby zdefiniować różne typy reguł dla każdego reklamodawcy.

Technologie reklamowe, które inicjują wywołanie rejestracji wyzwalacza (np. pakiety SDK), zawierają parametr w adresach URL określonych w Attribution-Reporting-Redirect, np. duplicate_trigger_id. Parametr duplicate_trigger_id może zawierać takie informacje, jak nazwa pakietu SDK i typ reguły danego reklamodawcy. Następnie mogą wysyłać podzbiór tych duplikatów reguł do raportów na poziomie zdarzenia. Firmy technologiczne zajmujące się reklamami mogą też uwzględniać ten parametr duplicate_trigger_id w kluczach agregacji.

Przykład atrybucji międzysieciowej

W przykładzie opisanym w tej sekcji reklamodawca korzysta z 2 platform reklamowych (Ad tech A i Ad tech B) do wyświetlania reklam oraz z 1 partnera do pomiarów (MMP).

Aby zacząć korzystać z interfejsu Attribution Reporting API, technologia reklamowa A, technologia reklamowa B i MMP muszą się zarejestrować. Więcej informacji znajdziesz w artykule Zakładanie konta Piaskownicy prywatności.

Na liście poniżej znajdziesz hipotetyczną serię działań użytkowników, które będą realizowane 1 dzień, oraz sposób, w jaki interfejs Attribution Reporting API obsługuje te działania w odniesieniu do technologii reklamowej A, technologii reklamowej B i MMP:

Dzień 1: użytkownik klika reklamę wyświetlaną przez AdTech A

Technologia reklamowa A wywołuje metodę registerSource() za pomocą identyfikatora URI. Interfejs API wysyła żądanie do adresu URI, a kliknięcie jest rejestrowane z metadanymi z odpowiedzi serwera Ad tech A.

Technologia reklamowa A zawiera też identyfikator URI platformy MMP w nagłówku Attribution-Reporting-Redirect. Interfejs API wysyła żądanie do identyfikatora URI MMP i kliknięcie jest rejestrowane przy użyciu metadanych z odpowiedzi serwera MMP.

Dzień 2: użytkownik klika reklamę wyświetlaną przez AdTech B

Technologia reklamowa B wywołuje funkcję registerSource() za pomocą identyfikatora URI. Interfejs API wysyła żądanie do identyfikatora URI, a kliknięcie jest rejestrowane przy użyciu metadanych z odpowiedzi serwera usługi AdTech B.

Podobnie jak technologia reklamowa A, technologia reklamowa B również uwzględnia identyfikator URI platformy MMP w nagłówku Attribution-Reporting-Redirect. Interfejs API wysyła żądanie do identyfikatora URI MMP i kliknięcie jest rejestrowane przy użyciu metadanych z odpowiedzi serwera MMP.

Dzień 3. Użytkownik widzi reklamę wyświetlaną przez usługę Ad tech A.

Interfejs API reaguje tak samo jak pierwszego dnia, z tym że widok jest zarejestrowany dla usługi Ad tech A i MMP.

Dzień 4. Użytkownik instaluje aplikację, która do pomiaru konwersji używa MMP

MMP wywołuje metodę registerTrigger() za pomocą identyfikatora URI. Interfejs API wysyła żądanie do adresu URL, a konwersja jest rejestrowana z użyciem metadanych z odpowiedzi serwera MMP.

W nagłówku Attribution-Reporting-Redirect narzędzie MMP zawiera też identyfikatory URI technologii reklamowej A i techniki reklamowej B. Interfejs API wysyła żądania do serwerów Ad tech A i Ad tech B, a konwersja jest rejestrowana odpowiednio z metadanymi z odpowiedzi serwera.

Poniższy diagram przedstawia proces opisany na poprzedniej liście:

Przykład reakcji interfejsu Attribution Reporting API na serię działań użytkownika.

Atrybucja działa w ten sposób:

• Technologia reklamowa A przypisuje wyższy priorytet kliknięciom niż wyświetleniom, dlatego instalacja jest przypisywana do kliknięcia w Dzień 1.
• Technologia reklamowa B otrzymuje przypisaną instalację w dniu 2.
• MMP ustawia priorytet kliknięć nad liczbą wyświetleń i przypisuje instalację do kliknięcia drugiego dnia. Kliknięcie w drugim dniu ma najwyższy priorytet i najnowsze zdarzenie reklamowe.

Atrybucja międzysieciowa bez przekierowań

Chociaż zalecamy używanie przekierowań, aby umożliwić wielu technikom reklamowym rejestrowanie źródeł i reguł atrybucji, zdajemy sobie sprawę, że w niektórych sytuacjach używanie przekierowań nie jest możliwe. Z tej sekcji dowiesz się, jak obsługiwać atrybucję w wielu sieciach bez przekierowań.

Przepływ wysokiego poziomu

1. Podczas rejestracji źródła sieć technologii reklam wyświetlających reklamy udostępnia klucze agregacji źródła.
2. Podczas rejestracji reguły reklamodawca lub partner świadczący usługi pomiarowe wybiera, których elementów klucza po stronie źródła ma użyć, i określa ich konfigurację atrybucji.
3. Atrybucja jest ustalana na podstawie konfiguracji atrybucji, udostępnionych kluczy i źródeł, które zostały faktycznie zarejestrowane przez tego reklamodawcę lub partnera ds. pomiarów (np. z innej sieci reklamowej, która ma włączone przekierowania).
4. Jeśli reguła jest przypisana do źródła z technologii reklamowej wyświetlającej reklamy bez przekierowania, reklamodawca lub partner świadczący usługi pomiaru może otrzymać zbiorczy raport, który łączy źródło i aktywuje kluczowe elementy określone w kroku 2.

Rejestracja źródła

Podczas rejestracji źródła sieć technologii reklamowych, która wyświetla reklamy, może udostępnić źródłowe klucze agregacji lub podzbiór źródłowych kluczy agregacji zamiast przekierowania. Technologia reklamowa służąca do wyświetlania reklam nie musi używać tych kluczy źródeł w własnych raportach podlegających agregacji i może je deklarować tylko w imieniu reklamodawcy lub partnera ds. pomiarów (w razie potrzeby).

Udostępnione klucze agregacji są dostępne dla wszystkich usług reklamowych, które rejestrują wyzwalacz dla tego samego reklamodawcy. Jednak to na serwerach technologii reklamowej obsługującej reklamy i na serwerach technologii reklamowej obsługującej pomiary polegające na wywoływaniu akcji należy współpracować w zakresie tego, jakie typy kluczy agregacji są potrzebne, jakie są ich nazwy i jak dekodować klucze w czytelne wymiary.

Rejestracja wyzwalacza

Podczas rejestracji reguły usługa pomiarowa reklamy wybiera, które elementy klucza po stronie źródła mają być stosowane do poszczególnych elementów klucza reguły, w tym tych udostępnianych przez usługi pomiarowe reklamy.

Dodatkowo technologia reklam pomiarowych musi określić logikę atrybucji kaskadowej za pomocą nowego wywołania interfejsu API konfiguracji atrybucji. W tej konfiguracji technologia reklamowa może określić priorytet źródła, jego ważność i filtry dla źródeł, których nie widziała (np. źródeł, które nie korzystały z przekierowania).

Atrybucja

Interfejs Attribution Reporting API wykonuje przypisanie atrybucji ostatniego kontaktu z źródłem z uwzględnieniem priorytetu źródeł dla technologii pomiarowych na podstawie ich konfiguracji atrybucji, udostępnionych kluczy i wszystkich zarejestrowanych źródeł. Na przykład:

• Użytkownik kliknął reklamy wyświetlane przez technologie reklamowe A, B, C i D. Następnie użytkownik zainstalował aplikację reklamodawcy, która korzysta z usług partnera świadczącego usługi pomiaru skuteczności reklam (MMP).
• Technologia reklamowa A przekierowuje swoje źródła do platformy MMP.
• Technologie reklamowe B i C nie przekierowują, ale udostępniają klucze agregujące.
• Technologia reklamowa D nie przekierowuje ani nie udostępnia kluczy agregacji.

MMP rejestruje źródło z Techniki reklamowej A i definiuje konfigurację atrybucji, która obejmuje technologię reklamową B i technikę reklamową D.

Atrybucja MMP obejmuje teraz:

• Technologia reklamowa A, ponieważ MMP zarejestrował źródło z przekierowania tej technologii reklamowej.
• Ad tech B, ponieważ udostępnia klucze, a MMP uwzględnia je w konfiguracji atrybucji.

Atrybucja w MMP nie uwzględnia:

• Technologia reklamowa C, ponieważ MMP nie uwzględnił jej w konfiguracji atrybucji.
• Ad tech D, ponieważ nie przekierowywał ani nie udostępniał kluczy agregacji.

Uwaga: więcej informacji o wdrażaniu tego projektu znajdziesz w przewodniku dla deweloperów Attribution Reporting API.

Debugowanie

Aby ułatwić debugowanie atrybucji międzysieciowej bez przekierowań, dostępne jest dodatkowe pole shared_debug_key, które administratorzy technologii reklamowych mogą ustawić podczas rejestracji źródła. Jeśli zostanie ustawiony przy rejestracji pierwotnego źródła, zostanie też ustawiony w odpowiednim źródle pochodnym jako debug_key podczas rejestracji aktywatora na potrzeby atrybucji międzysieciowej bez przekierowań. Ten klucz debugowania jest dołączany jako source_debug_key w raportach zdarzeń i raportach zbiorczych.

Ta funkcja debugowania będzie obsługiwana tylko w przypadku atrybucji w wielu sieciach bez przekierowań w tych sytuacjach:

• Pomiar konwersji z aplikacji do aplikacji, w których dozwolony jest identyfikator AdId
• pomiar konwersji z aplikacji do witryny, gdy identyfikator AdId jest dozwolony i dopasowany zarówno do źródła aplikacji, jak i reguły w witrynie.
• pomiar danych z sieci (w tej samej przeglądarce), gdy ar_debug występuje zarówno w źródle, jak i w wyzwalaczu

Wykrywanie klucza na potrzeby atrybucji międzysieciowej bez przekierowań

Kluczowe odkrywanie ma usprawnić sposób, w jaki specjaliści ds. technologii reklamowych (zwykle MMP) wdrażają konfigurację atrybucji na potrzeby atrybucji międzysieciowej, gdy co najmniej 1 specjalistka ds. wyświetlania reklam korzysta ze wspólnych kluczy agregacji (jak opisano powyżej w sekcji Atrybucja międzysieciowa bez przekierowań).

Gdy MMP wysyła zapytanie do usługi agregacji w celu wygenerowania raportów zbiorczych dotyczących kampanii, które obejmują źródła pochodne, usługa agregacji wymaga, aby MMP podał listę możliwych kluczy jako dane wejściowe do zadania agregacji. W niektórych przypadkach lista potencjalnych kluczy agregacji źródeł może być bardzo długa lub nieznana. Duże listy możliwych kluczy są trudne do śledzenia, a ich przetwarzanie może być dość skomplikowane i kosztowne. Przyjrzyjmy się tym przykładom:

• Lista wszystkich możliwych kluczy jest długa:
  • Sieć reklamowa wyświetlająca reklamy realizuje złożoną inicjatywę pozyskiwania użytkowników, która obejmuje 20 kampanii, z których każda zawiera 10 grup reklam, a każda grupa reklam z 5 kreacjami, które są odświeżane co tydzień na podstawie skuteczności.
• Lista wszystkich możliwych kluczy jest nieznana:
  • Sieć reklamowa wyświetla reklamy w wielu aplikacjach mobilnych, w przypadku których pełna lista identyfikatorów aplikacji wydawcy nie jest znana w momencie rozpoczęcia kampanii.
  • Reklamodawca działa w różnych sieciach reklamowych, które nie przekierowują do MMP w momencie rejestracji źródła. Każda sieć reklamowa ma inną strukturę kluczy i wartości, których nie można z wyprzedzeniem udostępniać MMP.

Dzięki wprowadzeniu funkcji wykrywania słów kluczowych:

• Usługa do agregacji nie wymaga już pełnego wyliczenia możliwych kluczy agregacji.
• Zamiast podawać pełną listę możliwych kluczy, MMP może utworzyć pusty (lub częściowo pusty) zbiór kluczy i ustawić dla niego próg, dzięki czemu w wyniku będą uwzględniane tylko klucze (niezdeklarowane wstępnie) o wartościach przekraczających ten próg.
• MMP otrzymuje raport podsumowujący, który zawiera zniekształcone wartości w przypadku kluczy, których udział w wartościach przekracza ustawiony próg. Raport może też obejmować klucze, z którymi nie jest powiązany żaden faktyczny udział użytkowników i są pozbawione szumów.
• MMP używa pola x_network_bit_mapping podczas rejestracji reguły, aby ustalić, która technologia reklamowa odpowiada danemu kluczowi.
• Dzięki temu MMP może skontaktować się z odpowiednią technologią wyświetlania reklam, aby zrozumieć wartości w kluczu źródłowym.

Podsumowując, wykrywanie kluczy umożliwia MMP uzyskiwanie kluczy agregacji bez wiedzy o nich z wyprzedzeniem i unikanie przetwarzania dużej liczby kluczy źródłowych kosztem dodatkowego szumu.

Uwaga: ta funkcja jest na etapie propozycji i nie jest jeszcze dostępna do testowania. Czekamy na Twoją opinię i komentarze.

Przekierowania w łańcuchu połączeń

Dzięki podaniu wielu nagłówków Attribution-Reporting-Redirect w źródle lub odpowiedzi serwera HTTPS rejestracji aktywatora technologia reklamowa może używać interfejsu Attribution Reporting API do rejestracji wielu źródeł i aktywacji za pomocą jednego wywołania interfejsu API rejestracji.

W odpowiedzi serwera technologia reklamowa może też zawierać jeden nagłówek Location (przekierowanie 302) z adresem URL, który prowadzi do kolejnej rejestracji, do określonej liczby.

Oba typy nagłówków są opcjonalne i nie można podać żadnego, jeśli nie są potrzebne przekierowania. Możesz podać jeden lub oba typy nagłówków. W przypadku awarii sieci żądania rejestracji źródła i wyzwalacza (w tym przekierowania) są ponownie wysyłane. Liczba ponownych prób na żądanie jest ograniczona do stałej, aby uniknąć istotnego wpływu na urządzenie.

Przekierowania nie są akceptowane w przypadku funkcji registerWebSource i registerWebTrigger używanych przez przeglądarki. Więcej informacji znajdziesz w przewodniku po implementacji funkcji na potrzeby różnych przeglądarek i aplikacji.

Wyświetlanie danych pomiarowych w raportach atrybucji

Interfejs Attribution Reporting API umożliwia tworzenie tych typów raportów, które są opisane bardziej szczegółowo w dalszej części tej strony:

• Raporty na poziomie zdarzenia łączą konkretne źródło atrybucji (kliknięcie lub widok) z ograniczonymi fragmentami danych reguł wysokiej jakości.
• Raporty zbiorcze nie są koniecznie powiązane z konkretnym źródłem atrybucji. Te raporty zawierają bardziej szczegółowe dane o wyzwalaczach niż raporty na poziomie zdarzenia, ale są dostępne tylko w postaci zbiorczej.

Te 2 rodzaje raportów się uzupełniają i można ich używać jednocześnie.

Raporty na poziomie zdarzenia

Gdy wywołanie zostanie przypisane do źródła atrybucji, na urządzeniu jest generowany raport na poziomie zdarzenia i przechowywany do momentu, gdy można go przesłać z powrotem do adresu URL wywołania zwrotnego każdej firmy technologicznej w jednym z określionych okien czasowych na wysyłanie raportów, które są opisane bardziej szczegółowo dalej na tej stronie.

Raporty na poziomie zdarzenia są przydatne, gdy nie potrzebujesz wielu informacji o wyzwalaczu. Dane reguły na poziomie zdarzenia są ograniczone do 3 bitów danych reguły dotyczących kliknięć (co oznacza, że reguła może być przypisana do jednej z 8 kategorii) i 1 bita dotyczącego wyświetleń. Raporty na poziomie zdarzenia nie obsługują kodowania danych po stronie reguły o wysokiej jakości, takich jak określona cena czy czas reguły. Atrybucja odbywa się na urządzeniu, dlatego raporty na poziomie zdarzenia nie obsługują funkcji analitycznych na różnych urządzeniach.

Raport na poziomie zdarzenia zawiera takie dane jak:

• Miejsce docelowe: nazwa pakietu aplikacji reklamodawcy lub eTLD+1, gdzie wystąpiła reguła.
• Identyfikator źródła atrybucji: ten sam identyfikator źródła atrybucji, który został użyty do rejestracji źródła atrybucji
• Typ wyzwalacza: 1 lub 3 bity danych wyzwalacza o niskiej jakości, w zależności od typu źródła atrybucji.

Mechanizmy chroniące prywatność stosowane do wszystkich raportów

Podane niżej limity są stosowane po uwzględnieniu priorytetów źródeł i reguł atrybucji.

Ograniczenia liczby technologii reklamowych

Liczba techników reklamowych, które mogą rejestrować lub otrzymywać raporty z interfejsu API, są ograniczone. Aktualna propozycja:

• 100 technologii reklamowych ze źródłami atrybucji na {źródłową aplikację, aplikację docelową, 30 dni, urządzenie}.
• 10 technologii reklamowych z przypisanymi uruchamiaczami na {aplikacja źródłowa, aplikacja docelowa, 30 dni, urządzenie}.
• 20 technologii reklamowych może rejestrować pojedyncze źródło lub skonfigurowany przez siebie mechanizm atrybucji (za pomocą Attribution-Reporting-Redirect).

Limity liczby niepowtarzalnych miejsc docelowych

Te limity utrudniają specjalistom ds. technologii reklamowych łączenie się ze sobą, ponieważ wysyłają zapytania do dużej liczby aplikacji, aby zrozumieć, jak dany użytkownik korzysta z aplikacji.

• We wszystkich zarejestrowanych źródłach i w przypadku wszystkich technologii reklamowych interfejs API obsługuje maksymalnie 200 unikalnych miejsc docelowych na aplikację źródłową na minutę.
• W przypadku wszystkich zarejestrowanych źródeł w przypadku danej technologii reklamowej interfejs API obsługuje maksymalnie 50 unikalnych miejsc docelowych na aplikację źródłową na minutę. Ten limit zapobiega wykorzystaniu całego budżetu przez jedną technologię reklamową.

Nieaktualne źródła nie wliczają się do limitów liczby żądań.

1 źródło raportowania na źródłową aplikację dziennie

Dana platforma adtech może używać tylko jednego źródła raportowania do rejestrowania źródeł w aplikacji wydawcy w przypadku danego urządzenia w danym dniu. Ten limit liczby żądań uniemożliwia technikom reklamowym korzystanie z różnych źródeł raportowania w celu uzyskania dostępu do dodatkowego budżetu na potrzeby prywatności.

Rozważ następujący scenariusz, w którym pojedyncza technologia reklamowa chce użyć wielu źródeł raportowania, aby zarejestrować źródła w aplikacji wydawcy na 1 urządzeniu.

1. Źródło raportowania 1 technologii reklamowej A rejestruje źródło w aplikacji B
2. 12 godzin później system raportowania technologii reklamowej A 2 próbuje zarejestrować źródło w aplikacji B

Drugie źródło, czyli źródło raportowania 2 dla technologii reklamowych A, zostanie odrzucone przez interfejs API. Źródło raportowania 2 platformy AdTech A nie będzie mogło zarejestrować źródła na tym samym urządzeniu w aplikacji B do następnego dnia.

Limity czasu bezczynności i ograniczenia szybkości

Aby ograniczyć wyciek tożsamości użytkownika między parą {source, destination}, interfejs API ogranicza ilość wszystkich informacji wysyłanych w danym okresie przez użytkownika.

Obecna propozycja zakłada ograniczenie każdej firmy technologicznej do 100 przypisanych wyzwalaczy na {aplikacja źródłowa, aplikacja docelowa, 30 dni, urządzenie}.

Liczba unikalnych miejsc docelowych

Interfejs API ogranicza liczbę miejsc docelowych, które mogą być mierzone przez technologię reklamową. Im niższy limit, tym trudniej technologii reklamowej wykorzystać interfejs API do mierzenia aktywności użytkownika związanej z przeglądaniem, która nie jest powiązana z wyświetlanymi reklamami.

Obecna propozycja polega na ograniczeniu każdej technologii reklamowej do 100 różnych miejsc docelowych z istniejącymi źródłami na aplikację źródłową.

Mechanizmy ochrony prywatności stosowane w raportach na poziomie zdarzenia

Ograniczona wierność danych aktywatora

Interfejs API udostępnia 1 bit dla wyzwalaczy po obejrzeniu i 3 bity dla wyzwalaczy po kliknięciu. Źródła atrybucji nadal obsługują pełne 64 bity metadanych.

Należy sprawdzić, czy i w jaki sposób można ograniczyć informacje wyrażane w wyzwalaczach, aby działały one z ograniczoną liczbą bitów dostępnych w raportach na poziomie zdarzenia.

Ramy dla szumu w ramach prywatności różnicowej

Celem tego interfejsu API jest umożliwienie pomiaru na poziomie zdarzenia w celu spełnienia lokalnych wymagań dotyczących prywatności różnicowej przez wykorzystanie k-losowych odpowiedzi w celu wygenerowania zaszumionych danych wyjściowych dla każdego zdarzenia źródłowego.

Szum jest stosowany do określania, czy zdarzenie źródła atrybucji jest raportowane zgodnie z prawdą. Źródło atrybucji jest zarejestrowane na urządzeniu z prawdopodobieństwem $ 1-p $, że źródło atrybucji jest zarejestrowane w zwykły sposób, oraz $ p $, że urządzenie losowo wybiera spośród wszystkich możliwych stanów wyjściowych interfejsu API (w tym nie zgłasza żadnych fałszywych zgłoszeń ani nie zgłasza wielu fałszywych zgłoszeń).

Odpowiedź z k-losowaniem to algorytm, który jest epsilon-prywatny, jeśli zachodzi równość:

\[ p = \frac{k}{k + e^ε - 1} \]

W przypadku niskich wartości ε rzeczywisty wynik jest chroniony przez mechanizm odpowiedzi z losowym k. Dokładne parametry szumu są obecnie opracowywane i mogą ulec zmianie na podstawie opinii. Aktualna propozycja obejmuje:

• p=0,24% w przypadku źródeł nawigacji
• p=0,00025% dla źródeł zdarzeń

Limity dostępnych reguł (konwersji)

Istnieją limity liczby reguł na źródło atrybucji, a ich aktualna oferta obejmuje:

• 1–2 reguły dla źródeł atrybucji obejrzenia reklamy (2 reguły są dostępne tylko w przypadku atrybucji po instalacji)
• 3 reguły źródeł atrybucji reklam kliknięć

Uwaga: opisuje to domyślne działanie interfejsu API w przypadku liczby atrybucji na źródło korzystających z raportowania na poziomie zdarzenia. W październiku 2023 r. wprowadziliśmy elastyczne raportowanie na poziomie zdarzenia, dzięki czemu firmy technologiczne zajmujące się reklamami mogą teraz konfigurować ten wymiar swoich raportów na podstawie tego, co najlepiej pasuje do ich przypadku użycia.

Określone okna czasowe na wysyłanie raportów (zachowanie domyślne)

Raporty na poziomie zdarzenia dotyczące źródeł atrybucji wyświetleń reklam są wysyłane 1 godzinę po wygaśnięciu źródła. Datę wygaśnięcia można skonfigurować, ale nie może ona być krótsza niż 1 ani dłuższa niż 30 dni. Jeśli 2 reguły zostały przypisane do źródła atrybucji wyświetlenia reklamy (za pomocą atrybucji po instalacji), raporty na poziomie zdarzenia mogą być wysyłane w określonych interwałach czasu.

Raportów na poziomie zdarzenia dotyczących źródeł atrybucji kliknięć reklam nie można konfigurować. Są one wysyłane przed wygaśnięciem źródła lub w określonych momentach w zależności od tego, co nastąpi wcześniej. Czas pomiędzy źródłem atrybucji a wygaśnięciem jest dzielony na kilka okien raportowania. Każde okno raportowania ma termin (od czasu źródła atrybucji). Pod koniec każdego okresu raportowania urządzenie zbiera wszystkie wyzwalacze, które wystąpiły od poprzedniego okresu raportowania, i wysyła zaplanowany raport. Interfejs API obsługuje te okna raportowania:

• 2 dni: urządzenie zbiera wszystkie reguły, które wystąpiły maksymalnie 2 dni od zarejestrowania źródła atrybucji. Raport jest wysyłany po 2 dniach i 1 godzinie od zarejestrowania źródła atrybucji.
• 7 dni: urządzenie zbiera wszystkie reguły, które wystąpiły ponad 2 dni temu, ale nie później niż 7 dni od zarejestrowania źródła atrybucji. Raport jest wysyłany 7 dni i godzinę po zarejestrowaniu źródła atrybucji.
• Niestandardowy zakres czasu określony przez atrybut „expiry” źródła atrybucji. Raport jest wysyłany 1 godzinę po upływie określonego czasu ważności. Ta wartość nie może być mniejsza niż 1 dzień ani większa niż 30 dni.

Uwaga: ten artykuł opisuje domyślne zachowanie interfejsu API w oknach raportowania na poziomie zdarzenia. W październiku 2023 r. wprowadziliśmy elastyczne raportowanie na poziomie zdarzenia, dzięki czemu firmy technologiczne zajmujące się reklamami mogą teraz konfigurować ten wymiar raportowania na podstawie tego, co najlepiej pasuje do ich przypadku użycia.

Elastyczna konfiguracja na poziomie zdarzenia

Rekomendujemy, aby specjaliści ds. technologii reklamowych zaczęli używać domyślnej konfiguracji raportowania na poziomie zdarzenia, gdy rozpoczną testowanie użyteczności. Nie zawsze jest ona jednak odpowiednia do wszystkich przypadków użycia. Interfejs Attribution Reporting API będzie obsługiwać opcjonalne i bardziej elastyczne konfiguracje, dzięki którym specjaliści ds. technologii reklamowych będą mieli większą kontrolę nad strukturą raportów na poziomie zdarzenia i będą w stanie zmaksymalizować użyteczność danych.

Ta dodatkowa elastyczność zostanie wprowadzona w przypadku interfejsu Attribution Reporting API w 2 fazach:

• Etap 1. Elastyczna konfiguracja na poziomie zdarzenia w wersji lite
  • Ta wersja stanowi podzbiór wszystkich funkcji i można jej używać niezależnie od etapu 2.
• Etap 2. Pełna wersja elastycznej konfiguracji na poziomie zdarzenia

Etap 1 (poziom zdarzenia elastycznego Lite) można wykorzystać do:

• Zmiana częstotliwości raportów przez określenie liczby okresów raportowania
• Zmiana liczby atrybucji na rejestrację źródła
• Ogranicz ilość całkowitego szumu, zmniejszając powyższe parametry
• Konfigurowanie okien raportowania zamiast korzystania z domyślnych

Etap 2 (pełny elastyczny poziom zdarzenia) może być używany do wszystkich funkcji etapu 1, a także:

• Zmieniaj moc zbioru danych reguły w raporcie
• Ogranicz ilość całkowitego szumu, zmniejszając moc zbioru danych reguły

Zmniejszenie jednego wymiaru w konfiguracji domyślnej pozwala technologii reklamowej zwiększyć inny wymiar. Całkowita ilość szumu w raporcie na poziomie zdarzenia może też zostać zredukowana przez zmniejszenie wartości wspomnianych wyżej parametrów.

Oprócz dynamicznego ustawiania poziomów szumów na podstawie wybranej konfiguracji technologii reklamowej wprowadzimy pewne limity parametrów, aby uniknąć dużych kosztów obliczeń i konfiguracji z zbyt dużą liczbą stanów wyjściowych (gdzie szumy znacznie wzrosną). Oto przykładowy zestaw ograniczeń. Zachęcamy do przesyłania opinii na temat [projektu][50]:

• Maksymalnie 20 raportów ogółem, globalnie i na podstawie parametru trigger_data.
• Maksymalnie 5 możliwych okien raportowania na trigger_data
• Maksymalnie 32 moc zbioru danych aktywatora (nie dotyczy elastycznego poziomu zdarzenia Etap 1. Lite)

Gdy technicy reklamowe zaczną korzystać z tej funkcji, pamiętaj, że używanie wartości ekstremalnych może skutkować dużą ilością szumu lub niepowodzeniem rejestracji w przypadku nieosiągnięcia poziomów prywatności.

Uwaga: faza 1 (poziom zdarzenia Lite Flexible) została wydana w wersji beta w październiku 2023 r. Etap 2 (pełna elastyczność na poziomie zdarzenia) zostanie udostępniony w wersji beta w pierwszym kwartale 2024 r.

Raporty zbiorcze

Zanim zaczniesz korzystać z raportów możliwych do agregacji, musisz skonfigurować swoje konto w chmurze i rozpocząć otrzymywanie raportów możliwych do agregacji.

Raporty umożliwiające agregację zapewniają szybszy dostęp do danych o wyzwalaczach z urządzenia o wyższej jakości niż w przypadku raportów na poziomie zdarzenia. Te dane o wyższej jakości mogą być analizowane tylko w ujęciu zbiorczym i nie są powiązane z konkretnym wyzwalaczem ani użytkownikiem. Klucze agregacji mogą mieć maksymalnie 128 bitów, co pozwala raportom zbiorczym obsługiwać takie przypadki użycia jak:

• Raporty dotyczące wartości reguł, takich jak przychody
• Obsługa większej liczby typów reguł

Raporty agregowane korzystają z tego samego modelu atrybucji z priorytetem źródła co raporty na poziomie zdarzenia, ale obsługują więcej konwersji przypisanych do kliknięcia lub wyświetlenia.

Ogólny schemat sposobu, w jaki interfejs Attribution Reporting API przygotowuje i wysyła raporty agregowane, przedstawia schemat:

1. Urządzenie wysyła zaszyfrowane, zbiorcze raporty do zespołu technicznego reklam. W środowisku produkcyjnym technologie reklamowe nie mogą korzystać z tych raportów bezpośrednio.
2. Technologia reklamowa wysyła do usługi agregacji zestaw raportów możliwych do zsumowania w celu ich zsumowania.
3. Usługa agregacji odczytuje zbiorczy zestaw raportów, odszyfruje je i zbiorczo je zsumuje.
4. Ostateczne dane zbiorcze są wysyłane z powrotem do firmy zajmującej się technologią reklamową w raporcie podsumowaniu.

Proces, którego używa Attribution Reporting API do przygotowywania i wysyłania raportów możliwych do agregacji.

Raporty umożliwiające agregację zawierają te dane związane ze źródłami atrybucji:

• Miejsce docelowe: nazwa pakietu aplikacji lub adres URL witryny eTLD+1, w której wystąpił wyzwalacz.
• Data: data wystąpienia zdarzenia reprezentowanego przez źródło atrybucji.
• Ładunek: wartości aktywatorów, zbierane jako zaszyfrowane pary klucz-wartość, które są używane w zaufanej usłudze agregacji do obliczania agregacji.

Usługi agregacji

Poniższe usługi umożliwiają agregację i pomagają chronić dane agregacji przed nieuprawnionym dostępem.

Te usługi są zarządzane przez różne podmioty, które są opisane bardziej szczegółowo na tej stronie:

• Usługa agregacji jest jedyną usługą, którą firmy technologiczne zajmujące się reklamami powinny wdrożyć.
• Usługi zarządzania kluczami i raportowania z możliwością agregacji są obsługiwane przez zaufane podmioty zwane koordynatorami. Koordynatorzy ci potwierdzają, że kod uruchamiający usługę agregacji to publicznie dostępny kod udostępniany przez Google oraz że wszyscy użytkownicy tej usługi mają ten sam klucz i usługi księgowania raportów agregowanych.

Usługa agregacji

Platformy technologii reklamowych muszą z wyprzedzeniem wdrożyć usługę agregacji opartą na plikach binarnych dostarczonych przez Google.

Ta usługa agregacji działa w zaufanym środowisku wykonawczym (TEE) hostowanym w chmurze. TEE zapewnia te korzyści związane z bezpieczeństwem:

• Dzięki temu kod działający w TEE to konkretny plik binarny oferowany przez Google. Jeśli ten warunek nie zostanie spełniony, usługa agregacji nie może uzyskać dostępu do kluczy odszyfrowywania, których potrzebuje do działania.
• Zapewnia bezpieczeństwo podczas trwającego procesu i odizoluje go od monitorowania lub ingerencji z zewnątrz.

Te korzyści w zakresie bezpieczeństwa zwiększają bezpieczeństwo usługi agregacji przy wykonywaniu poufnych operacji, takich jak dostęp do zaszyfrowanych danych.

Więcej informacji o projektowaniu, przepływie pracy i o zabezpieczeniach usługi agregacji znajdziesz w dokumentacji usługi agregacji na GitHub.

System zarządzania kluczami (KMS)

Ta usługa sprawdza, czy usługa agregacji korzysta z zatwierdzonej wersji pliku binarnego, a potem udostępnia tej usłudze w technologii reklamowej odpowiednie klucze odszyfrowywania danych wyzwalacza.

Uwzględnianie w raportach agregowanych

Ta usługa śledzi, jak często usługa agregacji firmy zajmującej się technologiami reklamowymi uzyskuje dostęp do określonego reguły, która może zawierać wiele kluczy agregacji, i ogranicza dostęp do odpowiedniej liczby odszyfrowań. Więcej informacji znajdziesz w propozycji projektu usługi agregacji interfejsu Attribution Reporting API.

Interfejs API do agregacji raportów

Interfejs API służący do tworzenia danych do raportów zbiorczych korzysta z tego samego podstawowego interfejsu API co w przypadku rejestrowania źródła atrybucji na potrzeby raportów na poziomie zdarzenia. W dalszej części tego artykułu znajdziesz opis rozszerzeń interfejsu API.

Rejestrowanie danych źródłowych możliwych do zsumowania

Gdy interfejs API wysyła żądanie do identyfikatora URI źródła atrybucji, technologia reklamowa może zarejestrować listę kluczy agregacji o nazwie histogram_contributions, odpowiadając nowym polem o nazwie aggregation_keys w nagłówku HTTP Attribution-Reporting-Register-Source, w którym kluczem jest key_name, a wartością key_piece:

• (Klucz) Nazwa klucza: ciąg znaków nazwy klucza. Służy jako klucz łączenia, który łączy się z kluczami po stronie wyzwalacza, tworząc klucz końcowy.
• (Wartość) Klucz: wartość ciągów bitowych klucza.

Ostateczny klucz zasobnika histogramu jest w pełni zdefiniowany w czasie aktywatora przez wykonanie operacji binarnej LUB na tych częściach i częściach po stronie aktywatora.

Klucze końcowe są ograniczone do maksymalnie 128 bitów; klucze dłuższe są obcinane. Oznacza to, że ciągi szesnastkowe w pliku JSON powinny być ograniczone do 32 cyfr.

Dowiedz się więcej o strukturze kluczy agregacji i o ich konfigurowaniu.

W tym przykładzie technologia reklamowa używa interfejsu API do zbierania tych danych:

• Agregować liczbę konwersji na poziomie kampanii
• Zbiorcze wartości zakupów na poziomie geograficznym

// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

Zarejestruj agregacyjny regułę.

Rejestracja reguły zawiera 2 pola dodatkowe.

Pierwsze pole służy do rejestrowania listy kluczy agregacji po stronie reguły. Technologia reklamowa powinna odpowiedzieć, podając w polu aggregatable_trigger_data nagłówka HTTP Attribution-Reporting-Register-Trigger te pola dla każdego klucza zbiorczego na liście:

• Element klucza: wartość ciągu bitów klucza.
• Klucze źródłowe: lista ciągów z nazwami pobocznych kluczy źródła atrybucji, z którymi należy połączyć klucz reguły, by utworzyć klucze końcowe.

Drugie pole służy do rejestrowania listy wartości, które powinny być uwzględniane w każdym kluczu. Dostawca technologii reklamowych powinien odpowiedzieć, przesyłając pole aggregatable_values w nagłówku HTTP Attribution-Reporting-Register-Trigger. Drugie pole służy do rejestrowania listy wartości, które powinny być uwzględniane w przypadku każdego klucza. Mogą to być liczby całkowite z zakresu $ [1, 2^{16}] $.

Każdy z nich może mieć wpływ na wiele raportów podlegających agregacji. Całkowita liczba udziałów w danym zdarzeniu źródłowym jest ograniczona parametrem $L1$, który jest maksymalną sumą udziałów (wartości) we wszystkich kluczach agregacji dla danego źródła. $ L1 $ odnosi się do czułości lub normy udziału histogramu na zdarzenie źródłowe. Jeśli przekroczysz te limity, przyszłe treści będą pojawiać się dyskretnie. Wstępna propozycja to ustawienie $L1$ na $2^{16}$ (65536).

Szum w usłudze agregacji jest skalowany proporcjonalnie do tego parametru. W związku z tym zalecamy odpowiednie dostosowanie wartości raportowanych dla danego klucza agregacji na podstawie przypisanej mu części budżetu L1. Dzięki temu raporty zbiorcze zachowują najwyższą możliwą dokładność po zastosowaniu szumu. Ten mechanizm jest bardzo elastyczny i może obsługiwać wiele strategii agregacji.

W tym przykładzie budżet prywatności jest dzielony po równo między campaignCounts i geoValue przez podzielenie udziału $L1$ na te dwa elementy:

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

Poprzedni przykład generuje te dane na histogram:

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

Uwaga: filters nadal działa w przypadku raportów podlegających agregacji, a w przypadku każdego słownika w aggregatable_trigger_data można opcjonalnie stosować filtry konwersji, podobnie jak filtry reguł w przypadku raportów na poziomie zdarzenia.

Aby uzyskać prawidłowe wartości, współczynniki skalowania można odwrócić, stosując odpowiedni hałas:

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

Prywatność różnicowa

Celem tego interfejsu API jest stworzenie platformy, która będzie obsługiwać prywatne pomiary zbiorcze z różnymi poziomami szczegółowości. Można to osiągnąć, dodając szum proporcjonalny do budżetu $L1$, np. wybierając szum o tej dystrybucji:

\[ Laplace(\frac{L1}{ε}) \]

Integracja Protected Audience API z Attribution Reporting API

Integracja różnych interfejsów API w ramach interfejsów Protected Audience API oraz Attribution Reporting API pozwala firmom reklamowym ocenić skuteczność atrybucji w różnych taktykach remarketingowych i dowiedzieć się, które typy odbiorców zapewniają najwyższy ROI.

Dzięki integracji różnych interfejsów API Adtechs może:

• Utwórz mapę identyfikatorów URI, która będzie służyć do: 1) raportowania interakcji i 2) rejestracji źródeł.
• uwzględnić CustomAudience w mapowaniu klucza po stronie źródła na potrzeby zbiorczego raportowania podsumowania (za pomocą interfejsu Attribution Reporting API).

Gdy użytkownik widzi lub klika reklamę:

• Adres URL używany do raportowania tych interakcji za pomocą interfejsu Protected Audience API posłuży też do zarejestrowania obejrzenia lub kliknięcia jako kwalifikującego się źródła w interfejsie Attribution Reporting API.
• Technologia reklamowa może zdecydować się na przekazywanie za pomocą tego adresu URL niestandardowych informacji o odbiorcach (lub innych istotnych informacji kontekstowych o reklamie, takich jak miejsce docelowe reklamy lub czas oglądania). Dzięki temu te metadane mogą zostać przeniesione do raportów podsumowujących, gdy technologia reklamowa sprawdza zbiorczą skuteczność kampanii.

Więcej informacji o tym, jak włączyć tę funkcję w Protected Audience, znajdziesz w odpowiedniej sekcji artykułu o Protected Audience API.

Przykłady priorytetów rejestracji, atrybucji i raportowania

Ten przykład pokazuje zbiór interakcji użytkowników oraz to, jak technologie reklamowe definiujące źródło atrybucji i priorytety reguł mogą wpłynąć na przypisane raporty. W tym przykładzie zakładamy, że:

• Wszystkie źródła i reguły atrybucji są rejestrowane przez tę samą technologię reklamową dla tego samego reklamodawcy.
• Wszystkie źródła i wyzwalacze atrybucji działają w pierwszym oknie raportowania zdarzeń (w ciągu 2 dni od pierwszego wyświetlenia reklamy w aplikacji wydawcy).

Weź pod uwagę sytuację, w której użytkownik wykonuje te czynności:

1. Użytkownik widzi reklamę. Technologie reklamowe rejestrują w interfejsie API źródło atrybucji z priorytetem 0 (widok 1).
2. Użytkownik widzi reklamę zarejestrowaną z priorytetem 0 (wyświetlenie 2).
3. Użytkownik klika reklamę zarejestrowaną z priorytetem 1 (kliknięcie 1).
4. Użytkownik dokonuje konwersji (czyli dociera do strony docelowej) w aplikacji reklamodawcy. Technologia reklamowa rejestruje w interfejsie API regułę o priorytecie 0 (konwersja 1).
   • Gdy rejestrujesz wyzwalacze, interfejs API najpierw wykonuje atrybucję, a potem generuje raporty.
   • Dostępne są 3 źródła atrybucji: widok 1, widok 2 i kliknięcie nr 1. Interfejs API przypisuje ten bodziec do kliknięcia 1, ponieważ ma najwyższy priorytet i jest najnowszy.
   • Widok 1 i widok 2 są odrzucane i nie można ich już uwzględniać w przypisaniu.
5. Użytkownik dodaje produkt do koszyka w aplikacji reklamodawcy zarejestrowanej z priorytetem 1 (konwersja 2).
   • Kliknięcie 1 jest jedynym kwalifikującym się źródłem atrybucji. Interfejs API przypisuje ten element do kliknięcia 1.
6. Użytkownik dodaje produkt do koszyka w aplikacji reklamodawcy zarejestrowanym z priorytetem 1 (konwersja 3).
   • Kliknięcie 1 jest jedynym kwalifikującym się źródłem atrybucji. Interfejs API przypisuje ten wyzwalacz do kliknięcia nr 1.
7. Użytkownik dodaje produkt do koszyka w aplikacji reklamodawcy zarejestrowanej z priorytetem 1 (konwersja 4).
   • Kliknięcie 1 jest jedynym kwalifikującym się źródłem atrybucji. Interfejs API przypisuje ten element do kliknięcia 1.
8. Użytkownik dokonuje zakupu w aplikacji reklamodawcy, który został zarejestrowany z priorytetem 2 (konwersja 5).
   • Kliknięcie 1 jest jedynym kwalifikującym się źródłem atrybucji. Interfejs API przypisuje ten wyzwalacz do kliknięcia nr 1.

Raporty na poziomie zdarzenia mają te cechy:

• Domyślnie pierwsze 3 wyzwalacze przypisane do kliknięcia i pierwszy wyzwalacz przypisany do wyświetlenia są wysyłane po odpowiednich okresach raportowania.
• Jeśli w okresie raportowania jakieś reguły są zarejestrowane o wyższym priorytecie, będą one miały pierwszeństwo i zastąpią najnowszą regułę.
• W poprzednim przykładzie technologia reklamowa otrzymuje 3 raporty zdarzeń po 2-dniowym oknie raportowania: konwersja nr 2, konwersja nr 3 i konwersja 5.
  • Wszystkie te 5 reguł są przypisane do kliknięcia nr 1. Domyślnie interfejs API wysyła raporty dotyczące pierwszych 3 reguł: konwersji nr 1, konwersji nr 2 i konwersji nr 3.
  • Priorytet konwersji 4 (1) jest jednak wyższy niż priorytet konwersji 1 (0). Raport o zdarzeniu konwersji 4 zastąpi wysyłany raport o zdarzeniu konwersji 1.
  • Poza tym priorytet konwersji nr 5 (2) jest wyższy niż jakiejkolwiek innej reguły. Raport o zdarzeniach konwersji nr 5 zastępuje raport konwersji nr 4, który ma zostać wysłany.

Raporty agregowane charakteryzują się tymi cechami:

• Zaszyfrowane raporty podlegające agregacji są wysyłane do technologii reklamowej od razu po przetworzeniu, czyli kilka godzin po zarejestrowaniu reguł.

  Jako dostawca technologii reklamowych tworzysz ich partie na podstawie informacji, które są odszyfrowane w raportach możliwych do zagregowania. Informacje te są zawarte w polu shared_info raportu skumulowanego i obejmują sygnaturę czasową oraz źródło raportowania. Nie możesz tworzyć zbiorczych operacji na podstawie zaszyfrowanych informacji w parach klucz-wartość w Twoim zbiorze. Możesz np. tworzyć zbiorcze raporty codziennie lub co tydzień. Najlepiej, jeśli partie zawierają co najmniej 100 raportów.

• To technologia reklamowa o tym, kiedy i jak grupować raporty agregowane i wysyłać je do usługi agregacji.

• W porównaniu do raportów na poziomie zdarzenia zaszyfrowane raporty agregowane mogą przypisywać do źródła więcej reguł.

• W poprzednim przykładzie wysyłanych jest 5 raportów zbiorczych, po 1 na każdą zarejestrowaną regułę.

Raporty dotyczące debugowania przejściowych

Attribution Reporting API to nowy, dość złożony sposób mierzenia atrybucji bez identyfikatorów w różnych aplikacjach. W związku z tym obsługujemy mechanizm przejściowy umożliwiający uzyskiwanie dodatkowych informacji o raportach atrybucji, gdy dostępny jest identyfikator wyświetlania reklam (użytkownik nie zrezygnował z personalizacji za pomocą identyfikatora wyświetlania reklam, a aplikacja wydawcy lub reklamodawcy zadeklarowała uprawnienia AdID). Dzięki temu interfejs API będzie w pełni zrozumiały podczas wdrażania, pomoże wyeliminować błędy i ułatwi porównywanie skuteczności z rozwiązaniami alternatywnymi opartymi na identyfikatorze reklamy. Istnieją 2 typy raportów debugowania: raport o sukcesie atrybucji i raport szczegółowy.

Szczegółowe informacje o debugowaniu raportów z pomiarami danych między aplikacją a aplikacją, znajdziesz w przewodniku po raportach debugowania.

Raporty z debugowania o sukcesie atrybucji

Rejestracje źródła i wyzwalacza akceptują nowe 64-bitowe pole debug_key (sformatowane jako ciąg znaków), które jest wypełniane przez technologię reklamową. Wartości source_debug_key i trigger_debug_key są przekazywane bez zmian zarówno w raportach zbiorczych, jak i na poziomie zdarzenia.

Jeśli raport jest tworzony przy użyciu zarówno kluczy debugowania źródła, jak i kluczy debugowania reguły, do punktu końcowego .well-known/attribution-reporting/debug/report-event-attributionzostaje wysłany duplikat raportu debugowania z ograniczonym opóźnieniem. Raporty debugowania są identyczne z normalnymi raportami, w tym w przypadku pól klucza debugowania. Uwzględnienie tych kluczy w obu tych miejscach pozwala powiązać zwykłe raporty z osobnym strumieniem raportów na temat debugowania.

• W przypadku raportów na poziomie zdarzenia:
  • Powtarzające się raporty debugowania są wysyłane z niewielkim opóźnieniem, dlatego nie są pomijane przez ograniczenia dotyczące dostępnej liczby wyzwalaczy. Dzięki temu dostawcy technologii reklamowych mogą lepiej zrozumieć wpływ tych ograniczeń na raporty na poziomie zdarzenia.
  • Raporty na poziomie zdarzenia powiązane z fałszywymi zdarzeniami aktywacji nie będą zawierać kolumny trigger_debug_key. Dzięki temu dostawcy technologii reklamowych mogą dokładniej zrozumieć, jak działa szum w interfejsie API.
• W przypadku raportów agregowanych:
  • Nowe pole debug_cleartext_payload, które zawiera odszyfrowany ładunek, będzie obsługiwane tylko wtedy, gdy pola source_debug_key i trigger_debug_key są skonfigurowane.

szczegółowe raporty z debugowania,

Szczegółowe raporty debugowania umożliwiają deweloperom monitorowanie niektórych błędów w źródle atrybucji lub rejestracji zdarzeń. Te raporty debugowania są wysyłane z niewielkim opóźnieniem po rejestracji źródła atrybucji lub wyzwalacza.Punkt końcowy well-known/attribution-reporting/debug/verbose.

Każdy raport szczegółowy zawiera te pola:

• Typ: przyczyna wygenerowania raportu. Zobacz pełną listę szczegółowych typów raportów.
  • Ogólnie istnieją szczegółowe raporty źródłowe i szczegółowe raporty wyzwalaczy.
  • Pełne raporty źródłowe wymagają udostępnienia identyfikatora wyświetlania reklam aplikacji wydawcy, a generujące raporty szczegółowe wymagają udostępnienia identyfikatora wyświetlania reklam aplikacji reklamodawcy.
  • Raporty szczegółowe (z wyjątkiem raportu trigger-no-matching-source) mogą opcjonalnie zawierać informacje source_debug_key. Ten identyfikator można uwzględnić tylko wtedy, gdy identyfikator wyświetlania reklam jest też dostępny w aplikacji wydawcy.
• Treść: treść raportu, która zależy od jego typu.

Specjaliści ds. technologii reklamowych muszą wyrazić zgodę na otrzymywanie szczegółowych raportów debugowania za pomocą nowego pola słownika debug_reporting w nagłówkach Attribution-Reporting-Register_Source i Attribution-Reporting-Register-Trigger.

• Szczegółowe raporty źródłowe wymagają zaakceptowania tylko w nagłówku rejestracji źródła.
• Raporty na temat debugowania reguły wymagają wyrażenia zgody tylko w nagłówku rejestracji aktywatora.

Jak korzystać z raportów debugowania

Jeśli miała miejsce konwersja (zgodnie z obecnym systemem pomiarowym) i otrzymano dla niej raport debugowania, oznacza to, że reguła została zarejestrowana.

W przypadku każdego raportu atrybucji debugowania sprawdź, czy otrzymujesz zwykły raport atrybucji, który pasuje do 2 kluczy debugowania.

Brak dopasowania może być spowodowany wieloma czynnikami.

Działa zgodnie z oczekiwaniami:

• Zachowania interfejsu API chroniące prywatność:
  • Użytkownik osiąga limit częstotliwości raportowania, co powoduje, że wszystkie kolejne raporty nie są wysyłane w danym okresie. Źródło może zostać usunięte z powodu limitu oczekujących miejsc docelowych.
  • W przypadku raportów na poziomie zdarzenia: raport podlega losowej odpowiedzi (szumie) i jest pomijany lub możesz otrzymać raport losowy.
  • W przypadku raportów na poziomie zdarzenia: osiągnięto limit 3 raportów (w przypadku kliknięć) lub 1 raportu (w przypadku wyświetleń), a kolejne raporty nie mają określonego priorytetu lub mają priorytet niższy niż istniejące raporty.
  • Przekroczono limity udziału w raportach agregowanych.
• Logika biznesowa zdefiniowana przez technologię reklamową:
  • Wyzwalacz jest odfiltrowywany za pomocą filtrów lub reguł z priorytetem.
• opóźnienia lub interakcje z dostępem do sieci (np. wyłączenie urządzenia na dłuższy czas);

Niezamierzone przyczyny:

• Problemy z implementacją:
  • Nagłówek źródłowy jest nieprawidłowo skonfigurowany.
  • Nieprawidłowo skonfigurowano nagłówek reguły.
  • inne problemy z konfiguracją.
• Problemy z urządzeniem lub siecią:
  • Awarie z powodu warunków sieciowych.
  • Odpowiedź na rejestrację źródła lub reguły nie dociera do klienta.
  • Błąd interfejsu API.

Kwestie na przyszłość i pytania otwarte

Interfejs Attribution Reporting API jest w trakcie tworzenia. Rozważamy też potencjalne funkcje na przyszłość, takie jak modele atrybucji niezwiązanej z ostatnim kliknięciem i przypadki użycia pomiarów na różnych urządzeniach.

Chcielibyśmy też poznać opinie społeczności na temat kilku problemów:

1. Czy są jakieś przypadki użycia, w których interfejs API ma wysyłać raporty o zweryfikowanej instalacji? Raporty te uwzględniałyby limity liczby żądań na platformach technologii reklamowych.
2. Czy przewidujesz jakieś trudności z przekazaniem InputEvent z aplikacji do technologii reklamowych na potrzeby rejestracji źródła?
3. Czy masz jakieś szczególne przypadki atrybucji w przypadku wstępnie zainstalowanych lub ponownie zainstalowanych aplikacji?