Raportowanie atrybucji

Przesłać opinię

Ostatnie aktualizacje

  • Zaktualizowaliśmy listę nadchodzących zmian i znanych problemów.
  • Wprowadziliśmy elastyczną konfigurację na poziomie zdarzenia, która jako pomost do pełnej elastycznej konfiguracji na poziomie zdarzenia.
  • Od września 2023 r. w polach, które oczekują wartości liczbowej, w polach registerWebSource, registerWebTrigger, registerAppSource i registerAppTrigger trzeba używać ciągów znaków (np. priority, source_event_id, debug_key, trigger_data, deduplication_key itp.).
  • W IV kwartale 2023 r. dodamy obsługę Google Cloud do interfejsu Android Attribution Reporting API w celu generowania raportów podsumowujących za pomocą usługi agregacji w Google Cloud. Tutaj znajdziesz bardziej szczegółowe informacje o terminach. Więcej informacji o konfigurowaniu usługi agregacji z Google Cloud znajdziesz w przewodniku wdrażania.
  • Nowe limity stawek chroniące prywatność dla liczby unikalnych miejsc docelowych.
  • Zaktualizowane funkcje filtrów reguł związanych z okresem ważności zostaną wprowadzone w I kwartale 2024 roku. Więcej informacji znajdziesz w dalszej części wiadomości.

Przegląd

Obecnie rozwiązania do atrybucji i pomiarów na urządzeniach mobilnych często korzystają z różnych identyfikatorów, np. identyfikatora 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 użycia atrybucji i pomiaru konwersji w aplikacjach i w internecie.

Ten interfejs API ma te mechanizmy strukturalne, które zapewniają platformę do usprawniania prywatności. Opisaliśmy je bardziej szczegółowo w dalszej części tej strony:

Poprzednie mechanizmy ograniczają możliwość łączenia tożsamości użytkownika z 2 różnymi aplikacjami lub domenami.

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

  • Raportowanie konwersji: pomóż reklamodawcom mierzyć skuteczność kampanii, wyświetlając im liczbę konwersji (reguł) i wartości konwersji (reguł) w różnych wymiarach, np. według kampanii, grupy reklam i kreacji.
  • Optymalizacja: raporty na poziomie zdarzenia pomagające w optymalizacji wydatków na reklamę. Dostarczają one danych atrybucji na poziomie wyświetlenia, które mogą służyć do trenowania modeli systemów uczących się.
  • Wykrywanie nieprawidłowej aktywności: udostępniaj raporty, które mogą być używane do wykrywania nieprawidłowego ruchu oraz wykrywania i analizowania oszustw reklamowych.

Ogólnie interfejs Attribution Reporting API działa w ten sposób, co zostało szczegółowo opisane w późniejszych sekcjach tego dokumentu:

  1. Technologia reklamowa 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, czyli 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, czyli atrybucji konwersji, a co najmniej 1 z nich jest wysyłana poza urządzenie za pomocą raportów na poziomie zdarzenia i zbiorczych raportów 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 Rejestrowanie konta Piaskownicy prywatności.

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

Interfejs Attribution Reporting API określa kliknięcia i wyświetlenia reklam jako źródła atrybucji. Aby zarejestrować kliknięcie lub wyświetlenie reklamy, wywołaj funkcję registerSource(). Ten interfejs API wymaga następujących 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 (w przypadku zdarzenia wyświetlenia).

Gdy interfejs API wysyła żądanie do identyfikatora URI źródła atrybucji, technika reklamowa powinna odpowiedzieć, przesyłając metadane źródła atrybucji w nowym nagłówku HTTP Attribution-Reporting-Register-Source z tymi polami:

  • Identyfikator zdarzenia źródłowego: ta wartość reprezentuje dane na poziomie zdarzenia powiązane z danym źródłem atrybucji (kliknięciem lub widokiem reklamy). Musi to być 64-bitowa nieoznaczona liczba całkowita sformatowana pod postacią ciągu znaków.
  • Miejsce docelowe: źródło, którego eTLD+1 lub nazwa pakietu aplikacji, w którym występuje zdarzenie aktywujące.
  • Wygaśnięcie (opcjonalnie): wygasa w sekundach i wygasa, gdy źródło powinno zostać usunięte z urządzenia. Domyślnie jest to 30 dni, minimalna wartość to 1 dzień i maksymalna 30 dni. Ta wartość jest zaokrąglana do najbliższego dnia. Może być sformatowany jako 64-bitowa nieoznaczona liczba całkowita lub ciąg znaków.
  • Okno raportu o zdarzeniach (opcjonalnie): czas (w sekundach) od rejestracji źródła, podczas którego można tworzyć raporty o zdarzeniach dla tego źródła. Jeśli okno raportu o zdarzeniach już minęło, ale ten okres jeszcze nie upłynął, nadal można dopasować do źródła regułę, ale raport o zdarzeniach nie jest dla niej wysyłany. Wartość nie może być większa niż wartość Data ważności. Może być sformatowany jako 64-bitowa nieoznaczona liczba całkowita lub ciąg znaków.
  • Okno raportu zbiorczego (opcjonalnie): czas (w sekundach) od rejestracji źródła, podczas którego można tworzyć raporty zbiorcze dotyczące tego źródła. Wartość nie może być większa niż wartość Data ważności. Może być sformatowany jako 64-bitowa liczba całkowita lub ciąg znaków bez znaku.
  • Priorytet źródła (opcjonalnie): służy do wybierania źródła atrybucji, z którym ma być powiązana dana reguła, na wypadek gdyby można było z nią powiązać wiele źródeł atrybucji. Musi to być 64-bitowa liczba całkowita ze znakiem sformatowana pod postacią ciągu znaków.

    Po otrzymaniu reguły interfejs API znajduje pasujące źródło atrybucji o najwyższym priorytecie źródła i generuje raport. Każda platforma technologii reklamowych może zdefiniować własną strategię ustalania priorytetów. Więcej informacji o tym, jak priorytet wpływa na atrybucję, znajdziesz w sekcji z przykładem ustalania priorytetów.

    Wyższe wartości oznaczają wyższe priorytety.
  • Okna atrybucji instalacji i po instalacji (opcjonalne): służą do określania atrybucji zdarzeń po instalacji opisanych w dalszej części tej strony.
  • Filtrowanie danych (opcjonalnie): służy do selektywnego filtrowania niektórych reguł w celu ich skutecznego zignorowania. Więcej informacji znajdziesz w sekcji filtrów reguł na tej stronie.
  • Klucze agregacji (opcjonalnie): określ podział na segmenty na potrzeby raportów agregowanych.

Opcjonalnie odpowiedź z metadanymi źródła atrybucji może zawierać dodatkowe dane w nagłówku Przekierowania w raportach atrybucji. Dane zawierają przekierowania, które umożliwiają wielu technikom reklamowym zarejestrowanie żądania.

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

Oto przykładowy przepływ pracy:

  1. Pakiet AdTech SDK wywołuje interfejs API, by zainicjować rejestrację źródła atrybucji, określając identyfikator URI, do którego odwołuje się interfejs API:

    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, 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 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 we właściwości Attribution-Reporting-Redirect. W tym przykładzie podano 2 adresy URL partnerów w zakresie 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 z 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ń pokazanych w poprzednich krokach zarejestrowane są 3 źródła atrybucji kliknięć.

Rejestrowanie źródła atrybucji w WebView

WebView obsługuje przypadki użycia, w których aplikacja renderuje reklamę w komponencie WebView. Jest ona obsługiwana przez komponent WebView bezpośrednio wywołujący registerSource() jako żądanie w tle. Powoduje ono powiązanie źródła atrybucji z aplikacją zamiast ze źródłem najwyższego poziomu. Obsługiwane jest też rejestrowanie źródeł z umieszczonych treści z internetu w kontekście przeglądarki. W tym celu należy dostosować ustawienia zarówno wywołania interfejsu API, jak i aplikacje. Instrukcje dotyczące wywołań interfejsu API znajdziesz w sekcji Rejestrowanie źródła atrybucji i aktywatora w komponencie WebView, a instrukcje dotyczące źródeł atrybucji i rejestracji w komponencie WebView w przypadku aplikacji.

Ponieważ technologie reklamowe używają wspólnego kodu w internecie i komponencie WebView, komponent WebView wykonuje przekierowania HTTP 302 i przekazuje prawidłowe rejestracje na platformie. Nie będziemy obsługiwać nagłówka Attribution-Reporting-Redirect w tym scenariuszu, ale jeśli masz problem, którego dotyczy problem, skontaktuj się z nami.

Rejestrowanie reguły (konwersja)

Platformy technologii reklamowych mogą rejestrować reguły – konwersje, np. instalacje czy zdarzenia po instalacji – za pomocą metody registerTrigger().

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

