Omówienie raportu Atrybucja na urządzeniach mobilnych

Ostatnie aktualizacje

  • Zaktualizowaliśmy listę nadchodzących zmian i znanych problemów.

  • Wprowadziliśmy konfigurację na poziomie zdarzenia w wersji lite, która stanowi przejście do pełnej konfiguracji na poziomie zdarzenia w wersji lite.

  • Od września 2023 r. funkcje registerWebSource, registerWebTrigger, registerAppSource i registerAppTrigger muszą używać ciągów znaków w polach, które oczekują wartości liczbowej (takich jak priority, source_event_id, debug_key, trigger_data, deduplication_key itp.).

  • 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 wdrożeniowym.

  • Nowe limity stawek zapewniające ochronę prywatności w przypadku liczby unikalnych miejsc docelowych.

  • Zaktualizowana funkcjonalność filtrów reguł okresu ważności wstecz zostanie wprowadzona w I kwartale 2024 r. Więcej informacji znajdziesz w notatce.

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 te mechanizmy strukturalne, które stanowią podstawę do poprawy prywatności:

Powyższe mechanizmy ograniczają możliwość łączenia tożsamości użytkownika w 2 różnych aplikacjach lub domenach.

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

  • Raportowanie konwersji: pomaga reklamodawcom mierzyć skuteczność ich kampanii poprzez wyświetlanie liczby i wartości konwersji (wyzwalaczy) w różnych wymiarach, np. według kampanii, grupy reklam i elementu 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: podaj raporty, 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. Firma zajmująca się technologiami reklamowymi kończy proces rejestracji, aby korzystać z interfejsu Attribution Reporting API.
  2. Technologia reklamowa rejestruje źródła atrybucji (kliknięcia lub wyświetlenia reklam) za pomocą interfejsu 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 (atrybucja konwersji), a co najmniej 1 regułę wysyła poza urządzenie w raportach na poziomie zdarzenia i zbiorcze do technologii reklamowych.

Uzyskiwanie dostępu 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ęcia lub wyświetlenia)

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 funkcję 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ścia: obiekt InputEvent (w przypadku zdarzenia kliknięcia) lub null (w przypadku zdarzenia wyświetlenia).

Gdy interfejs API wysyła żądanie do identyfikatora URI źródła atrybucji, technologia reklamowa powinna odpowiedzieć metadanymi źródła atrybucji w nowym nagłówku HTTP Attribution-Reporting-Register-Source, który zawiera 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: domena eTLD+1 lub nazwa pakietu aplikacji, w której ma miejsce zdarzenie uruchamiające.
  • Czas ważności (opcjonalnie): czas ważności (w sekundach), po którym źródło powinno zostać usunięte z urządzenia. Wartość domyślna to 30 dni, a wartość minimalna i maksymalna to 1 dzień. 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 okno raportowania zdarzeń upłynęło, ale jeszcze nie upłynął termin ważności, reguła może być nadal dopasowywana do źródła, ale raport o zdarzeniu nie jest wysyłany. Nie może być większa niż data ważności. Może być sformatowany jako 64-bitowa liczba całkowita bez znaku 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ększa niż data ważności. Może być sformatowany jako 64-bitowa liczba bez znaku 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ższy priorytet.
  • Okna atrybucji instalacji i okresu po instalacji (opcjonalnie): służą do określania atrybucji zdarzeń po instalacji, które są opisane dalej na tej stronie.
  • 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 agregacyjnych.

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.

W przewodniku dla programistów znajdziesz przykłady akceptowania rejestracji źródła.

Poniżej znajdziesz przykładowy proces:

  1. Pakiet SDK technologii reklamowej wywołuje interfejs API, aby zainicjować rejestrację źródła atrybucji, podając identyfikator 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 interfejsuhttps://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA, używając 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 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 podanego w pliku Attribution-Reporting-Redirect. W tym przykładzie podano 2 adresy URL partnera technologicznego, więc interfejs API wysyła 1 żądanie do https://adtechpartner1.example?their_ad_click_id=567 i 1 żądanie 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"
}

Na podstawie żądań podanych w poprzednich krokach zarejestrowano 3 źródła atrybucji nawigacji (kliknięcia).

Rejestrowanie źródła atrybucji w komponencie WebView

WebView obsługuje przypadki użycia, w których aplikacja renderuje reklamę w komponencie WebView. WebView wywołuje bezpośrednio funkcję registerSource() jako żądanie w tle. To wywołanie powoduje powiązanie źródła atrybucji z aplikacją zamiast z źródłem 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 przypadku, ale skontaktuj się z nami, jeśli dotyczy to Twojego przypadku użycia.

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 URI czynnika uruchamiającego. Interfejs API wysyła żądanie do tego identyfikatora URI, aby pobrać metadane powiązane z wyzwalaczem.

