Konfigurowanie raportów debugowania w przypadku Attribution Reporting

Część 2 z 3 dotycząca debugowania raportowania atrybucji. Skonfiguruj raporty debugowania.

Słowniczek

  • The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
  • An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
  • A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
  • A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
  • Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
  • Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
  • Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

Masz pytania dotyczące implementacji?

Jeśli podczas konfigurowania raportów debugowania napotkasz jakikolwiek problem, utwórz zgłoszenie w naszym repozytorium dla deweloperów, a my pomożemy Ci go rozwiązać.

Przygotowanie do konfigurowania raportów debugowania

Zanim skonfigurujesz raporty debugowania, wykonaj te czynności:

Sprawdź, czy zastosowałeś/aś sprawdzone metody integracji interfejsu API.

  • Sprawdź, czy kod jest zabezpieczony przed wykryciem funkcji. Aby mieć pewność, że interfejs API nie jest blokowany przez Permissions-Policy, uruchom ten kod:

    if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}

    Jeśli ta funkcja wykrywania zwróci wartość true, interfejs API jest dozwolony w kontekście (stronie), w którym przeprowadzany jest test.

  • (Nie jest wymagane w fazie testowania: sprawdź, czy masz ustawione Permissions-Policy).

Rozwiązywanie podstawowych problemów z integracją

Chociaż raporty debugowania są przydatne do wykrywania i analizowania strat na dużą skalę, niektóre problemy z integracją można wykryć lokalnie. Problemy z nieprawidłową konfiguracją nagłówka źródła i wyzwalacza, problemy z analizowaniem danych JSON, niepewny kontekst (nie-HTTPS) i inne problemy, które uniemożliwiają działanie interfejsu API, będą widoczne na karcie Problemy w DevTools.

Problemy w DevTools mogą być różnego typu. Jeśli wystąpi problem z invalid header, skopiuj nagłówek do narzędzia do sprawdzania nagłówków. Pomoże Ci to zidentyfikować i naprawić pole, które powoduje problem.

Sprawdzanie nagłówków raportowania atrybucji

Aby sprawdzić nagłówki związane z interfejsem Attribution Reporting API, możesz użyć walidatora nagłówków. Aby ułatwić debugowanie interfejsu API, możesz monitorować błędy weryfikacji pochodzące z przeglądarki.

Aby włączyć otrzymywanie raportów debugowania, w nagłówku odpowiedzi Attribution-Reporting-Info podaj wartość report-header-errors.

Attribution-Reporting-Info: report-header-errors

Pamiętaj, że Attribution-Reporting-Info to nagłówek uporządkowany w formie słownikaAttribution-Reporting-Info, więc podanie klucza logicznego report-header-errors oznacza wartość true (prawda).

Raporty debugowania są natychmiast wysyłane do punktu końcowego raportowania:

https://<reporting origin>/.well-known/attribution-reporting/debug/verbose

Dane raportu są zawarte w treści żądania jako lista obiektów JSON o tym formacie:

[{
  "type": "header-parsing-error",
  "body": {
    "context_site": "https://source.example",
    "header": "Attribution-Reporting-Register-Source",
    "value": "!!!", // header value received in the response
    "error": "invalid JSON" // optional error details that may vary across browsers or different versions of the same browser
  }
}]
Zrzut ekranu pokazujący narzędzie do sprawdzania nagłówków

Konfigurowanie raportów debugowania: czynności wspólne dla raportów sukcesu i raportów szczegółowych

Ustaw następujący plik cookie w źródle raportowania:

Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly

Przeglądarka sprawdzi obecność tego pliku cookie zarówno w źródle, jak i w przypadku rejestracji wyzwalacza. Raport debugowania powodzenia zostanie wygenerowany tylko wtedy, gdy plik cookie jest obecny w obu przypadkach.

Kod demonstracyjny: plik cookie debugowania

Pamiętaj, że raporty debugowania można włączyć w przeglądarkach w trybie B, w których pliki cookie innych firm są wyłączone, aby ułatwić testowanie i przygotowanie do wycofania plików cookie innych firm. W przypadku przeglądarek w trybie B nie musisz ustawiać pliku cookie debugowania, aby włączyć raporty debugowania. Przejdź do kroku 2, aby skonfigurować klucze debugowania na potrzeby raportów o udanym debugowaniu.

Krok 2. Skonfiguruj klucze debugowania

Każdy klucz debugowania musi być 64-bitową liczbą całkowitą bez znaku sformatowaną jako ciąg tekstowy w systemie dziesiętnym. Każdy klucz debugowania powinien mieć unikalny identyfikator. Raport debugowania sukcesu zostanie wygenerowany tylko wtedy, gdy ustawione są klucze debugowania.

  • Przypisz klucz debugowania po stronie źródła do dodatkowych informacji źródłowych, które według Ciebie są przydatne do debugowania.
  • Przypisz klucz debugowania po stronie wyzwalacza do dodatkowych informacji o czasie wyzwalania, które mogą być przydatne do debugowania.