Interfejs API śledzi przekierowania. Odpowiedź serwera technologii reklamowych powinna zawierać nagłówek HTTP Attribution-Reporting-Register-Trigger, który reprezentuje informacje o co najmniej 1 zarejestrowanych aktywatorach. Zawartość nagłówka powinna być zakodowana w formacie JSON i zawierać te pola:

  • Dane reguły: dane identyfikujące zdarzenie reguły (3 bity dla kliknięć, 1 dla widoków). Musi to być 64-bitowa liczba całkowita ze znakiem sformatowana pod postacią ciągu znaków.
  • Priorytet reguły (opcjonalnie): reprezentuje priorytet tej reguły w porównaniu z innymi regułami z tego samego źródła atrybucji. Musi to być 64-bitowa liczba całkowita ze znakiem sformatowana pod postacią ciągu znaków. Więcej informacji o wpływie priorytetów na raportowanie znajdziesz w sekcji na temat priorytetów.
  • Klucz deduplikacji (opcjonalny): służy do identyfikowania przypadków, w których ta sama reguła jest zarejestrowana wielokrotnie przez tę samą platformę technologii reklamowych w przypadku tego samego źródła atrybucji. Musi to być 64-bitowa liczba całkowita ze znakiem sformatowana jako ciąg znaków.
  • Klucze agregujące (opcjonalnie): lista słowników, które określają klucze agregacji, i z których raportów zbiorczych można używać agregacji wartości.
  • Wartości agregacji (opcjonalnie): lista ilości wartości, które są uwzględniane w poszczególnych kluczach.
  • Filtry (opcjonalne): służą do selektywnego filtrowania reguł lub danych aktywujących. Więcej informacji znajdziesz w sekcji filtrów reguł na tej stronie.

Opcjonalnie odpowiedź serwera technologii reklamowych może zawierać dodatkowe dane w nagłówku Attribution Reporting Redirects. Dane zawierają przekierowania, które umożliwiają wielu technikom reklamowym zarejestrowanie żądania.

Kilka technologii reklamowych może zarejestrować to samo zdarzenie reguły za pomocą przekierowań w polu Attribution-Reporting-Redirect lub wielu wywołań metody registerTrigger(). Zalecamy korzystanie z pola klucz deduplikacji, aby uniknąć uwzględniania w raportach zduplikowanych reguł w sytuacji, gdy ta sama technologia reklamowa przekazuje wiele odpowiedzi na to samo zdarzenie reguły. 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 akceptować rejestrację reguł.

Oto przykładowy przepływ pracy:

  1. Pakiet AdTech SDK wywołuje interfejs API, aby zainicjować rejestrację za pomocą wcześniej zarejestrowanego identyfikatora URI. Więcej informacji znajdziesz w artykule Rejestrowanie konta 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
    
  4. Interfejs API wysyła żądanie do każdego adresu URL określonego we właściwości Attribution-Reporting-Redirect. W tym przykładzie określono tylko 1 adres URL, więc interfejs API wysyła żądanie do 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"
    }]
    }
    

    Na podstawie żądań z poprzednich kroków rejestrowane są 2 aktywatory.

Funkcje atrybucji

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

Zastosowano algorytm atrybucji z priorytetem źródła

Interfejs Attribution Reporting API korzysta z algorytmu atrybucji opartego na źródle, który dopasowuje regułę (konwersję) do źródła atrybucji.

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

  • Reguły możesz przypisywać do poszczególnych zdarzeń reklamowych zamiast do innych. Możesz np. skupić się na kliknięciach, a nie na wyświetleniach, lub skupić się na zdarzeniach z określonych kampanii.
  • Możesz skonfigurować źródło atrybucji i regułę w taki sposób, aby po osiągnięciu limitów liczby żądań otrzymywać raporty, które są dla Ciebie ważniejsze. Możesz np. zwiększyć prawdopodobieństwo pojawienia się w tych raportach konwersji z możliwością określenia stawki lub konwersji o wysokiej wartości.

W przypadku gdy wiele technologii reklamowych rejestruje źródło atrybucji, jak opisano to na tej stronie, każda z nich odbywa się niezależnie. W przypadku każdej technologii reklamowej źródło atrybucji o najwyższym priorytecie jest przypisywane do źródła o najwyższym priorytecie. Jeśli jest wiele źródeł atrybucji o takim samym priorytecie, interfejs API wybiera ostatnie zarejestrowane źródło atrybucji. Wszelkie inne źródła atrybucji, które nie zostaną wybrane, są odrzucane i nie kwalifikują się już do przypisywania udziału w konwersji w przyszłości.

Filtry reguł

Rejestracja źródła i aktywatora obejmuje dodatkowe opcjonalne funkcje:

  • Selektywnie filtruj niektóre reguły, skutecznie je ignorując.
  • Wybierz dane reguły na potrzeby raportów na poziomie zdarzenia na podstawie danych źródłowych.
  • Wybierz, czy chcesz wykluczyć regułę z raportów na poziomie zdarzenia.

Aby selektywnie filtrować reguły, technologie reklamowe mogą podczas rejestracji źródła i aktywacji określić dane filtra, które składają się z kluczy i wartości. Jeśli ten sam klucz jest określony zarówno w przypadku źródła, jak i reguły, reguła jest ignorowana, gdy przecięcie jest puste. Na przykład źródło może zawierać ciąg "product": ["1234"], gdzie product to klucz filtra, a 1234 to wartość. Jeśli filtr reguły ma wartość "product": ["1111"], reguła jest ignorowana. Jeśli nie ma żadnego klucza filtra aktywatora pasującego do product, filtry są ignorowane.

Inny scenariusz, w którym platformy z branży technologii reklamowych mogą chcieć selektywnie filtrować reguły, to wymuszenie krótszego okresu ważności. Przy rejestracji reguły specjalista ds. reklam może określić (w sekundach) okres ważności od chwili wystąpienia konwersji. Na przykład 7-dniowy okres ważności będzie zdefiniowany jako: "_lookback_window": 604800 // 7d

Aby określić, czy filtr pasuje, interfejs API najpierw sprawdza okres ważności. Jeśli ta opcja jest dostępna, czas od momentu zarejestrowania źródła musi być krótszy lub równy okresowi ważności.

Platformy z branży technologii reklamowych mogą też wybierać dane reguły na podstawie danych o zdarzeniach źródłowych. Na przykład interfejs source_type jest automatycznie generowany przez interfejs API jako navigation lub event. Podczas rejestracji aktywatora trigger_data można ustawić jako 1 wartość "source_type": ["navigation"] i inną wartość "source_type": ["event"].

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

  • Nie określono żadnego elementu trigger_data.
  • Źródło i reguła określają ten sam klucz filtra, ale wartości się nie zgadzają. 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 reguły po instalacji muszą być przypisane do tego samego źródła atrybucji, które doprowadziło do instalacji, nawet wtedy, gdy inne odpowiednie źródła atrybucji miały miejsce później.

Interfejs API obsługuje ten przypadek użycia, umożliwiając technikom reklamowym ustawienie okresu atrybucji po instalacji:

  • Przy rejestrowaniu źródła atrybucji określ okno atrybucji instalacji, w którym spodziewasz się instalacji (zwykle jest to 2–7 dni, akceptowany zakres od 1 do 30 dni). Podaj ten przedział czasu jako liczbę sekund.
  • Przy rejestrowaniu źródła atrybucji określ okres wyłączności atrybucji po instalacji, w którym wszystkie zdarzenia powodujące wyświetlenie reklamy po instalacji powinny być powiązane ze źródłem atrybucji, który doprowadził do instalacji (zazwyczaj 7–30 dni, akceptowany zakres od 0 do 30 dni). Podaj 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 ze szczególnym uwzględnieniem źródła. Instalacja nie jest jednak wysyłana do technologii reklamowych i nie jest wliczana do limitów liczby żądań na poszczególnych platformach.
  • Weryfikacja instalacji aplikacji jest dostępna dla każdej pobranej aplikacji.
  • Wszystkie przyszłe aktywatory, które wystąpią w okresie atrybucji po instalacji, będą przypisywane do tego samego źródła atrybucji co zweryfikowana instalacja, o ile to źródło atrybucji kwalifikuje się do zastosowania.

W przyszłości możemy rozszerzyć ten projekt o bardziej zaawansowane modele atrybucji.

W tabeli poniżej pokazujemy, jak technologie reklamowe mogą wykorzystywać atrybucję po instalacji. Załóżmy, że wszystkie źródła atrybucji i reguły są rejestrowane przez tę samą sieć technologii reklamowych, a wszystkie priorytety są takie same.

Zdarzenie Dzień, w którym ma miejsce zdarzenie Uwagi
Kliknij 1 1 Ustawiono install_attribution_window na 172800 (2 dni), a dla opcji post_install_exclusivity_window864000 (10 dni)
Zweryfikowana instalacja 2 Interfejs API wewnętrznie przypisuje zweryfikowane instalacje, ale te instalacje nie są uznawane za aktywatory. Dlatego na tym etapie nie wysyłamy żadnych raportów.
Aktywator 1 (pierwsze uruchomienie) 2 Pierwszy aktywator zarejestrowany przez technologię reklamową. W tym przykładzie jest to pierwsze uruchomienie, ale może to być dowolny typ reguły.
Przypisane do kliknięcia 1 (pasuje do atrybucji zweryfikowanej instalacji).
Kliknij 2 4 Używa tych samych wartości w atrybutach install_attribution_window i post_install_exclusivity_window co Kliknięcie 1
Aktywator 2 (po instalacji) 5 Druga reguła zarejestrowana przez technologię reklamową. W tym przykładzie reprezentuje konwersję po instalacji, np. zakup.
Przypisane do kliknięcia 1 (pasuje do atrybucji zweryfikowanej instalacji).
Kliknięcie 2 zostaje odrzucone i nie kwalifikuje się do atrybucji w przyszłości.