Interfejs API śledzi przekierowania. Odpowiedź serwera adtech powinna zawierać nagłówek HTTP o nazwie Attribution-Reporting-Register-Trigger, który zawiera informacje o co najmniej jednym zarejestrowanym elemencie wyzwalacza. 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 postaci ciągu znaków.

  • Priorytet reguły (opcjonalnie): określa priorytet tej reguły w porównaniu z innymi regułami dla tego samego źródła atrybucji. Musi być 64-bitową liczbą całkowitą ze znakiem w postaci ciągu znaków. Więcej informacji o tym, jak priorytety wpływają na raportowanie, znajdziesz w sekcji Ustalanie priorytetów.

  • Klucz do usuwania duplikatów (opcjonalnie): służy do identyfikowania przypadków, gdy ta sama platforma technologiczna reklamowa zarejestrowała ten sam regułę wielokrotnie w przypadku tego samego źródła atrybucji. Musi być 64-bitową liczbą całkowitą ze znakiem sformatowaną jako ciąg znaków.

  • Klucze agregacji (opcjonalnie): lista słowników, która określa klucze agregacjii określa, które raporty podlegające agregacji mają mieć zsumowane wartości.

  • Wartości agregacji (opcjonalnie): lista wartości, które przyczyniają się do każdego klucza.

  • 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 adtech może zawierać dodatkowe dane w nagłówku Przekierowanie raportowania atrybucji. Dane zawierają adresy URL przekierowań, które umożliwiają wielu technologiom reklamowym zarejestrowanie żądania.

Wiele technologii reklamowych może rejestrować to samo zdarzenie uruchamiające za pomocą przekierowań w polu Attribution-Reporting-Redirect lub 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 deduplikacji.

W Przewodniku dla deweloperów znajdziesz przykłady akceptowania rejestracji wyzwalacza.

Poniżej znajdziesz przykładowy proces:

  1. Pakiet SDK technologii reklamowej wywołuje interfejs API, aby zainicjować rejestrację aktywatora za pomocą wcześniej 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 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
    Attribution-Reporting-Redirect

  4. Interfejs API wysyła żądanie do każdego adresu URL podanego w pliku 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 nagłówkami zawierającymi:

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

    Na podstawie żądań z poprzednich kroków rejestrowane są 2 reguły.

Funkcje atrybucji

W następnych sekcjach opisujemy, jak interfejs Attribution Reporting API dopasowuje wyzwalacze 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ć wyzwalacze do określonych zdarzeń reklamowych, a nie do innych. 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 atrybucji i wyzwalacz tak, aby w przypadku przekroczenia limitów szybkości większa była szansa na otrzymanie raportów, które są dla Ciebie ważniejsze. Możesz na przykład chcieć zwiększyć prawdopodobieństwo występowania w tych raportach konwersji z możliwością określenia stawki lub konwersji 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 kilka ź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ł

Rejestracja źródła i reguły obejmuje dodatkowe funkcje opcjonalne, które umożliwiają:

  • selektywnie filtrować niektóre wyzwalacze, skutecznie je ignorując;
  • Wybierz dane reguły na potrzeby raportów na poziomie zdarzenia na podstawie danych źródłowych.
  • Wykluczenie reguły z raportów na poziomie zdarzenia.

Aby selektywnie filtrować reguły, technologia reklamowa może podczas rejestracji źródła i reguł podać dane filtra, które składają się z kluczy i wartości. Jeśli ten sam klucz jest określony zarówno w źródle, jak i w wyzwalaczu, to wyzwalacz jest ignorowany, jeśli jego przecina jest pusta. Źródło może na przykład określać wartość "product": ["1234"], gdzie product to klucz filtra, a 1234 to wartość. Jeśli filtr reguły jest ustawiony na "product": ["1111"], reguła jest ignorowana. Jeśli nie ma klucza filtra, który pasuje do wartości 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 reklamowej 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 jest dostępny, czas od zarejestrowania źródła musi być krótszy lub równy długości okresu historycznego.

Platformy technologii reklamowych mogą też wybierać dane czynnika uruchamiającego na podstawie danych źródłowych zdarzenia. 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"].

Wyzwalacze są wykluczane z raportów na poziomie zdarzenia, jeśli jest spełniony co najmniej 1 z tych warunków:

  • Nie podano wartości trigger_data.
  • Źródło i wyzwalacz podają ten sam klucz filtra, ale ich wartości się różnią. 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 okno atrybucji po instalacji, w którym wszystkie zdarzenia wywoływane po instalacji powinny być powiązane ze źródłem atrybucji, które spowodowało instalację (zwykle 7–30 dni, dopuszczalny zakres: 0–30 dni). Okres ten należy określić w liczbie sekund.
  • Interfejs Attribution Reporting API sprawdza, kiedy nastąpiła instalacja aplikacji, i wewnętrznie przypisuje ją do źródła atrybucji o najwyższym priorytecie. Instalacja nie jest jednak wysyłana do technologii reklamowych i nie jest uwzględniana w ramach limitów stawek na platformach.
  • Weryfikacja instalacji aplikacji jest dostępna w przypadku każdej pobranej aplikacji.
  • Wszystkie przyszłe wyzwalacze, które wystąpią w okresie atrybucji po instalacji, są przypisywane do tego samego źródła atrybucji co zweryfikowana instalacja, o ile to źródło atrybucji jest odpowiednie.

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

W tabeli poniżej podajemy przykład wykorzystania przez technologie reklamowe 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ń wystąpienia zdarzenia Uwagi
Kliknięcie 1 1 install_attribution_window jest ustawiony na 172800 (2 dni), a post_install_exclusivity_window jest ustawiony na 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 Pierwszy czynnik uruchamiający zarejestrowany przez usługę adtech. W tym przykładzie reprezentuje on pierwsze otwarcie, ale może to być dowolny typ czynnika uruchamiającego.
Przypisany do kliknięcia 1 (zgodny z atrybucją zweryfikowanej instalacji).
Kliknij 2 4 Używa tych samych wartości w przypadku atrybutów install_attribution_window i post_install_exclusivity_window co Click 1.
Aktywator 2 (po instalacji) 5 Drugi czynnik rejestrowany przez usługę adtech. W tym przykładzie reprezentuje konwersję po instalacji, np. zakup.
Przypisany do kliknięcia 1 (zgodny z atrybucją zweryfikowanej instalacji).
Klik 2 jest odrzucany i nie kwalifikuje się do przyszłej atrybucji.