Możesz na przykład ustawić te klucze debugowania:

  • identyfikator pliku cookie + sygnatura czasowa źródła jako klucz debugowania źródła (oraz rejestrowanie tej samej sygnatury czasowej w systemie opartym na plikach cookie);
  • Identyfikator pliku cookie + sygnatura czasu wywołania jako klucz debugowania wywołania (i zapisywanie tej samej sygnatury czasu w systemie opartym na plikach cookie)

Dzięki temu możesz używać informacji o konwersjach opartych na plikach cookie do wyszukiwania odpowiednich raportów debugowania lub raportów atrybucji. Więcej informacji znajdziesz w części 3: Książka kucharska.

Ustaw klucz debugowania po stronie źródła na inny niż source_event_id, aby można było rozróżniać poszczególne raporty, które mają ten sam identyfikator zdarzenia źródłowego.

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}

Kod demonstracyjny: klucz debugowania źródła Kod demonstracyjny: klucz debugowania wyzwalacza

Konfigurowanie raportów debugowania o powodzeniu

Przykładowy kod w tej sekcji generuje raporty debugowania sukcesu zarówno w przypadku raportów na poziomie zdarzenia, jak i raportów możliwych do zsumowania. Raporty na poziomie zdarzenia i zbiorcze korzystają z tych samych kluczy debugowania.

Krok 3. Skonfiguruj punkt końcowy do zbierania raportów debugowania o skutecznych działaniach

Skonfiguruj punkt końcowy do zbierania raportów debugowania. Ten punkt końcowy powinien być podobny do głównego punktu końcowego atrybucji, ale z dodatkowym ciągiem znaków debug w ścieżce:

  • Punkt końcowy raportów debugowania powodzenia na poziomie zdarzenia: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
    • Punkt końcowy dla zbiorczych raportów debugowania o udanych działaniach: https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

Gdy zostanie wywołane atrybucja, przeglądarka natychmiast wyśle raport debugowania za pomocą żądania POST do tego punktu końcowego. Kod serwera do obsługi przychodzących raportów debugowania o sukcesie może wyglądać tak (tutaj na punkcie końcowym węzła):

// Handle incoming event-Level Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-event-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

// Handle incoming aggregatable Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-aggregate-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

Kod demonstracyjny: punkt końcowy raportów debugowania na poziomie zdarzenia

Kod demonstracyjny: punkt końcowy raportów debugowania umożliwiających agregację

Krok 4. Sprawdź, czy Twoja konfiguracja będzie generować raporty debugowania z dodatkiem informacji o skuteczności

  • Otwórz chrome://attribution-internals w przeglądarce.
  • Upewnij się, że na kartach Raporty na poziomie zdarzenia i Raporty agregowane jest zaznaczone pole wyboru Pokaż raporty debugowania.
  • Otwórz witryny, w których zaimplementowano raportowanie atrybucji. Wykonaj czynności służące do generowania raportów atrybucji. Te same czynności posłużą do wygenerowania raportów debugowania skuteczności.
  • W chrome://attribution-internals:
    • Sprawdź, czy raporty atrybucji są prawidłowo generowane.
    • Na karcie Raporty na poziomie zdarzenia i Raporty podlegające agregacji sprawdź, czy generowane są też raporty debugowania dotyczące sukcesu. Możesz je rozpoznać po niebieskim debug na liście.
Zrzut ekranu: wewnętrzne działanie atrybucji
  • Na serwerze sprawdź, czy punkt końcowy natychmiast otrzymuje te raporty debugowania. Sprawdź raporty debugowania sukcesu na poziomie zdarzenia i zbiorcze.
Zrzut ekranu: dzienniki serwera źródłowego raportowania

Krok 5. Sprawdź raporty debugowania dotyczące sukcesu

Raport debugowania skuteczności jest identyczny z raportami atrybucji i zawiera klucze debugowania po stronie źródła i po stronie reguły.

{
  "attribution_destination": "https://advertiser.example",
  "randomized_trigger_rate": 0.0000025,
  "report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
  "source_debug_key": "647775351539539",
  "source_event_id": "760938763735530",
  "source_type": "event",
  "trigger_data": "0",
  "trigger_debug_key": "156477391437535"
}


{
  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
      "payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
    }
  ],
  "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
  "source_debug_key": "647775351539539",
  "trigger_debug_key": "156477391437535"
}

Konfigurowanie szczegółowych raportów debugowania

Krok 3. Włącz szczegółowe debugowanie w nagłówkach źródła i reguły

Ustaw wartość debug_reporting na true w przypadku zarówno Attribution-Reporting-Register-Source, jak i Attribution-Reporting-Register-Trigger.

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Kod demonstracyjny: nagłówek źródła

Kod demonstracyjny: nagłówek wyzwalacza