Na tej liście znajdziesz dodatkowe uwagi na temat atrybucji po instalacji:

  • Jeśli zweryfikowana instalacja nie nastąpi w ciągu liczby dni określonej przez zasadę install_attribution_window, atrybucja po instalacji nie jest stosowana.
  • Zweryfikowane instalacje nie są rejestrowane przez technologie reklamowe i nie są uwzględniane w raportach. Nie są objęte limitami dotyczącymi technologii reklamowych. Zweryfikowane instalacje są używane tylko do identyfikowania źródła atrybucji, któremu przypisano instalację.
  • W przykładzie z poprzedniej tabeli aktywatory 1 i aktywatory 2 odpowiadają odpowiednio konwersji po pierwszym uruchomieniu i po instalacji. Jednak platformy technologii reklamowych mogą rejestrować dowolny typ reguły. Inaczej mówiąc, pierwsza reguła nie musi być aktywatorem pierwszego uruchomienia.
  • Jeśli po wygaśnięciu okresu post_install_exclusivity_window zarejestrowanych jest więcej reguł, kliknięcie 1 nadal będzie kwalifikować się do atrybucji, o ile nie wygasło i nie osiągnęło jeszcze limitów częstotliwości.
    • Jeśli zarejestrowane jest źródło atrybucji o wyższym priorytecie, kliknięcie 1 może nadal utracić lub zostać odrzucone.
  • Jeśli aplikacja reklamodawcy zostanie odinstalowana i ponownie zainstalowana, ponowne zainstalowanie jest liczone jako nowa zweryfikowana instalacja.
  • Jeśli kliknięcie 1 było zdarzeniem wyświetlenia, przypisywane są do niego zarówno reguły „pierwsze uruchomienie”, jak i po instalacji. Interfejs API ogranicza atrybucję do 1 reguły na widok. Wyjątkiem jest atrybucja po instalacji, w której dozwolone są maksymalnie 2 reguły na wyświetlenie. W przypadku atrybucji po instalacji technologia reklamowa może otrzymać 2 różne okna raportowania (po 2 dniach lub po wygaśnięciu u źródła).

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

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

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

Zezwalamy przeglądarkom na obsługę nowych funkcji dostępnych w internecie, takich jak funkcje podobne do Piaskownicy prywatności dla internetowych interfejsów Attribution Reporting API, które mogą wywoływać interfejsy API Androida, aby umożliwić atrybucję w aplikacjach i internecie.

Dowiedz się więcej o zmianach, jakie muszą wprowadzić technologie reklamowe i aplikacje, aby obsługiwać ścieżki reguł na potrzeby pomiarów w różnych aplikacjach i witrynach.

Nadawanie priorytetów większej liczbie reguł do jednego źródła atrybucji

Jedno źródło atrybucji może wpływać na wiele reguł. Na przykład proces zakupu może obejmować regułę „instalacja aplikacji”, jedną lub więcej reguł „dodanie do koszyka” oraz „zakup”. Każda reguła jest przypisywana do co najmniej 1 źródła atrybucji zgodnie z algorytmem atrybucji opartym na źródle, który został opisany w dalszej części tej strony.

Istnieją limity dotyczące 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 poświęconej wyświetlaniu danych pomiarowych w raportach atrybucji. Jeśli jest wiele aktywatorów wykraczających poza te limity, warto wprowadzić logikę ustalania priorytetów, aby przywrócić najbardziej wartościowe aktywatory. Deweloperzy aplikacji reklamowej mogą np. traktować priorytetowo generowanie reguł „zakup” zamiast reguł „dodanie do koszyka”.

Aby obsługiwać tę logikę, wyzwalacz może mieć osobne pole priorytetu, a reguły o najwyższym priorytecie są wybierane przed zastosowaniem limitów w danym okresie raportowania.

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

Raporty atrybucji często otrzymują więcej niż 1 technologia reklamowa. Zwykle służą do usuwania duplikatów między sieciami. Dlatego interfejs API umożliwia wielu technikom reklamowym rejestrowanie tego samego źródła atrybucji lub tej samej reguły. Technologia reklamowa musi zarejestrować zarówno źródła atrybucji, jak i aktywatory, aby otrzymywać wywołania zwrotne z interfejsu API. Atrybucja odbywa się między źródłami i regułami atrybucji zarejestrowanymi przez daną technologię w interfejsie API.

Reklamodawcy, którzy chcą korzystać z usługi zewnętrznej do duplikowania danych międzysieciowych, mogą nadal to robić, stosując metodę podobną do tej:

  • Skonfigurowanie własnego serwera do rejestrowania i odbierania raportów za pomocą interfejsu API.
  • dalsze korzystanie z usług dotychczasowego partnera świadczącego usługi pomiaru danych mobilnych.

Źródła atrybucji

Przekierowania źródła atrybucji są obsługiwane w metodzie registerSource():

  1. Technologia reklamowa, która wywołuje w odpowiedzi metodę registerSource(), może podać dodatkowe pole Attribution-Reporting-Redirect, które reprezentuje zestaw adresów URL przekierowań partnera.
  2. Interfejs API wywołuje następnie przekierowania, dzięki czemu technicy reklamowi partnerów mogą zarejestrować źródło atrybucji.

W polu Attribution-Reporting-Redirect może znajdować się wiele adresów URL technologii reklamowych partnerów, a technologie reklam partnerów nie mogą określać własnych pól Attribution-Reporting-Redirect.

Interfejs API umożliwia też różnym technikom reklamowym wywoływanie każdego wywołania registerSource().

Aktywatory

W przypadku rejestracji reguły firmy zewnętrzne są obsługiwane w podobny sposób: technologie reklamowe mogą korzystać z dodatkowego pola Attribution-Reporting-Redirect lub wywoływać metodę registerTrigger().

Jeśli reklamodawca korzysta z wielu technologii reklamowych, aby rejestrować to samo zdarzenie reguły, należy użyć klucza deduplikacji. Klucz deduplikacji służy do rozróżniania powtarzających się raportów o tym samym zdarzeniu zarejestrowanych na tej samej platformie technologii reklamowych. Na przykład pakiet SDK dewelopera może mieć bezpośrednie wywołanie interfejsu API, aby zarejestrować regułę, a jego adres URL w polu przekierowania wywołania innego techniki reklamowej. Jeśli nie podasz klucza do usuwania duplikatów, duplikaty reguł mogą być zgłaszane w raportach dla każdej technologii reklamowej jako unikalne.

Obsługa zduplikowanych wyzwalaczy

Technolog reklam może wielokrotnie zarejestrować tę samą regułę za pomocą interfejsu API. Dostępne scenariusze to m.in.:

  • Użytkownik wielokrotnie wykonuje tę samą czynność (regułę). Na przykład: użytkownik przegląda ten sam produkt wiele razy w tym samym oknie raportowania.
  • Aplikacja reklamodawcy korzysta z wielu pakietów SDK do pomiaru konwersji, które przekierowują do tej samej technologii reklamowej. Na przykład aplikacja reklamodawcy korzysta z 2 partnerów świadczących usługi pomiarowe: MMP 1 i MMP 2. Obie MMP przekierowują do technologii reklamowej nr 3. Gdy wystąpi wyzwalacz, obie platformy MMP rejestrują go za pomocą interfejsu Attribution Reporting API. Technologia reklamowa 3 otrzymuje następnie 2 osobne przekierowania dla tej samej reguły – jedno z MMP 1 i z MMP 2.

Istnieje kilka sposobów na pomijanie raportów na poziomie zdarzenia w takich przypadkach, by zmniejszyć prawdopodobieństwo przekroczenia limitów stawek obowiązujących w raportach na poziomie zdarzenia. Zalecanym sposobem jest użycie klucza do usuwania duplikatów.

Zalecana metoda: klucz deduplikacji

Zalecana metoda polega na przekazaniu przez aplikację reklamodawcy unikalnego klucza deduplikacji do dowolnych technologii reklamowych lub pakietów SDK, których używa do pomiaru konwersji. Gdy następuje konwersja, aplikacja przekazuje klucz deduplikacji do technologii reklamowych lub pakietów SDK. Następnie technologie reklamowe lub pakiety SDK przekazują klucz deduplikacji do przekierowań, używając parametru w adresach URL określonych w zasadzie Attribution-Reporting-Redirect.

Technologie reklamowe mogą zarejestrować tylko pierwszą regułę za pomocą danego klucza deduplikacji lub zarejestrować wiele reguł albo wszystkie. Technologie reklamowe mogą określić deduplication_key podczas rejestrowania zduplikowanych reguł.