Oto dodatkowe informacje dotyczące atrybucji po instalacji:

  • Jeśli weryfikowana instalacja nie nastąpi w okresie określonym przez install_attribution_window, nie zostanie zastosowana atrybucja po instalacji.
  • Zweryfikowane instalacje nie są rejestrowane przez technologie reklamowe i nie są wysyłane w raportach. Nie wliczają się one do limitów szybkości reklamy. 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 otwarciu aplikacji i konwersji po zainstalowaniu aplikacji. Platformy technologii reklamowych mogą jednak rejestrować dowolny typ wyzwalacza. Innymi słowy, pierwszy aktywator nie musi być pierwszym aktywatorem otwartym.
  • Jeśli po wygaśnięciu post_install_exclusivity_windowzarejestruje się więcej wyzwalaczy, kliknięcie 1 nadal kwalifikuje się do przypisania, o ile nie wygasło i nie osiągnęło limitu szybkości.
    • 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 zdarzenia nadal będą przypisywane zarówno inicjatory „pierwszego uruchomienia”, jak i poinstalowania. 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 dostawca technologii reklamowej może otrzymywać 2 różne okna raportowania (po 2 dniach lub po wygaśnięciu źródła).

Obsługiwane są wszystkie kombinacje ścieżek reguł opartych na aplikacjach i na stronie internetowej.

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 dokonuje konwersji w tej aplikacji lub innej zainstalowanej aplikacji.
  • App-to-web: użytkownik widzi reklamę w aplikacji, a potem dokonuje konwersji w przeglądarce mobilnej lub w przeglądarce w aplikacji.
  • Web-to-app: 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 w aplikacji, a potem dokonuje konwersji w tej samej przeglądarce lub w innej przeglądarce na tym samym urządzeniu.

Zezwalam przeglądarkom na obsługę nowych funkcji internetowych, takich jak funkcje podobne do interfejsu Attribution Reporting API w Piaskownicy prywatności na potrzeby internetu, które mogą wywoływać interfejsy API Androida, aby umożliwić przypisywanie atrybucji w aplikacjach i w internecie.

Dowiedz się, jakie zmiany muszą wprowadzić dostawcy technologii reklamowych i aplikacje, aby obsługiwać ścieżki uruchamiania 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żdy taki czynnik jest przypisywany do co najmniej 1 źródła atrybucji zgodnie z algorytmem atrybucji z priorytetem źródła, który opisujemy dalej na tej stronie.

Liczba reguł, które można przypisać do pojedynczego źródła atrybucji, jest ograniczona. Więcej informacji znajdziesz w sekcji Wyświetlanie danych pomiarowych w raportach atrybucji poniżej.

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.

Zezwalanie na rejestrowanie źródeł atrybucji lub wyzwalaczy przez wiele technologii reklamowych

Zwykle raporty atrybucji otrzymuje więcej niż 1 technologia reklamowa, zwykle w celu przeprowadzania deduplikacji między sieciami. Dlatego interfejs API umożliwia wielu technologiom reklamowym rejestrowanie tego samego źródła atrybucji lub tego samego wyzwalacza. 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 pomiarowe 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ń partnera.
  2. Następnie interfejs API wywołuje adresy URL przekierowania, aby źródło atrybucji mogło zostać zarejestrowane przez technologię reklamową partnera.

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

Interfejs API umożliwia też stosowanie różnych technologii reklamowych do każdego wywołania 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 kilku 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 dostawca technologii reklamowej może wywołać interfejs API bezpośrednio z pakietu SDK, aby zarejestrować wyzwalacz, a jego adres URL podać w polu przekierowania wywołania innego dostawcy technologii reklamowej. Jeśli nie podasz klucza deduplikacji, zduplikowane reguły mogą zostać zwrócone do każdej technologii reklamowej jako unikalne.

Obsługa zduplikowanych reguł

Firma zajmująca się technologiami reklamowymi może zarejestrować ten sam wyzwalacz kilka razy w interfejsie API. Scenariusze:

  • Użytkownik wykonuje to samo działanie (regułę) kilka razy. Na przykład użytkownik przegląda ten sam produkt kilka razy w tym samym oknie raportowania.
  • Aplikacja reklamodawcy używa wielu pakietów SDK do pomiaru konwersji, które wszystkie przekierowują do tego samego rozwiązania do pomiaru reklam. Na przykład aplikacja reklamodawcy korzysta z 2 partnerów do pomiarów: MMP 1 i MMP 2. Oba MMP przekierowują do technologii reklamowej 3. Gdy nastąpi wywołanie reguły, oba MMP rejestrują to wywołanie w interfejsie 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 elementu wyzwalczającego.

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. Zalecamy użycie klucza deduplikacji.

Zalecana metoda: klucz deduplikacji

Zalecana metoda polega na tym, aby aplikacja reklamodawcy przekazała unikalny klucz deduplikacji do wszystkich technologii reklamowych lub pakietów SDK, których używa do pomiaru konwersji. Gdy nastąpi konwersja, aplikacja przekazuje klucz deduplikacji do technologii reklamowych lub pakietów SDK. Następnie te technologie reklamowe lub pakiety SDK przekazują klucz deduplikacji do przekierowań za pomocą parametru w adresach URL określonych w Attribution-Reporting-Redirect.

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