Krok 4. Skonfiguruj punkt końcowy do zbierania obszernych raportów debugowania

Skonfiguruj punkt końcowy do zbierania raportów debugowania. Ten punkt końcowy powinien być podobny do głównego punktu końcowego atrybucji, ale zawierać dodatkowy ciąg znaków debug/verbose na ścieżce:

https://adtech.example/.well-known/attribution-reporting/debug/verbose

Gdy generowane są szczegółowe raporty debugowania, czyli gdy źródło lub wyzwalacz nie są zarejestrowane, przeglądarka natychmiast wysyła szczegółowy raport debugowania za pomocą żądania POST do tego punktu końcowego. Kod serwera do obsługi przychodzących szczegółowych raportów z debugowania może wyglądać tak (tutaj w przypadku punktu końcowego węzła):

// Handle incoming verbose debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/verbose',
  async (req, res) => {
    // List of verbose debug reports is in req.body
    res.sendStatus(200);
  }
);

W odróżnieniu od raportów debugowania z uwzględnieniem sukcesu raporty szczegółowe mają tylko 1 punkt końcowy. Szczegółowe raporty dotyczące zdarzeń i raporty zagregowane będą wysyłane do tego samego punktu końcowego.

Kod demonstracyjny: punkt końcowy szczegółowych raportów debugowania

Krok 5. Sprawdź, czy konfiguracja będzie generować szczegółowe raporty z debugowania

Chociaż istnieje wiele typów szczegółowych raportów debugowania, wystarczy sprawdzić konfigurację szczegółowego debugowania za pomocą tylko jednego typu szczegółowego raportu debugowania. Jeśli ten jeden typ obszernego raportu debugowania jest prawidłowo generowany i odbierany, oznacza to, że wszystkie typy obszernych raportów debugowania będą również prawidłowo generowane i odbierane, ponieważ wszystkie obszerne raporty debugowania korzystają z tej samej konfiguracji i są wysyłane do tego samego punktu końcowego.

  1. Otwórz chrome://attribution-internals w przeglądarce.
  2. Wywołaj atrybucję (konwersję) w witrynie skonfigurowanej z raportowaniem atrybucji. Ponieważ przed tą konwersją nie było żadnego zaangażowania reklamy (wyświetlenia ani kliknięcia), spodziewaj się obszernego raportu debugowania typu trigger-no-matching-source.
  3. W chrome://attribution-internals otwórz kartę Szczegółowe raporty debugowania i sprawdź, czy został wygenerowany szczegółowy raport debugowania typu trigger-no-matching-source.
  4. Na serwerze sprawdź, czy punkt końcowy natychmiast otrzymał ten obszerny raport debugowania.

Krok 6. Sprawdź szczegółowe raporty z debugowania

Szczegółowe raporty z debugowania generowane w momencie uruchomienia zawierają klucz debugowania po stronie źródła i klucz debugowania po stronie reguły (jeśli istnieje odpowiednie źródło reguły). Szczegółowe raporty debugowania wygenerowane w źródle zawierają klucz debugowania po stronie źródła.

Przykład żądania zawierającego szczegółowe raporty debugowania wysłane przez przeglądarkę:

[
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "randomized_trigger_rate": 0.0000025,
      "report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_type": "event",
      "trigger_data": "1",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-event-low-priority"
  },
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "limit": "65536",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_site": "http://arapi-publisher.localhost",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-aggregate-insufficient-budget"
  }
]

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

Type
Informacja o przyczynie wygenerowania raportu. Aby dowiedzieć się więcej o wszystkich rozbudowanych typach raportów i o tym, jakie działania należy podjąć w zależności od ich rodzaju, zapoznaj się z informacjami o tych raportach w artykule Część 3. Przewodnik po debugowaniu.
Body
Treść zgłoszenia. To zależy od typu. Zapoznaj się z pełnymi raportami w sekcji Część 3. Przewodnik po debugowaniu.

Treść prośby będzie zawierać co najmniej 1 a maksymalnie 2 raporty szczegółowe:

  • Jeden obszerny raport, jeśli błąd dotyczy tylko raportów na poziomie zdarzenia (lub tylko raportów możliwych do zsumowania). Niepowodzenie rejestracji źródła lub reguły aktywującej ma tylko jedną przyczynę, dlatego na każde takie niepowodzenie i każdy typ raportu (na poziomie zdarzenia lub agregowalny) można wygenerować jeden obszerny raport.
  • 2 raporty szczegółowe, jeśli błąd dotyczy zarówno raportów na poziomie zdarzenia, jak i raportów możliwych do zgrupowania – z jednym wyjątkiem: jeśli przyczyna błędu jest taka sama w przypadku raportów na poziomie zdarzenia i raportów możliwych do zgrupowania, generowany jest tylko 1 raport szczegółowy (np. trigger-no-matching-source).

Następny

Część 3. Przewodnik po debugowaniu