Jeśli specjalista ds. technologii reklamowych zarejestruje wiele reguł z tym samym kluczem deduplikacji i przypisanym źródłem, w raportach na poziomie zdarzenia zostanie wysłana tylko pierwsza zarejestrowana reguła. Zduplikowane reguły są nadal wysyłane w zaszyfrowanych raportach zbiorczych.

Metoda alternatywna: technologie reklamowe uzgadniają typy reguł zależnych od reklamodawcy

W sytuacjach, gdy technologie reklamowe nie chcą używać klucza do usuwania duplikatów lub gdy aplikacja reklamodawcy nie może przekazać tego klucza, istnieje alternatywna opcja. Wszyscy technicy reklamodawcy, którzy mierzą konwersje w przypadku danego reklamodawcy, muszą współpracować, by zdefiniować różne typy reguł dla każdego z nich.

Technologie reklamowe, które inicjują wywołanie rejestracji aktywatora (np. pakiety SDK), dodają parametr w adresach URL określonych w zasadzie Attribution-Reporting-Redirect, np. duplicate_trigger_id. Parametr duplicate_trigger_id może zawierać takie informacje jak nazwa pakietu SDK i typ aktywatora danego reklamodawcy. Technologie reklamowe mogą następnie wysłać podzbiór tych zduplikowanych reguł do raportów na poziomie zdarzenia. Technologie reklamowe mogą też uwzględnić ten duplicate_trigger_id w swoich kluczach agregacji.

Przykład atrybucji międzysieciowej

W przykładzie opisanym w tej sekcji reklamodawca używa 2 platform technologii reklamowych (technologia reklamowa A i technologii reklamowej B) i 1 partnera świadczącego usługi pomiaru.

Na początek technologie reklamowe A, technologie reklamowe B i MMP muszą ukończyć rejestrację, aby móc korzystać z interfejsu Attribution Reporting API. Więcej informacji znajdziesz w artykule Rejestrowanie konta Piaskownicy prywatności.

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

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

Technika A reklam wywołuje element registerSource(), podając identyfikator URI. Interfejs API wysyła żądanie do identyfikatora URI, a kliknięcie jest rejestrowane za pomocą metadanych z odpowiedzi serwera AdTech A.

Technologia reklam A zawiera też w nagłówku Attribution-Reporting-Redirect identyfikator URI MMP. Interfejs API wysyła żądanie do identyfikatora URI MMP, a kliknięcie jest rejestrowane za pomocą metadanych z odpowiedzi serwera MMP.

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

AdTech B wywołuje funkcję registerSource(), podając jej identyfikator URI. Interfejs API wysyła żądanie do identyfikatora URI, a kliknięcie jest rejestrowane za pomocą metadanych z odpowiedzi serwera AdTech B.

Podobnie jak w technologii reklam A, technologia Ad B uwzględniła też identyfikator URI MMP w nagłówku Attribution-Reporting-Redirect. Interfejs API wysyła żądanie do identyfikatora URI MMP, a kliknięcie jest rejestrowane za pomocą metadanych z odpowiedzi serwera MMP.

Dzień 3: użytkownik ogląda reklamę wyświetlaną przez technologię reklamową A

Interfejs API odpowiada tak samo jak w dniu 1, z tą różnicą, że wyświetlenie jest zarejestrowane przez AdTech A i MMP.

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

MMP wywołuje registerTrigger(), podając identyfikator URI. Interfejs API wysyła żądanie na adres URL, a konwersja jest rejestrowana za pomocą metadanych z odpowiedzi serwera MMP.

MMP umieszcza też w nagłówku Attribution-Reporting-Redirect identyfikatory URI reklam w technologii A i B. Interfejs API wysyła żądania do serwerów technologii reklamowej A i technologii reklamowej B, a konwersja jest odpowiednio zarejestrowana za pomocą metadanych 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 nadaje priorytet kliknięciom wyższym niż liczba wyświetleń, dzięki czemu instalacja ta jest przypisywana kliknięciu pierwszego dnia.
  • AdTech B uzyskuje instalację przypisaną drugiego dnia.
  • W ramach MMP priorytet kliknięć jest wyższy niż liczba wyświetleń, a instalacja jest przypisywana do kliknięcia drugiego dnia. Kliknięcie drugiego dnia ma najwyższy priorytet i najnowsze zdarzenie reklamowe.

Atrybucja międzysieciowa bez przekierowań

Chociaż zalecamy stosowanie przekierowań, aby umożliwić wielu technikom reklamowym rejestrowanie źródeł i reguł atrybucji, zdajemy sobie sprawę, że mogą wystąpić sytuacje, w których użycie przekierowań może być niemożliwe. Z tej sekcji dowiesz się, jak obsługiwać atrybucję międzysieciową bez przekierowań.

Przepływ na wysokim poziomie

  1. Po rejestracji źródła sieć technologii reklamowych udostępnia swoje źródłowe klucze agregacji.
  2. Podczas rejestracji reguły reklamodawca lub partner świadczący usługi pomiarowe wybiera, których elementów kluczy po stronie źródła używać, oraz określa ich konfigurację atrybucji.
  3. Atrybucja opiera się na konfiguracji atrybucji, udostępnionych kluczach i wszelkich źródłach, które zostały faktycznie zarejestrowane przez tego reklamodawcę lub partnera świadczącego usługi pomiaru (np. z innej sieci technologii reklamowych, która włączyła przekierowania).
  4. Jeśli reguła zostanie przypisana do źródła z technologii reklamowej nieprzekierowującej, reklamodawca lub partner świadczący usługi pomiaru może otrzymać zagregowany raport, który łączy źródło i kluczowe elementy aktywujące określone w kroku 2.

Rejestracja źródła

Przy rejestracji źródła sieć technologii reklamowych wyświetlających reklamy może udostępnić swoje źródłowe klucze agregacji lub podzbiór swoich kluczy agregacji źródeł, zamiast stosować przekierowanie. Technologia wyświetlania reklam nie musi używać tych kluczy źródłowych w swoich własnych raportach zbiorczych. W razie potrzeby może je zadeklarować tylko w imieniu reklamodawcy lub partnera świadczącego usługi pomiaru.

Udostępnione klucze agregacji są dostępne dla wszystkich technologii reklamowych, które rejestrują regułę dla tego samego reklamodawcy. Jednak to od technologii reklam, która się wyświetla, i technologii reklamowej służących do pomiaru czynników uruchamiających, zależy jednak od współpracy nad potrzebnymi typami kluczy agregacji, ich nazw i sposobu dekodowania kluczy na czytelne wymiary.

Rejestracja aktywatora

Podczas rejestracji reguły technologia reklam pomiarowych wybiera klucze po stronie źródła, które mają być zastosowane do poszczególnych elementów klucza reguły, w tym te udostępniane przez technologie reklamowe.

Dodatkowo technologia reklam pomiarowych musi również określić logikę atrybucji kaskady za pomocą nowego wywołania interfejsu API konfiguracji atrybucji. W tej konfiguracji technologia reklamowa może określać priorytet i wygaśnięcie źródła oraz filtry w przypadku źródeł, w których nie ma wglądu (np. źródeł, które nie skorzystały z przekierowania).

Atrybucja

Interfejs Attribution Reporting API wykonuje priorytetową atrybucję ostatniego punktu kontaktu na potrzeby technologii reklam 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 dostawcy technologii reklamowych do pomiaru skuteczności reklam.
  • Technologia reklam A przekierowuje swoje źródła do MMP.
  • Technologie reklamowe B i C nie przeprowadzają przekierowywania, ale udostępniają swoje klucze agregacji.
  • AdTech 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 technologię D reklam.

Atrybucja MMP obejmuje teraz:

  • technologii reklamowej A, ponieważ MMP zarejestrował źródło z przekierowania tej technologii reklamowej.
  • AdTech B, ponieważ w konfiguracji atrybucji uwzględniono klucze udostępnione przez usługę AdTech B, a MMP uwzględniło je w swojej konfiguracji atrybucji.

Atrybucja MMP nie obejmuje:

  • AdTech C, ponieważ MMP nie uwzględniło go w konfiguracji atrybucji.
  • AdTech D, ponieważ nie przekierowywał ani nie współużytkował kluczy agregacji.

Debugowanie

Aby ułatwić debugowanie atrybucji międzysieciowej bez przekierowań, technicy ds. reklam udostępniają dodatkowe pole shared_debug_key, które można ustawić przy rejestracji źródła. Jeśli ustawisz ją w pierwotnej rejestracji źródłowej, zostanie ona też ustawiona w odpowiednim źródle pochodnym jako debug_key podczas rejestracji aktywatora na potrzeby atrybucji międzysieciowej bez przekierowań. Ten klucz debugowania jest dołączony do raportów o zdarzeniach i zbiorczych jako source_debug_key.

Ta funkcja debugowania będzie obsługiwana w przypadku atrybucji międzysieciowej bez przekierowań:

  • Pomiary z aplikacji do aplikacji, w których dozwolony jest identyfikator AdId,
  • Pomiary z aplikacji do witryny, w których identyfikator AdId jest dozwolony i dopasowywany zarówno w źródle aplikacji, jak i w ramach reguły powiązanej z witryną.
  • pomiar danych z sieci do internetu (w tej samej aplikacji przeglądarki), gdy parametr ar_debug występuje zarówno w źródle, jak i w aktywatorze.