Jeśli usługa reklamowa rejestruje wiele wyzwalaczy z tym samym kluczem deduplikacji i przypisanym źródłem, w raportach na poziomie zdarzenia jest wysyłany tylko pierwszy zarejestrowany wyzwalacz. Duplikaty reguł są nadal wysyłane w zaszyfrowanych raportach możliwych do agregacji.

Metoda alternatywna: dostawcy technologii reklamowych uzgadniają typy wyzwalaczy 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ć ze sobą, aby definiować różne typy zdarzeń 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ć informacje takie jak nazwa pakietu SDK i typ reguły dla 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ć. Aby dowiedzieć się więcej, zapoznaj się z artykułem Rejestracja na konto w Piaskownicy prywatności.

Poniżej znajdziesz hipotetyczną serię działań użytkownika, które występują co dzień, oraz sposób, w jaki interfejs Attribution Reporting API obsługuje te działania w odniesieniu do technologii reklamowych A i B oraz MMP:

Dzień 1: użytkownik klika reklamę wyświetloną przez usługę Ad tech A.

Technologia reklamowa A wywołuje registerSource() za pomocą swojego 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ż w główce Attribution-Reporting-Redirectidentyfikator URI MMP. Interfejs API wysyła żądanie do identyfikatora URI MMP, a kliknięcie jest rejestrowane z użyciem metadanych z odpowiedzi serwera MMP.

Dzień 2. Użytkownik klika reklamę wyświetloną przez usługę Ad tech B

Technologia reklamowa B wywołuje adres registerSource() za pomocą identyfikatora URI. Interfejs API wysyła żądanie do identyfikatora URI, a kliknięcie jest rejestrowane z metadanymi z odpowiedzi serwera AdTech B.

Podobnie jak usługa Ad tech A, usługa Ad tech B zawiera w nagłówku Attribution-Reporting-Redirect adres URI MMP. Interfejs API wysyła żądanie do adresu URI MMP, a kliknięcie jest rejestrowane wraz z metadanymi 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 registerTrigger() za pomocą swojego 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 MMP zawiera też identyfikatory URI usług Ad tech A i Ad tech 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.

Proces opisany na liście powyżej przedstawia diagram poniżej:

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

Atrybucja działa w ten sposób:

  • Technologia reklamowa A ustawia wyższą priorytetyzację kliknięć niż wyświetleń, dlatego instalacja jest przypisywana do kliknięcia w Dzień 1.
  • Technologia reklamowa B otrzymuje przypisaną instalację w dniu 2.
  • MMP ustawia wyższy priorytet kliknięć niż wyświetleń i przypisuje instalację kliknięciu w dniu 2. Kliknięcie w 2. dniu ma najwyższy priorytet i jest najnowszym zdarzeniem reklamowym.

Atrybucja międzysieciowa bez przekierowań

Chociaż zalecamy stosowanie przekierowań, aby umożliwić rejestrowanie źródeł atrybucji i wyzwalaczy przez wiele technologii reklamowych, zdajemy sobie sprawę, że w niektórych przypadkach nie jest to możliwe. Z tej sekcji dowiesz się, jak obsługiwać atrybucję w wielu sieciach bez przekierowań.

Przepływ na wysokim poziomie

  1. Podczas rejestracji źródła sieć reklamowa udostępnia klucze agregacji źródeł.
  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 wywołanie zostanie przypisane do źródła z reklamy wyświetlanej przez technologię reklamową bez przekierowania, reklamodawca lub partner ds. pomiarów może otrzymać raport z możliwością agregacji, który łączy elementy klucza źródła i wywołania zdefiniowane w kroku 2.

Rejestracja źródła

Podczas rejestracji źródła sieć reklamowa obsługująca reklamy może udostępnić klucze agregacji źródeł lub ich podzbiór zamiast przekierowywać. 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 od technologii reklamowej obsługującej reklamy i technologii reklamowej obsługującej uruchamianie liczników zależy, jakie typy kluczy agregacji są potrzebne, jak mają się nazywać i jak dekodować te klucze na 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, które są udostępniane przez usługi pomiarowe reklamy.

Dodatkowo technologia reklamowa do pomiarów 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 partnera technologicznego MMP do pomiarów.
  • Technologia reklamowa A przekierowuje swoje źródła do MMP.
  • Technologia reklamy B i C nie przekierowuje, ale udostępnia klucze agregacji.
  • Technologia reklamowa D nie przekierowuje ani nie udostępnia kluczy agregacji.

MMP rejestruje źródło z technologii reklamowej A i określa konfigurację atrybucji, która obejmuje technologię reklamową B i D.

Atrybucja w MMP obejmuje teraz:

  • Technologia reklamowa A, ponieważ MMP zarejestrowała ź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 obejmuje:

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

Debugowanie

Aby umożliwić debugowanie atrybucji w wielu sieciach bez przekierowań, dostawcy technologii reklamowych mogą ustawić dodatkowe pole shared_debug_key podczas rejestracji źródła. Jeśli jest ustawiona w ramach rejestracji pierwotnego źródła, zostanie też ustawiona w odpowiednim pochodnym źródle jako debug_key podczas rejestracji reguły w celu atrybucji w różnych sieciach 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 skuteczności aplikacji do aplikacji, w którym dozwolony jest identyfikator AdID;
  • pomiar przejścia z aplikacji do witryny, w którym Identyfikator reklamy jest dozwolony i dopasowywany zarówno w źródle aplikacji, jak i w wyzwalaczu internetowym;
  • pomiar skuteczności w internecie (w tej samej aplikacji przeglądarki), gdy w źródle i wyzwalaczu występuje parametr ar_debug;