Odkrywanie najważniejszych informacji do atrybucji międzysieciowej bez przekierowań

Wykrywanie kluczy ma na celu uproszczenie sposobu, w jaki technologie reklamowe (zwykle MMP) implementują swoją konfigurację atrybucji na potrzeby atrybucji międzysieciowej, gdy co najmniej jedna z tych technologii reklam wyświetlających reklamy korzysta ze wspólnych kluczy agregacji (jak opisano w sekcji Atrybucja międzysieciowa bez przekierowań).

Gdy MMP wysyła zapytanie do usługi agregującej, aby wygenerować raporty podsumowujące dla kampanii, które zawierają źródła pochodne, usługa agregacji wymaga od MMP określenia listy możliwych kluczy jako danych wejściowych dla zadania agregacji. W niektórych przypadkach lista potencjalnych kluczy agregacji źródeł może być bardzo duża lub nieznana. Duża lista możliwych kluczy jest trudna do śledzenia, a także dość złożona i kosztowna w obsłudze. Rozważmy następujące przykłady:

  • Lista wszystkich możliwych kluczy jest bardzo długa:
    • Sieć reklamowa, która wyświetla reklamy, realizuje złożoną inicjatywę pozyskiwania użytkowników obejmującą 20 kampanii, każdą z 10 grupami reklam, a każdą grupę reklam zawierającą 5 kreacji, które są odświeżane co tydzień w zależności od skuteczności reklam.
  • Lista wszystkich możliwych kluczy jest nieznana:
    • Sieć reklamowa wyświetla reklamy w wielu aplikacjach mobilnych, gdy pełna lista identyfikatorów aplikacji wydawcy nie jest znana w momencie uruchamiania kampanii.
    • Reklamodawca korzysta z wielu sieci reklamowych, które podczas rejestracji źródła nie przekierowują do MMP. Każda wyświetlana sieć reklamowa ma inną strukturę klucza i wartości, które mogą nie być udostępniane z wyprzedzeniem MMP.

Po wprowadzeniu funkcji odkrywania treści:

  • Usługa agregacji nie wymaga już pełnego wyliczenia możliwych kluczy agregacji.
  • Zamiast określać pełną listę możliwych kluczy, MMP może utworzyć pusty (lub częściowo pusty) zestaw kluczy i ustawić próg, tak aby w danych wyjściowych znalazły się tylko klucze (niezdefiniowane) z wartościami przekraczającymi próg.
  • MMP otrzymuje raport podsumowujący, który uwzględnia zaszumione wartości kluczy, których składowe wartości przekraczają ustalony próg. Raport może też zawierać klucze, które nie są powiązane z prawdziwymi użytkownikami i są czyste, zaszumiane.
  • MMP używa pola x_network_bit_mapping podczas rejestracji reguły do określania, która technologia reklamowa odpowiada któremu kluczowi.
  • MMP może następnie skontaktować się z odpowiednim technikiem wyświetlania reklam, aby poznać 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.

Wyświetlanie danych pomiarowych w raportach atrybucji

Interfejs Attribution Reporting API umożliwia generowanie tych typów raportów, które zostały szczegółowo opisane na tej stronie:

  • Raporty na poziomie zdarzenia przypisują określone źródło atrybucji (kliknięcie lub wyświetlenie) z ograniczoną ilością danych o wysokiej jakości.
  • Raporty agregujące nie muszą być powiązane z konkretnym źródłem atrybucji. Raporty te zapewniają bogatsze dane dotyczące reguł niż raporty na poziomie zdarzenia, ale są dostępne tylko w postaci zbiorczej.

Te 2 typy raportów wzajemnie się uzupełniają i można ich używać równocześnie.

Raporty na poziomie zdarzenia

Po przypisaniu reguły do źródła atrybucji raport na poziomie zdarzenia jest generowany i przechowywany na urządzeniu, dopóki nie będzie można go odesłać na adres URL wywołania zwrotnego każdej technologii reklamowej w jednym z przedziałów czasowych na wysyłanie raportów, które opisano bardziej szczegółowo na tej stronie.

Raporty na poziomie zdarzenia są przydatne, gdy potrzebnych jest niewiele informacji o reguły. Dane reguły na poziomie zdarzenia są ograniczone do 3 bitów danych reguły dla kliknięć, co oznacza, że regułę można przypisać do jednej z 8 kategorii, i 1 bitu dla widoków. Raporty na poziomie zdarzenia nie obsługują też kodowania wysokiej jakości danych po stronie reguły, takich jak określona cena lub czas aktywacji. Atrybucja odbywa się na urządzeniu, więc raporty na poziomie zdarzenia nie obsługują analizy różnych urządzeń.

Raport na poziomie zdarzenia zawiera m.in. te dane:

  • Miejsce docelowe: nazwa pakietu aplikacji reklamodawcy lub adres eTLD + 1, w którym wystąpił wyzwalacz.
  • Attribution Source ID: (Identyfikator źródła atrybucji): ten sam identyfikator źródła atrybucji, który został użyty do rejestracji źródła atrybucji
  • Typ reguły: 1 lub 3 bity danych aktywujących o niskiej wierności w zależności od typu źródła atrybucji.

Mechanizmy chroniące prywatność stosowane we wszystkich raportach

Po uwzględnieniu priorytetów związanych ze źródłami atrybucji i regułami obowiązują te limity.

Ograniczenia liczby technologii reklamowych

Liczba specjalistów reklamowych, którzy mogą rejestrować lub otrzymywać raporty za pomocą interfejsu API, jest ograniczona. Oto one:

  • 100 technologii reklamowych ze źródłami atrybucji na {aplikacja źródłowa, aplikacja docelowa, 30 dni, urządzenie}.
  • 10 technologii reklamowych z przypisanymi regułami na {aplikacja źródłowa, aplikacja docelowa, 30 dni, urządzenie}.
  • 20 technologów reklamowych może zarejestrować 1 źródło lub regułę atrybucji (za pomocą Attribution-Reporting-Redirect)

Ograniczenia liczby niepowtarzalnych miejsc docelowych

Te limity utrudniają kilku technikom reklamowym analizę zachowań użytkowników korzystających z aplikacji przez wysyłanie zapytań do dużej liczby aplikacji.

  • We wszystkich zarejestrowanych źródłach i we wszystkich technologiach reklamowych interfejs API obsługuje maksymalnie 200 niepowtarzalnych miejsc docelowych na aplikację źródłową na minutę.
  • W przypadku wszystkich zarejestrowanych źródeł w przypadku jednej technologii reklamowej interfejs API obsługuje maksymalnie 50 niepowtarzalnych miejsc docelowych na aplikację źródłową na minutę. Dzięki temu 1 technologia reklamowa nie może wykorzystać całego budżetu z wcześniej wspomnianego limitu stawki.

Wygasłe źródła nie wliczają się do limitów liczby.

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

Platforma technologii reklamowych może używać tylko jednego źródła raportowania do rejestrowania źródeł w aplikacji wydawcy na danym urządzeniu w danym dniu. To ograniczenie liczby żądań uniemożliwia technikom reklamowym korzystanie z wielu źródeł raportowania w celu uzyskania dostępu do dodatkowego budżetu na ochronę prywatności.

Rozważmy taki scenariusz: 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 źródło raportowania 2 technologii reklamowej A podejmuje próbę zarejestrowania źródła w aplikacji B.

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

Limity czasu oczekiwania i częstotliwoś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 w przypadku użytkownika.

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

Liczba niepowtarzalnych miejsc docelowych

Interfejs API ogranicza liczbę miejsc docelowych, które technika reklamowa może spróbować zmierzyć. Im niższy limit, tym trudniej technologii reklamowej użyć interfejsu API, aby zmierzyć aktywność użytkowników, która nie jest związana z wyświetlaniem reklam.

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

Mechanizmy chroniące prywatność stosowane w raportach na poziomie zdarzenia

Ograniczona dokładność danych aktywatora

Interfejs API udostępnia 1 bit dla aktywatorów po wyświetleniu i 3 bity dla reguł po kliknięciu. Źródła atrybucji nadal obsługują pełne 64-bitowe metadane.

Zastanów się, czy i jak zmniejszyć ilość informacji wyrażanych w regułach, tak aby działały z ograniczoną liczbą bitów dostępnych w raportach na poziomie zdarzenia.

Platforma szumu różnicowego

Ten interfejs API ma umożliwić pomiar na poziomie zdarzenia w celu spełnienia lokalnych wymagań dotyczących prywatności różnicowej przez wykorzystanie losowych odpowiedzi k w celu generowania zaszumionych danych wyjściowych dla każdego zdarzenia źródłowego.

Szum jest stosowany do tego, czy zdarzenie źródła atrybucji jest raportowane zgodnie z prawdą. Źródło atrybucji jest rejestrowane na urządzeniu z prawdopodobieństwem $ 1-p $, że dane źródło jest zarejestrowane jako normalne, oraz z prawdopodobieństwem $ p $, że urządzenie wybierze losowo ze wszystkich możliwych stanów wyjściowych interfejsu API (w tym niczego nie zgłasza lub zgłasza wiele fałszywych raportów).

Odpowiedź k-losowa jest algorytmem, który jest prywatny epsilon, jeśli spełnione jest to równanie:

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

W przypadku niskich wartości ? rzeczywiste dane wyjściowe są chronione przez mechanizm losowej odpowiedzi k. Obecnie pracujemy nad filtrowaniem parametrów dokładnego szumu i mogą się one zmienić w zależności od opinii, a w obecnej ofercie:

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

Limity dostępnych reguł (konwersji)

W ramach obecnej oferty pakietowej obowiązują limity liczby reguł na źródło atrybucji:

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

Określone przedziały czasowe wysyłania raportów (działanie domyślne)

Raporty na poziomie zdarzenia dotyczące źródeł atrybucji wyświetleń reklamy są wysyłane godzinę po wygaśnięciu źródła. Datę ważności możesz skonfigurować, ale nie może ona być krótsza niż 1 dzień ani więcej 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 można wysyłać w okresach okien raportowania określonych poniżej.

Nie można skonfigurować raportów na poziomie zdarzenia związanych ze źródłami atrybucji kliknięć reklamy i są one wysyłane przed wygaśnięciem źródła lub po jego wygaśnięciu w określonym czasie w odniesieniu do jego rejestracji. Czas między źródłem atrybucji a wygaśnięciem konta jest podzielony na kilka okien raportowania. Każde okno raportowania ma określony termin (od momentu źródła atrybucji). Po zakończeniu każdego okresu raportowania urządzenie zbiera wszystkie wyzwalacze, które wystąpiły od czasu 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 najpóźniej 2 dni po zarejestrowaniu źródła atrybucji. Raport jest wysyłany 2 dni i godzinę po zarejestrowaniu źródła atrybucji.
  • 7 dni: urządzenie zbiera wszystkie reguły, które wystąpiły ponad 2 dni po zarejestrowaniu źródła atrybucji, ale nie później niż 7 dni. Raport jest wysyłany 7 dni i godzinę po zarejestrowaniu źródła atrybucji.
  • Niestandardowy czas trwania zdefiniowany przez atrybut „expiry” źródła atrybucji. Raport jest wysyłany 1 godzinę po określonym czasie wygaśnięcia. Ta wartość nie może być krótsza niż 1 dzień ani większa niż 30 dni.

Elastyczna konfiguracja na poziomie zdarzenia

Domyślna konfiguracja raportowania na poziomie zdarzenia jest tą, którą zalecamy technikom reklamowym na początku testów praktycznych, ale może nie być idealna w niektórych przypadkach użycia. Attribution Reporting API będzie obsługiwać opcjonalne i bardziej elastyczne konfiguracje, które zapewniają technikom reklamowym większą kontrolę nad strukturą raportów na poziomie zdarzenia i mogą maksymalizować użyteczność danych.

Tę dodatkową elastyczność wprowadzimy w interfejsie Attribution Reporting API w dwóch etapach:

  • Etap 1. Elastyczna konfiguracja na poziomie zdarzenia w wersji uproszczonej
    • Ta wersja zapewnia podzbiór pełnych funkcji i można jej używać niezależnie od fazy 2.
  • Etap 2. Pełna wersja elastycznej konfiguracji na poziomie zdarzenia

Faza 1 (elastyczny poziom zdarzenia w wersji Lite) pozwala:

  • Różnicuj częstotliwość wysyłania raportów, określając liczbę okien raportowania.
  • Różnicuj liczbę atrybucji w poszczególnych rejestracjach źródła
  • Zmniejsz całkowitą ilość szumu, zmniejszając powyższe parametry.
  • Skonfiguruj okna raportowania zamiast używać domyślnych

Faza 2 (w pełni elastyczny poziom zdarzenia) pozwala wykorzystać wszystkie możliwości dostępne w fazie 1 oraz:

  • Zróżnicowanie mocy zbioru danych reguły w raporcie
  • Zmniejsz całkowitą ilość szumu, zmniejszając moc zbioru danych aktywujących

Zmniejszenie jednego wymiaru w konfiguracji domyślnej umożliwia technologii reklamowej zwiększenie kolejnego wymiaru. Z kolei łączna ilość szumu w raporcie na poziomie zdarzenia może zostać zmniejszona przez zmniejszenie wartości parametrów wspomnianych powyżej.

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

  • Maksymalnie 20 raportów łącznie (globalnie i na aktywator_danych).
  • Maksymalnie 5 możliwych okresów raportowania na dane aktywatora
  • Maksymalnie 32 – moc zbioru danych aktywujących (nie dotyczy fazy 1. Elastyczny poziom zdarzenia w wersji Lite)

Gdy technologie reklamowe zaczną korzystać z tej funkcji, pamiętaj, że używanie wartości ekstremalnych może spowodować dużą ilość szumu lub brakować rejestracji w przypadku nieprzestrzegania poziomów prywatności.

Raporty zbiorcze

Zanim zaczniesz korzystać z raportów zbiorczych, musisz skonfigurować konto w chmurze i zacząć otrzymywać raporty zbiorcze.

Raporty zbiorcze dostarczają z urządzenia więcej wiernych danych o regułach niż te dostępne w przypadku raportów na poziomie zdarzenia. Te precyzyjne dane można poznać tylko w ramach zagregowanych i nie są powiązane z konkretną regułą ani użytkownikiem. Klucze agregacji mają do 128 bitów, dzięki czemu raporty agregowane mogą być wykorzystywane do raportowania takich przypadków, jak:

  • Raporty dotyczące wartości reguł, np. przychodów
  • Obsługa większej liczby typów aktywatorów

Dodatkowo raporty zbiorcze korzystają z tych samych zasad 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 wygląd i sposób przygotowywania i wysyłania raportów zbiorczych przez Attribution Reporting API wygląda tak:

  1. Urządzenie wysyła do technologii reklamowej zaszyfrowane raporty zbiorcze. W środowisku produkcyjnym technicy reklam nie mogą korzystać z tych raportów bezpośrednio.
  2. Technologia reklam wysyła do usługi agregującej zbiorcze raporty w celu ich agregacji.
  3. Usługa agregująca odczytuje grupę raportów zbiorczych, odszyfrowuje ją i agreguje.
  4. Końcowe dane zbiorcze są przesyłane z powrotem do technologii reklamowej w raporcie podsumowującym.
Proces, którego interfejs Attribution Reporting API używa do przygotowywania i wysyłania raportów zbiorczych.

Raporty zbiorcze zawierają te dane związane ze źródłami atrybucji:

  • Miejsce docelowe: nazwa pakietu aplikacji lub adres URL eTLD + 1, gdzie wystąpił wyzwalacz.
  • Data: data wystąpienia zdarzenia reprezentowanego przez źródło atrybucji.
  • Ładunek: wartości aktywatora zebrane w postaci zaszyfrowanych par klucz/wartość, które są używane przez zaufanej usłudze agregacji do obliczania agregacji.

Usługi agregacji

Opisane poniżej usługi zapewniają funkcję agregacji i pomagają chronić przed nieodpowiednim dostępem do danych zbiorczych.

Tymi usługami zarządzają różne podmioty, które zostały szczegółowo opisane na tej stronie:

  • Usługa agregacji to jedyna usługa, którą technicy reklam mają wdrażać.
  • Usługi zarządzania kluczami i księgowania raportów zbiorczych są uruchamiane przez zaufane podmioty nazywane koordynatorami. Koordynatorzy poświadczają, że kod obsługujący usługę agregacji jest publicznie dostępnym kodem udostępnionym przez Google i że wszyscy użytkownicy usług agregacji mają do nich ten sam klucz i usługi księgowe z możliwością agregacji raportów.
Usługa agregacji

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

Ta usługa agregacji działa w zaufanym środowisku wykonawczym (TEE) hostowanym w chmurze. TEE zapewnia następujące korzyści w zakresie bezpieczeństwa:

  • Zapewnia on, że kod działający w TEE to konkretny plik binarny oferowany przez Google. Jeśli ten warunek nie jest spełniony, usługa agregacji nie ma dostępu do kluczy odszyfrowywania, których potrzebuje do działania.
  • Zapewnia bezpieczeństwo działającego procesu, izoluje go od monitorowania lub ingerencji z zewnątrz.

Dzięki tym zaletom zabezpieczeń usługi agregujące mogą bezpieczniej wykonywać operacje poufne, np. uzyskiwać dostęp do zaszyfrowanych danych.

Więcej informacji na temat projektowania, przepływu pracy i kwestii bezpieczeństwa w usłudze agregacji znajdziesz w dokumentacji usługi agregacji w serwisie GitHub.

Usługa zarządzania kluczami

Ta usługa sprawdza, czy usługa agregacji używa zatwierdzonej wersji pliku binarnego, a następnie udostępnia usłudze agregacji w technologii reklamowej prawidłowe klucze odszyfrowywania danych aktywatorów.

Agregujące raporty księgowe