Wyszukiwanie kluczy w przypadku atrybucji międzysieciowej bez przekierowań

Odnajdywanie kluczy ma na celu uproszczenie implementacji konfiguracji atrybucji przez technologie reklamowe (zwykle MMP) na potrzeby atrybucji między sieciami, gdy jedna lub kilka technologii reklamowych korzysta ze wspólnych kluczy agregacji (jak opisano powyżej w sekcji Atrybucja między sieciami 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 jest skomplikowane i drogie. Rozważ te przykłady:

  • Lista wszystkich możliwych kluczy jest długa:
    • Sieć reklamowa obsługująca reklamy realizuje złożoną inicjatywę z zakresu pozyskiwania użytkowników, która obejmuje 20 kampanii, z których każda ma 10 grup reklam, a każda grupa reklam ma 5 kreacji, 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 korzysta z różnych sieci reklamowych, które nie przekierowują do MMP podczas rejestracji źródła. Każda sieć reklamowa ma inną strukturę i wartości kluczy, które mogą nie być udostępniane wcześniej MMP.

Dzięki wprowadzeniu kluczy dostępnych do odkrycia:

  • 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 wartości nieprawidłowe w przypadku kluczy, których wartości przyczyniają się do przekroczenia ustawionego progu. Raport może też zawierać klucze, które nie mają powiązanych danych pochodzących od rzeczywistych użytkowników i są czystym szumem.
  • MMP używa pola x_network_bit_mapping w rejestracji reguły, aby określić, któremu kluczowi odpowiada dana technologia reklamowa.
  • MMP może wtedy skontaktować się z odpowiednią technologią wyświetlania reklam, aby poznać wartości w kluczu źródłowym.

Podsumowując, wykrywanie kluczy umożliwia platformom MMP uzyskiwanie kluczy agregacji bez znajomości ich wcześniejszych wersji i unikanie przetwarzania dużej liczby kluczy źródeł kosztem dodanego szumu.

Łańcuch przekierowań

Przekazując w odpowiedzi serwera HTTPS po rejestracji źródła lub aktywatora wiele nagłówków Attribution-Reporting-Redirect, technologia reklamowa może używać interfejsu Attribution Reporting API do rejestrowania wielu źródeł i aktywacji za pomocą jednego wywołania interfejsu API.

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 w razie braku przekierowań nie trzeba podawać żadnego. 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 wartości, aby uniknąć znacznego 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 powiązane z określonym źródłem atrybucji (kliknięcie lub wyświetlenie) z ograniczoną ilością wysokiej jakości danych o wyzwalaczach.
  • Raporty nadające się do agregacji 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 wysłać z powrotem do adresu URL wywołania zwrotnego każdej technologii reklamowej 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 w przypadku kliknięć (co oznacza, że reguła może być przypisana do jednej z 8 kategorii) i 1 bita w przypadku 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 działania 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, w której wystąpił element wyzwalający.
  • Identyfikator źródła atrybucji: ten sam identyfikator źródła atrybucji, który został użyty do zarejestrowania ź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 we wszystkich raportach

Te limity są stosowane po uwzględnieniu priorytetów dotyczących źródeł atrybucji i wyzwalaczy.

Ograniczenia dotyczące liczby technologii reklamowych

Istnieją limity liczby dostawców technologii reklamowych, którzy mogą rejestrować się w interfejsie API lub otrzymywać z niego raporty. Obecna propozycja obejmuje:

  • 100 technologii reklamowych ze źródłami atrybucji na {source app, destination app, 30 days, device}.
  • 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).

Ograniczenia liczby unikalnych miejsc docelowych

Te limity utrudniają grupom dostawców technologii reklamowych współpracę polegającą na wysyłaniu zapytań do dużej liczby aplikacji w celu poznania zachowań użytkownika związanych z korzystaniem z aplikacji.

  • W przypadku wszystkich zarejestrowanych źródeł i wszystkich technologii reklamowych interfejs API obsługuje maksymalnie 200 niepowtarzalnych miejsc docelowych na aplikację źródłową na minutę.
  • W przypadku wszystkich zarejestrowanych źródeł interfejs API obsługuje nie więcej niż 50 niepowtarzalnych miejsc docelowych na aplikację źródłową na minutę. Ten limit zapobiega temu, aby jedna technologia reklamowa zużywała cały budżet z wymienionego wcześniej limitu stawek.

Źródła z wygasłymi tokenami nie wliczają się do limitów szybkości.

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

W danym dniu dana platforma technologii reklamowej może używać tylko jednego źródła raportowania do rejestrowania źródeł w aplikacji wydawcy na danym urządzeniu. Ten limit szybkości zapobiega wykorzystywaniu przez dostawców technologii reklamowych wielu źródeł raportowania do uzyskiwania dodatkowego budżetu na ochronę prywatności.

Rozważmy taki scenariusz, w którym jedna firma z branży technologii reklamowych chce używać wielu źródeł raportowania do rejestrowania źródeł w aplikacji wydawcy na jednym urządzeniu.

  1. Źródło raportowania 1 dostawcy technologii reklamowych A rejestruje źródło w aplikacji B.
  2. 12 godzin później usługa adtech A próbuje zarejestrować źródło w aplikacji B za pomocą źródła raportowania 2

Drugie źródło, które jest źródłem danych 2 w przypadku dostawcy Ad tech 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 parami {source, destination}, interfejs API ogranicza ilość informacji wysyłanych w danym okresie czasu dla danego 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 jest firmie zajmującej się technologiami reklamowymi używać interfejsu API do pomiaru aktywności użytkowników w sieci, która nie jest związana z wyświetlaniem reklam.