Ta usługa śledzi, jak często usługa agregacji technologii reklamowej uzyskuje dostęp do określonego aktywatora – który może zawierać wiele kluczy agregacji – i ogranicza dostęp do odpowiedniej liczby odszyfrowań. Więcej informacji znajdziesz w sekcji poświęconej usłudze agregacji oferty pakietowej Attribution Reporting API.

Interfejs API raportów zbiorczych

Interfejs API służący do tworzenia raportów zbiorczych korzysta z tego samego podstawowego interfejsu API co przy rejestrowaniu źródła atrybucji na potrzeby raportów na poziomie zdarzenia. W sekcjach poniżej opisujemy rozszerzenia interfejsu API.

Rejestrowanie agregowanych danych źródłowych

Gdy interfejs API wysyła żądanie do identyfikatora URI źródła atrybucji, specjalista ds. reklam może zarejestrować listę kluczy agregacji o nazwie histogram_contributions, odpowiadając na nowe pole o nazwie aggregation_keys w nagłówku HTTP Attribution-Reporting-Register-Source, gdzie klucz to key_name, a wartość jako key_piece:

  • (Klucz) Nazwa klucza: ciąg znaków nazwy klucza. Służy jako klucz łączenia do łączenia z kluczami po stronie aktywatora w celu utworzenia klucza końcowego.
  • (Wartość) Klucz: wartość ciągu bitowego klucza.

Końcowy klucz histogramu jest w pełni zdefiniowany w momencie aktywowania przez wykonanie operacji binarnej LUB na tych elementach i elementach po stronie aktywatora.

Klucze końcowe mogą mieć maksymalnie 128 bitów, a dłuższe klucze są obcięte. Oznacza to, że ciągi szesnastkowe w pliku JSON powinny mieć maksymalnie 32 cyfry.

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

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

  • Agregacja liczby 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"
}

Rejestrowanie aktywatora agregowanego

Rejestracja aktywatora zawiera 2 dodatkowe pola.

Pierwsze pole służy do rejestrowania listy kluczy zbiorczych po stronie aktywatora. Technologia reklamowa powinna odpowiedzieć z użyciem pola aggregatable_trigger_data w nagłówku HTTP Attribution-Reporting-Register-Trigger z tymi polami w przypadku każdego klucza zbiorczego z listy:

  • Klucz: ciąg znaków bitowy klucza.
  • Klucze źródłowe: lista ciągów tekstowych z nazwami kluczy bocznych źródła atrybucji, z którymi klucz aktywatora należy połączyć, by utworzyć klucze końcowe.

Drugie pole służy do rejestrowania listy wartości, które powinny odpowiadać poszczególnym kluczom. Technologia reklamowa powinna odpowiedzieć, używając pola aggregatable_values w nagłówku HTTP Attribution-Reporting-Register-Trigger. Drugie pole służy do rejestrowania listy wartości, które powinny zostać przypisane do każdego klucza. Mogą to być liczby całkowite w zakresie $ [1, 2^{16}] $.

Każda reguła może mieć wiele udziałów w raportach zbiorczych. Całkowita liczba udziałów (wartości) w danym zdarzeniu źródłowym jest ograniczona przez parametr $ L1 $, który stanowi maksymalną sumę darowizn (wartości) we wszystkich kluczach zbiorczych dla danego źródła. Odnosi się do czułości lub normy L1 histogramu dla poszczególnych zdarzeń źródłowych. Przekroczenie tych limitów spowoduje, że treści publikowane w przyszłości będą dyskretnie spadać. Początkowa propozycja zakłada ustawienie $ L1 $ na 2^{16} USD (65 536).

Szum w usłudze agregacji jest skalowany proporcjonalnie do tego parametru. Z tego względu zalecamy odpowiednie skalowanie wartości raportowanych dla danego klucza zbiorczego na podstawie przydzielonej do niego części budżetu L1 USD. Ta metoda pomaga zapewnić, że raporty zbiorcze będą uzyskać najwyższą możliwą dokładność po zastosowaniu szumu. Mechanizm ten jest bardzo elastyczny i obsługuje wiele strategii agregacji.

W poniższym przykładzie budżet na potrzeby prywatności jest dzielony po równo między campaignCounts i geoValue, dzieląc wkład w wysokości 1 zł między każdą z nich:

// 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 histogramu:

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

Współczynniki skalowania można odwrócić w celu uzyskania prawidłowych wartości, stosowanego szumu modulo:

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

Prywatność różnicowa

Celem tego interfejsu API jest stworzenie platformy obsługującej różnicowo prywatne pomiary zbiorcze. Można to osiągnąć, dodając szum proporcjonalnie do budżetu L1 $, na przykład wybierając szum z tym rozkładem:

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

Integracja interfejsów Protected Audience API i Attribution Reporting API

Integracja interfejsów API w ramach Protected Audience API i Attribution Reporting API umożliwia technologii reklamowych ocenę skuteczności atrybucji w ramach różnych taktyk remarketingowych w celu określenia, które typy odbiorców zapewniają największy zwrot z inwestycji.

Dzięki tej integracji między interfejsami API technologie reklamowe mogą:

  • Utwórz mapę par klucz-wartość identyfikatorów URI, które będą używane na potrzeby 1) raportowania interakcji i 2) rejestracji źródła.
  • Uwzględnij CustomAudience w mapowaniu kluczy 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 zgłaszania tych interakcji za pomocą Protected Audience API będzie też używany do rejestrowania obejrzenia lub kliknięcia jako kwalifikującego się źródła za pomocą interfejsu Attribution Reporting API.
  • Korzystając z tego adresu URL, technologia reklamowa może przekazywać niestandardowe listy odbiorców (lub inne istotne informacje kontekstowe dotyczące reklamy, takie jak miejsce docelowe reklamy czy czas oglądania). Te metadane mogą być przekazywane do raportów podsumowujących podczas sprawdzania zbiorczych danych o skuteczności kampanii.

Więcej informacji o tym, jak włączyć tę funkcję w ramach Protected Audience API, znajdziesz w odpowiedniej sekcji Wyjaśnienia dotyczącego Protected Audience API.

Priorytet rejestracji, atrybucja i przykłady raportowania

Ten przykład pokazuje zbiór interakcji użytkowników oraz sposób, w jaki zdefiniowane przez technologię reklamową źródło atrybucji i priorytety reguły mogą wpłynąć na przypisane raporty. W tym przykładzie zakładamy, że:

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

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

  1. Użytkownik widzi reklamę. AdTech rejestruje źródło atrybucji za pomocą interfejsu API o priorytecie 0 (widok 1).
  2. Użytkownik widzi reklamę zarejestrowaną z priorytetem 0 (widok 2).
  3. Użytkownik klika reklamę o priorytecie 1 (kliknięcie nr 1).
  4. Użytkownik dokonuje konwersji w aplikacji reklamodawcy (dociera do strony docelowej). Technologia reklamowa rejestruje regułę za pomocą interfejsu API o priorytecie 0 (konwersja 1).
    • Po zarejestrowaniu reguł interfejs API przeprowadza atrybucję, zanim wygeneruje raporty.
    • Dostępne są 3 źródła atrybucji: widok 1, widok 2 i kliknięcie nr 1. Interfejs API przypisuje temu aktywatorowi kliknięcie nr 1, ponieważ ma on najwyższy priorytet i najnowszy.
    • Widok 1 i widok 2 zostały odrzucone i nie kwalifikują się już do atrybucji w przyszłości.
  5. Użytkownik dodaje produkt do koszyka w aplikacji reklamodawcy o priorytecie 1 (konwersja 2).
    • Kliknięcie 1 jest jedynym odpowiednim źródłem atrybucji. Interfejs API przypisuje temu aktywatorowi kliknięcie nr 1.
  6. Użytkownik dodaje produkt do koszyka w aplikacji reklamodawcy o priorytecie 1 (konwersja 3).
    • Kliknięcie 1 jest jedynym odpowiednim źródłem atrybucji. Interfejs API przypisuje temu aktywatorowi kliknięcie nr 1.
  7. Użytkownik dodaje produkt do koszyka w aplikacji reklamodawcy o priorytecie 1 (konwersja 4).
    • Kliknięcie 1 jest jedynym odpowiednim źródłem atrybucji. Interfejs API przypisuje temu aktywatorowi kliknięcie nr 1.
  8. Użytkownik dokonuje zakupu w aplikacji reklamodawcy zarejestrowanej z priorytetem 2 (konwersja nr 5).
    • Kliknięcie 1 jest jedynym odpowiednim źródłem atrybucji. Interfejs API przypisuje temu aktywatorowi kliknięcie nr 1.