Obecna propozycja zakłada ograniczenie każdej technologii reklamowej do 100 różnych miejsc docelowych z niewygasłymi źródłami na aplikację źródłową.

Mechanizmy ochrony prywatności stosowane w raportach na poziomie zdarzenia

Ograniczona dokładność danych wyzwalacza

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-bitowe metadane.

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 pomiarów na poziomie zdarzenia, które spełniają lokalne wymagania dotyczące ochrony prywatności, dzięki zastosowaniu odpowiedzi z losowaniem k-tym, aby generować szumowe dane wyjściowe dla każdego zdarzenia źródłowego.

Szum jest stosowany w przypadku, gdy zdarzenie źródła atrybucji jest raportowane w sposób nieprawidłowy. Źródło atrybucji jest rejestrowane na urządzeniu z prawdopodobieństwom $ 1-p, że źródło atrybucji jest rejestrowane jako normalne, oraz z prawdopodobieństwom $ p, że urządzenie losowo wybiera spośród wszystkich możliwych stanów wyjściowych interfejsu API (w tym nie zgłasza żadnych danych lub zgłasza wiele fałszywych raportów).

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 parametru ε 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% dla źródeł nawigacji
  • p=0,00025% dla źródeł zdarzeń

Limity dotyczące dostępnych reguł (konwersji)

Istnieją limity liczby wyzwalaczy na źródło atrybucji. Obecna propozycja obejmuje:

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

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ę ważności można skonfigurować, ale nie może ona być krótsza niż 1 dzień ani dłuższa niż 30 dni. Jeśli 2 reguły są 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 okien raportowania.

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 czasie w stosunku do momentu jego rejestracji. Czas między źródłem atrybucji a wygasnięciem jest dzielony na kilka okien raportowania. Każde okno raportowania ma termin (od czasu źródła atrybucji). Na koniec każdego okna raportowania urządzenie zbiera wszystkie wyzwalacze, które wystąpiły od poprzedniego okna raportowania, i wysyła zaplanowany raport. Interfejs API obsługuje te okna raportowania:

  • 2 dni: urządzenie zbiera wszystkie wyzwalacze, które wystąpiły maksymalnie 2 dni po zarejestrowaniu źródła atrybucji. Raport jest wysyłany 2 dni i 1 godzinę po zarejestrowaniu źródła atrybucji.
  • 7 dni: urządzenie rejestruje wszystkie zdarzenia, które wystąpiły ponad 2 dni, ale nie więcej niż 7 dni po zarejestrowaniu źródła atrybucji. Raport jest wysyłany 7 dni i 1 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.

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 czemu specjaliści od technologii reklamowych będą mieć większą kontrolę nad strukturą raportów na poziomie zdarzenia i będą mogli w maksymalny sposób wykorzystywać dane.

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 zawiera podzbiór pełnych funkcji i może być używana niezależnie od etapu 2.
  • Etap 2. Pełna wersja elastycznej konfiguracji na poziomie zdarzenia

Etap 1 (Lite, elastyczny poziom zdarzeń):

  • Zmiana częstotliwości raportów przez określenie liczby okresów raportowania
  • Zmiana liczby atrybucji na rejestrację źródła
  • Zmniejsz całkowity szum, zmniejszając wymienione powyżej 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:

  • Zmiana w raporcie mocy zbioru danych reguły
  • Zmniejsz całkowity poziom szumu, zmniejszając kardinalityczność danych wyzwalacza.

Zmniejszenie jednego wymiaru w konfiguracji domyślnej pozwala technologii reklamowej zwiększyć inny wymiar. Łączną ilość szumów w raporcie na poziomie zdarzenia można też zmniejszyć, zmniejszając wymienione powyżej parametry.

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 wyrażenia opinii na temat [propozycja projektu][50]:

  • Maksymalnie 20 raportów ogółem, globalnie i na podstawie wartości parametru trigger_data.
  • Maksymalnie 5 możliwych okresów raportowania na trigger_data
  • Maksymalna moc zbioru danych reguły to 32 (nie dotyczy etapu 1: Lite: elastyczny poziom zdarzenia)

Pamiętaj, że gdy technicyczni specjaliści ds. reklam zaczną korzystać z tej funkcji, użycie wartości skrajnych może spowodować duży poziom szumu lub nieudaną rejestrację, jeśli nie zostaną spełnione poziomy prywatności.

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 o wartościach reguły, np. przychodach;
  • Obsługa większej liczby typów reguł

Raporty zbiorcze korzystają z tej samej logiki atrybucji opartej na priorytetach źródeł co raporty na poziomie zdarzenia, ale obsługują więcej konwersji przypisanych do kliknięcia lub wyświetlenia.

Interfejs Attribution Reporting API przygotowuje i wysyła raporty podlegające agregacji w taki sposób:

  1. Urządzenie wysyła do dostawcy technologii reklamowych zaszyfrowane raporty, które można agregować. W środowisku produkcyjnym dostawcy technologii reklamowych 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 partię raportów możliwych do zsumowania, odszyfruje je i 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 wywołania, zebrane jako zaszyfrowane pary klucz-wartość, które są używane w zaufanej usłudze agregacji do obliczania agregacji.

Usługi agregacji

Te usługi zapewniają możliwości agregacji danych i chronią przed nieautoryzowanym dostępem do danych zagregowanych.

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 specjalizujące się w technologiach reklamowych powinny wdrożyć.
  • Usługi zarządzania kluczami i raportowania z możliwością agregacji są obsługiwane przez zaufane podmioty zwane koordynatorami. Ci koordynatorzy poświadczają, że kod obsługujący usługę agregacji jest dostępny publicznie i dostarczony przez Google oraz że wszyscy użytkownicy usługi agregacji mają te same klucze i mogą korzystać z usług księgowania raportów podlegających agregacji.
Usługa agregacji

Platformy technologiczne muszą wcześniej wdrożyć usługę agregacji opartą na binarnych plikach udostępnionych 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 jest określonym binarnym kodem oferowanym przez Google. Jeśli to kryterium nie zostanie spełnione, usługa agregacji nie będzie mieć dostępu do kluczy odszyfrowywania, których potrzebuje do działania.
  • Zapewnia bezpieczeństwo dla uruchomionego procesu, izolując go od zewnętrznego monitorowania lub manipulowania.

Dzięki tym funkcjom bezpieczeństwa usługa agregacji może bezpieczniej wykonywać operacje wrażliwe, takie jak dostęp do zaszyfrowanych danych.

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

System zarządzania kluczami

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

Uwzględnianie danych w raportach zbiorczych

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 raportów zbiorczych

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 sekcjach poniżej opisano rozszerzenia 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:

  • (Key) Key name: ciąg znaków zawierający nazwę klucza. Służy jako klucz łączenia, który łączy się z kluczami po stronie wyzwalacza, tworząc klucz końcowy.
  • (Value) Key piece: wartość klucza w postaci ciągu bitów.

Ostateczny klucz zbiornika histogramu jest w pełni zdefiniowany w momencie uruchomienia, gdy wykonujemy operację binarnego LUB na tych elementach i elementach po stronie uruchamiania.

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

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

W tym przykładzie dostawca technologii reklamowych korzysta z interfejsu API, aby zbierać te informacje:

  • łączna liczba konwersji na poziomie kampanii,
  • wartości zakupu zbiorczego 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 regułę, która może być agregowana.

Rejestracja reguły zawiera 2 pola dodatkowe.

Pierwsze pole służy do rejestrowania listy kluczy zbiorczych 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ódeł: lista ciągów tekstowych z nazwami kluczy źródłowych atrybucji, z którymi należy połączyć klucz aktywatora, aby utworzyć klucze końcowe.

Drugie pole służy do rejestrowania listy wartości, które powinny się przyczyniać do każdego klucza. Technologia reklamowa powinna odpowiedzieć, podają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 możliwych do 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 $ to norma L1, czyli czułość histogramu na podstawie udziału w źródle. Przekroczenie tych limitów powoduje, że przyszłe wkłady są automatycznie odrzucane. 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. Takie podejście pozwala zachować jak najwyższą wierność danych w raportach zbiorczych 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
    }
}

Powyższy przykład generuje te wartości histogramu:

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

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ć prywatny pomiar zbiorczy z różnymi poziomami prywatnoś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 interfejsów Protected Audience API i Attribution Reporting API umożliwia firmom zajmującym się technologiami reklamowymi ocenę skuteczności atrybucji w różnych taktykach remarketingowych, aby dowiedzieć się, które typy odbiorców zapewniają najwyższy ROI.

Dzięki tej integracji interfejsów API firmy z branży adtech mogą:

  • Utwórz mapę identyfikatorów URI, która będzie służyć do: 1) raportowania interakcji i 2) rejestracji źródeł.
  • Uwzględnij CustomAudience w mapowaniu kluczy po stronie źródła na potrzeby raportowania zbiorczego (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 przekazać za pomocą tego adresu URL CustomAudience (lub inne odpowiednie informacje kontekstowe o reklamie, np. o miejscu docelowym reklamy lub czasie jej wyświetlania), aby te metadane mogły być propagowane do raportów zbiorczych, gdy technologia reklamowa będzie 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.

Priorytet rejestracji, atrybucja i przykłady raportów

Ten przykład pokazuje zestaw interakcji użytkowników oraz sposób, w jaki zdefiniowane przez technologię reklamową źródła atrybucji i priorytety wyzwalaczy mogą wpływać na raporty o przypisanych konwersjach. W tym przykładzie zakładamy:

  • Wszystkie źródła i wyzwalacze 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 wyświetlenia reklam w aplikacji wydawcy).

Weź pod uwagę przypadek, w którym użytkownik:

  1. Użytkownik widzi reklamę. Technologia reklamowa rejestruje w interfejsie API źródło atrybucji o priorytecie 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 (dociera do strony docelowej) w aplikacji reklamodawcy. Technologia reklamowa rejestruje w interfejsie API odpowiednią regułę z priorytetem 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 1. Interfejs API przypisuje ten regułowany element kliknięciu 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 zarejestrowanej z priorytetem 1 (konwersja 3).
    • Kliknięcie 1 jest jedynym kwalifikującym się źródłem atrybucji. Interfejs API przypisuje ten element do kliknięcia 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 element do kliknięcia 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 są zarejestrowane reguły o wyższym priorytecie, mają one pierwszeństwo i zastępują ostatnią regułę.
  • W powyższym przykładzie technologia reklamowa otrzymuje 3 raporty zdarzeń po upływie 2-dniowego okna raportowania w przypadku konwersji 2, 3 i 5.
    • Wszystkie 5 wyzwalaczy jest przypisanych do kliknięcia 1. Domyślnie interfejs API wysyła raporty dotyczące pierwszych 3 wyzwalaczy: konwersji 1, konwersji 2 i konwersji 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.
    • Dodatkowo priorytet konwersji 5 (2) jest wyższy niż w przypadku wszystkich innych reguł. Raport o zdarzeniu związanym z konwersją 5 zastąpi wysyłany raport o konwersji 4.