Raporty na poziomie zdarzenia charakteryzują się tymi cechami:

  • Domyślnie po upływie odpowiednich okresów raportowania wysyłane są 3 pierwsze reguły przypisane do kliknięcia oraz pierwsza reguła przypisana do widoku danych.
  • Jeśli w okresie raportowania istnieją reguły zarejestrowane o wyższym priorytecie, mają one pierwszeństwo i zastępują najnowszą regułę.
  • W poprzednim przykładzie technologia reklamowa otrzymuje 3 raporty o zdarzeniach po 2-dniowym oknie raportowania dla konwersji 2, konwersji 3 i 5.
    • Wszystkie 5 reguł jest przypisanych do kliknięcia 1. Domyślnie interfejs API wysyła raporty dotyczące pierwszych 3 reguł: konwersji 1, konwersji 2 i 3.
    • Jednak priorytet konwersji 4 (1) jest wyższy niż priorytet konwersji 1 (0). Raport o zdarzeniach konwersji 4 zastępuje raport o zdarzeniach konwersji 1.
    • Poza tym priorytet konwersji 5 (2) jest wyższy niż jakakolwiek inna reguła. Raport o zdarzeniach konwersji 5 zastępuje raport o konwersjach 4.

Raporty zbiorcze charakteryzują się tymi cechami:

  • Zaszyfrowane raporty zbiorcze są wysyłane do technologii reklamowej zaraz po ich przetworzeniu, czyli kilka godzin po zarejestrowaniu reguł.

    Jako technologia reklamowa tworzysz ich partie na podstawie informacji z Twoich zbiorczych raportów, które zawierają niezaszyfrowane informacje. Informacje te znajdują się w polu shared_info w raporcie zbiorczym i obejmują sygnaturę czasową oraz źródło raportu. Nie można zbiorczo tworzyć danych na podstawie zaszyfrowanych informacji zawartych w parach klucz-wartość agregacji. Kilka prostych strategii, których możesz użyć, to codzienne lub cotygodniowe raporty zbiorcze. W miarę możliwości partie powinny zawierać co najmniej 100 raportów.

  • To technologia reklam decyduje o tym, kiedy i jak można zbierać zbiorcze raporty i wysyłać je do usługi agregacji.

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

  • W poprzednim przykładzie wysyłanych jest 5 raportów zbiorczych, po 1 dla każdego zarejestrowanego aktywatora.

Raporty debugowania na temat przejścia

Interfejs Attribution Reporting API to nowy i dość złożony sposób przeprowadzania pomiarów atrybucji bez stosowania identyfikatorów w różnych aplikacjach. W związku z tym udostępniamy mechanizm przejściowy umożliwiający uzyskiwanie dodatkowych informacji o raportach atrybucji, gdy identyfikator wyświetlania reklam jest dostępny (użytkownik nie zrezygnował z personalizacji przy użyciu tego identyfikatora, a aplikacja wydawcy lub reklamodawcy zadeklarowała uprawnienia AdID). Dzięki temu interfejs API jest w pełni zrozumiały podczas wdrażania, łatwiej usuwasz wszelkie błędy i łatwiej porównujesz jego skuteczność z alternatywnymi rozwiązaniami opartymi na identyfikatorze wyświetlania reklam. Są 2 rodzaje raportów z debugowania: wysłanie atrybucji i wyczerpujące.

Szczegółowe informacje o debugowaniu raportów za pomocą pomiaru połączeń z aplikacji do witryny i połączenia z witryny do aplikacji znajdziesz w przewodniku po przejściowych raportach debugowania.

Raporty debugowania dotyczące atrybucji

Rejestracje źródeł i reguł akceptują nowe 64-bitowe pole debug_key (sformatowane jako ciąg znaków), które wypełnia technologia reklam. Parametry source_debug_key i trigger_debug_key są przekazywane bez zmian zarówno w raportach na poziomie zdarzenia, jak i w raportach zbiorczych.

Jeśli raport zostanie utworzony zarówno z kluczem debugowania źródła, jak i kluczy debugowania, zduplikowany raport debugowania jest wysyłany z ograniczonym opóźnieniem do punktu końcowego .well-known/attribution-reporting/debug/report-event-attribution. Raporty debugowania są takie same jak zwykłe raporty i zawierają oba pola kluczy debugowania. Uwzględnienie tych kluczy w obu przypadkach umożliwia powiązanie zwykłych raportów z osobnym strumieniem raportów debugowania.

  • W przypadku raportów na poziomie zdarzenia:
    • Zduplikowane raporty debugowania są wysyłane z ograniczonym opóźnieniem i dlatego nie są pomijane przez limity dostępnych reguł, co pozwala technologii reklamowych poznać wpływ tych limitów na raporty na poziomie zdarzenia.
    • Raporty na poziomie zdarzenia powiązane z fałszywymi zdarzeniami aktywującymi nie będą miały parametru trigger_debug_key. Dzięki temu technologie reklamowe mogą lepiej zrozumieć sposób zastosowania szumu w interfejsie API.
  • W przypadku raportów zbiorczych:
    • Będziemy obsługiwać nowe pole debug_cleartext_payload, które zawiera odszyfrowany ładunek, tylko jeśli ustawiono zarówno source_debug_key, jak i trigger_debug_key.

Szczegółowe raporty debugowania

Szczegółowe raporty z debugowania pozwalają programistom monitorować niektóre błędy w źródle atrybucji lub aktywować rejestracje. Raporty debugowania są wysyłane z pewnym opóźnieniem po tym, jak źródło atrybucji lub aktywuje rejestrację wPunkt końcowy: well-known/attribution-reporting/debug/verbose.

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

  • Typ: przyczyna wygenerowania raportu. Zobacz pełną listę typów raportów szczegółowych.
    • Ogólnie rzecz biorąc, istnieją raporty szczegółowe dotyczące źródeł i generowane w przypadku raportów szczegółowych.
    • Szczegółowe raporty dotyczące źródeł wymagają, aby aplikacja wydawcy miała dostęp do identyfikatora wyświetlania reklam, a generowanie szczegółowych raportów wymaga, aby identyfikator wyświetlania reklam był dostępny dla aplikacji reklamodawcy.
    • Raporty szczegółowe (z wyjątkiem trigger-no-matching-source) mogą opcjonalnie zawierać source_debug_key. Można go podać tylko wtedy, gdy aplikacja wydawcy ma też dostęp do identyfikatora wyświetlania reklam.
  • Treść: treść raportu – zależnie od jego typu.

Technologie reklamowe muszą wyrazić zgodę na otrzymywanie szczegółowych raportów z debugowania za pomocą nowego pola słownika debug_reporting w nagłówkach Attribution-Reporting-Register_Source i Attribution-Reporting-Register-Trigger.

  • Raporty o szczegółach źródeł wymagają wyrażenia zgody tylko w nagłówku rejestracji źródła.
  • Raporty debugowania reguł wymagają wyrażenia zgody tylko w nagłówku rejestracji reguły.

Jak korzystać z raportów debugowania

Jeśli miała miejsce konwersja (według dotychczasowego systemu pomiarowego) i otrzymujesz raport debugowania dotyczący tej konwersji, oznacza to, że reguła została zarejestrowana.

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

Brak dopasowań może mieć kilka przyczyn.

Działa zgodnie z oczekiwaniami:

  • Działania interfejsu API chroniące prywatność:
    • Użytkownik osiąga limit częstotliwości wysyłania raportów, przez co wszystkie kolejne raporty nie są wysyłane w wybranym okresie, lub źródło jest usuwane z powodu oczekującego limitu miejsca docelowego.
    • W przypadku raportów na poziomie zdarzenia: raport podlega losowej odpowiedzi (szumu) i jest pomijany. Możesz też otrzymać raport losowy.
    • W przypadku raportów na poziomie zdarzenia osiągnięto limit trzech raportów (kliknięcia) lub jeden (w przypadku obejrzeń), a kolejne raporty nie mają jawnego priorytetu lub są niższe niż w istniejących raportach.
    • Przekroczono limity udziału w raportach zbiorczych.
  • Logika biznesowa zdefiniowana przez technologię reklamową:
    • Reguła jest odfiltrowywana za pomocą filtrów lub reguł priorytetu.
  • opóźnienia lub interakcje z dostępnością sieci (np. wyłączenie urządzenia na dłuższy czas);

Niezamierzone przyczyny:

  • Problemy z implementacją:
    • Nagłówek źródła jest nieprawidłowo skonfigurowany.
    • Nagłówek reguły jest nieprawidłowo skonfigurowany.
    • Inne problemy z konfiguracją.
  • Problemy z urządzeniem lub siecią:
    • Niepowodzenia z powodu warunków sieciowych.
    • Odpowiedź dotycząca rejestracji źródła lub aktywatora nie dociera do klienta.
    • Błąd interfejsu API.

Uwagi na przyszłość i pytania otwarte

Obecnie pracujemy nad interfejsem Attribution Reporting API. Badamy też potencjalne funkcje, takie jak modele atrybucji niezwiązanej z ostatnim kliknięciem czy pomiary na różnych urządzeniach.

Chcielibyśmy też poznać opinie społeczności dotyczące kilku kwestii:

  1. Czy chcesz, aby interfejs API wysyłał raporty dotyczące zweryfikowanej instalacji? Takie raporty zaliczają się do limitów liczby żądań określanych przez platformy technologii reklamowych.
  2. Czy przewidujesz jakieś trudności z przekazywaniem parametru InputEvent z aplikacji do technologii reklamowej w celu rejestracji źródła?
  3. Czy masz jakieś specjalne przypadki użycia atrybucji w przypadku wstępnie załadowanych lub ponownie zainstalowanych aplikacji?