Raporty, które można agregować, mają te cechy:

  • 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 podlegających agregacji. Te informacje znajdują się w polu shared_info w raporcie możliwym do zgrupowania 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. Oto kilka prostych strategii, których możesz używać: Najlepiej, jeśli partie zawierają co najmniej 100 raportów.

  • To dostawca technologii reklamy decyduje, kiedy i jak grupować raporty zbiorcze oraz wysyłać je do usługi agregacji.

  • W porównaniu z raportami na poziomie zdarzenia raporty zaszyfrowane, które można agregować, mogą przypisywać więcej źródeł do większej liczby wywołań.

  • W powyższym przykładzie wysyłanych jest 5 raportów możliwych do zsumowania, po jednym na każdy zarejestrowany reguł.

Raporty przejściowe dotyczące debugowania

Interfejs Attribution Reporting API to nowy i dosyć złożony sposób pomiaru atrybucji bez identyfikatorów międzyaplikacjami. Dlatego udostępniamy mechanizm przejściowy, który pozwala uzyskać więcej informacji o raportach atrybucji w przypadku, gdy jest dostępny identyfikator wyświetlania reklam (użytkownik nie zrezygnował z personalizacji za pomocą identyfikatora wyświetlania reklam, a aplikacja wydawcy lub reklamodawcy ma zadeklarowane uprawnienia do 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: attribution-success i verbose.

Więcej informacji o debugowaniu raportów z użyciem pomiarów w aplikacji i w witrynie znajdziesz w przewodniku Przejściowe raporty z debugowaniem.

Raporty debugowania atrybucji

Zarówno rejestracje źródła, jak i wyzwalacza obsługują nowe 64-bitowe pole debug_key (sformatowane jako ciąg znaków), które jest wypełniane przez technologię reklamową. Parametry source_debug_key i trigger_debug_key są przekazywane w niezmienionej postaci w raportach na poziomie zdarzenia i raportach zbiorczych.

Jeśli raport jest tworzony przy użyciu kluczy debugowania źródła i kluczy debugowania reguły, do punktu końcowego .well-known/attribution-reporting/debug/report-event-attributionzostaje wysłany duplikat raportu debugowania. Raporty debugowania są identyczne z normalnymi raportami, w tym w przypadku pól klucza debugowania. Użycie tych kluczy w obu przypadkach umożliwia powiązanie standardowych raportów z oddzielnym strumieniem raportów 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 zbiorczych:
    • 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 szczegółowy raport zawiera te pola:

  • Typ: powód 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.
    • Raporty szczegółowe źródła wymagają, aby identyfikator wyświetlania reklam był dostępny dla aplikacji wydawcy, a raporty szczegółowe uruchamiania – aby był dostępny dla aplikacji reklamodawcy.
    • Raporty szczegółowe (z wyjątkiem raportu trigger-no-matching-source) mogą opcjonalnie zawierać informacje source_debug_key. Można go uwzględnić tylko wtedy, gdy identyfikator wyświetlania reklam jest też dostępny dla aplikacji wydawcy.
  • Treść: treść raportu, która zależy od jego typu.

Firmy zajmujące się technologiami reklamowymi muszą wyrazić zgodę na otrzymywanie szczegółowych raportów z debugowania, korzystając z nowego pola słownika debug_reporting w nagłówkach Attribution-Reporting-Register_Source i Attribution-Reporting-Register-Trigger.

  • Raporty szczegółowe źródła wymagają akceptacji tylko w nagłówku rejestracji źródła.
  • Raporty debugowania reguł wymagają włączenia tylko nagłówka rejestracji reguły.

Jak korzystać z raportów debugowania

Jeśli konwersja miała miejsce (zgodnie z Twoim dotychczasowym systemem pomiarowym) i w przypadku tej konwersji otrzymano raport debugowania, oznacza to, że wyzwalacz został zarejestrowany.

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 jest poddawany losowaniu odpowiedzi (szumowi) i jest tłumiony, a Ty możesz otrzymać losowy raport.
    • 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 danych w raportach możliwych do zgrupowania.
  • Logika biznesowa zdefiniowana przez technologię reklamową:
    • Wyzwalacz jest odfiltrowywany za pomocą filtrów lub reguł z priorytetem.
  • opóźnienia lub interakcje związane z dostępnością sieci (np. użytkownik wyłącza urządzenie na dłuższy czas);

Niezamierzone przyczyny:

  • Problemy z implementacją:
    • Nieprawidłowo skonfigurowano nagłówek źródła.
    • Nieprawidłowo skonfigurowano nagłówek reguły.
    • inne problemy z konfiguracją.
  • Problemy z urządzeniem lub siecią:
    • Błędy spowodowane warunkami sieci.
    • Źródło lub odpowiedź rejestracji wyzwalacza nie dociera do klienta.
    • Błąd interfejsu API.

Uwagi 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 wielu urządzeniach.

Chcielibyśmy też uzyskać od społeczności opinię na temat kilku kwestii:

  1. Czy są jakieś przypadki użycia, w których interfejs API powinien wysyłać raporty dotyczące zweryfikowanej instalacji? Te raporty będą wliczane do limitów częstotliwości platform 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 użycia atrybucji w przypadku wstępnie zainstalowanych lub ponownie zainstalowanych aplikacji?