Część 2 z 3 dotycząca debugowania interfejsu Attribution Reporting API. 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.exampleas 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
typefield 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.
Pytania dotyczące implementacji?
Jeśli podczas konfigurowania raportów debugowania wystąpią problemy, zgłoś je w naszym repozytorium pomocy dla deweloperów, a my pomożemy Ci je rozwiązać.
Przygotowanie do skonfigurowania raportów debugowania
Zanim skonfigurujesz raporty debugowania, wykonaj te czynności:
Sprawdź, czy zostały zastosowane sprawdzone metody integracji interfejsu API.
Sprawdź, czy kod jest chroniony przez wykrywanie funkcji. Aby upewnić się, ż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 ten test wykrywania funkcji zwróci wartość „true”, interfejs API jest dozwolony w kontekście (na stronie), w którym jest przeprowadzany.
(Nie jest wymagane w fazie testowania: sprawdź, czy masz ustawioną wartość Permissions-Policy).
Rozwiązywanie podstawowych problemów z integracją
Raporty debugowania są przydatne do wykrywania i analizowania utraty danych na dużą skalę, ale niektóre problemy z integracją można wykryć lokalnie. Problemy z konfiguracją nagłówka źródła i nagłówka wywołującego, problemy z parsowaniem JSON-a, niebezpieczne konteksty (inne niż HTTPS) i inne problemy, które uniemożliwiają działanie interfejsu API, będą wyświetlane na karcie Problemy w Narzędziach deweloperskich.
Problemy z narzędziami deweloperskimi mogą być różnego rodzaju. Jeśli napotkasz invalid headerproblem, skopiuj nagłówek do narzędzia do sprawdzania poprawności nagłówków. Pomoże Ci to zidentyfikować i naprawić pole, które powoduje problem.
Weryfikowanie nagłówków Attribution Reporting
Do sprawdzania nagłówków związanych 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 umieść wartość report-header-errors.
Attribution-Reporting-Info: report-header-errors
Pamiętaj, że Attribution-Reporting-Info to nagłówek o strukturze słownikaAttribution-Reporting-Info, więc podanie klucza logicznego report-header-errors oznacza wartość true.
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 w 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
}
}]
Konfigurowanie raportów debugowania: kroki wspólne dla raportów o sukcesie i raportów szczegółowych
Ustaw ten 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 rejestracji wywołującej. Raport debugowania dotyczący powodzenia zostanie wygenerowany tylko wtedy, gdy plik cookie będzie obecny w obu przypadkach.
Kod demonstracyjny: debug cookie
Pamiętaj, że raporty debugowania można włączyć w przypadku przeglądarek w trybie B, w którym 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 debugowaniu.
Krok 2. Ustaw klucze debugowania
Każdy klucz debugowania musi być 64-bitową liczbą całkowitą bez znaku sformatowaną jako ciąg w systemie dziesiętnym. Każdy klucz debugowania powinien być unikalnym identyfikatorem. Raport debugowania o pomyślnym wyniku zostanie wygenerowany tylko wtedy, gdy ustawione są klucze debugowania.
- Zmapuj klucz debugowania po stronie źródła na dodatkowe informacje o źródle, które Twoim zdaniem są istotne do debugowania.
- Przypisz klucz debugowania po stronie wyzwalacza do dodatkowych informacji o czasie wyzwalania, które Twoim zdaniem są istotne na potrzeby debugowania.
Możesz na przykład ustawić te klucze debugowania:
- Identyfikator pliku cookie + sygnatura czasowa źródła jako klucz debugowania źródła (i zarejestrowanie tej samej sygnatury czasowej w systemie opartym na plikach cookie)
- Identyfikator pliku cookie + sygnatura czasowa wywołania jako klucz debugowania wywołania (i zarejestrowanie tej samej sygnatury czasowej 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: Cookbook.
Klucz debugowania po stronie źródła powinien być inny niż source_event_id, aby można było odróżnić 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: source debug key Kod demonstracyjny: trigger debug key
Konfigurowanie raportów debugowania powodzenia
Przykładowy kod w tej sekcji generuje raporty debugowania o skuteczności zarówno w przypadku raportów na poziomie zdarzenia, jak i raportów z możliwością agregacji. Raporty na poziomie zdarzenia i raporty z możliwością agregacji używają tych samych kluczy debugowania.
Krok 3. Skonfiguruj punkt końcowy do zbierania raportów debugowania o sukcesie
Skonfiguruj punkt końcowy, aby zbierać raporty debugowania. Ten punkt końcowy powinien być podobny do głównego punktu końcowego atrybucji, ale w ścieżce powinien zawierać dodatkowy ciąg znaków debug:
- Punkt końcowy raportów debugowania na poziomie zdarzenia:
https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution- Punkt końcowy dla raportów debugowania z możliwością agregacji:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Punkt końcowy dla raportów debugowania z możliwością agregacji:
Gdy nastąpi 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 pomyślnym wykonaniu może wyglądać tak (w tym przypadku 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);
}
);
Przykładowy kod: punkt końcowy raportów debugowania na poziomie zdarzenia
Kod demonstracyjny: punkt końcowy raportów debugowania z możliwością agregacji
Krok 4. Sprawdź, czy konfiguracja będzie generować raporty debugowania z informacją o sukcesie
- Otwórz
chrome://attribution-internalsw przeglądarce. - Upewnij się, że na kartach Raporty na poziomie zdarzenia i Raporty z możliwością agregacji jest zaznaczone pole wyboru Pokaż raporty debugowania.
- Otwórz witryny, w których masz zaimplementowane interfejsy Attribution Reporting API. Wykonaj czynności, które zwykle wykonujesz, aby generować raporty o atrybucji. Te same czynności pozwolą Ci wygenerować raporty debugowania dotyczące powodzenia.
- W przypadku
chrome://attribution-internals:- Sprawdź, czy raporty o atrybucji są generowane prawidłowo.
- Na kartach Raporty na poziomie zdarzenia i Raporty z możliwością agregacji sprawdź, czy generowane są też raporty debugowania o sukcesie. Rozpoznaj je na liście po niebieskiej ścieżce
debug.
- Sprawdź na serwerze, czy punkt końcowy od razu otrzymuje te raporty debugowania o sukcesie. Sprawdź, czy nie ma raportów debugowania o sukcesie na poziomie zdarzenia i raportów z możliwością agregacji.
Krok 5. Obserwuj raporty debugowania dotyczące sukcesów
Raport debugowania o powodzeniu jest identyczny z raportem atrybucji i zawiera klucze debugowania po stronie źródła i po stronie wywołania.
{
"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 wyzwalacza
Ustaw wartość debug_reporting na true w przypadku Attribution-Reporting-Register-Source 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: source header
Kod wersji demonstracyjnej: trigger header
Krok 4. Skonfiguruj punkt końcowy do zbierania szczegółowych raportów debugowania
Skonfiguruj punkt końcowy, aby zbierać raporty debugowania. Ten punkt końcowy powinien być podobny do głównego punktu końcowego atrybucji, ale w ścieżce powinien zawierać dodatkowy ciąg znaków debug/verbose:
https://adtech.example/.well-known/attribution-reporting/debug/verbose
Gdy generowane są szczegółowe raporty debugowania, czyli gdy źródło lub reguła 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 debugowania może wyglądać tak (w tym przypadku w punkcie końcowym 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 przeciwieństwie do raportów debugowania o pomyślnym zakończeniu w przypadku raportów szczegółowych jest tylko 1 punkt końcowy. Szczegółowe raporty dotyczące raportów na poziomie zdarzenia i raportów zagregowanych będą wysyłane do tego samego punktu końcowego.
Kod demonstracyjny: szczegółowe raporty debugowania endpoint
Krok 5. Sprawdź, czy konfiguracja będzie generować szczegółowe raporty debugowania
Istnieje wiele typów szczegółowych raportów debugowania, ale wystarczy sprawdzić konfigurację szczegółowego debugowania za pomocą tylko jednego typu szczegółowego raportu debugowania. Jeśli ten jeden typ szczegółowego raportu debugowania jest prawidłowo generowany i otrzymywany, oznacza to, że wszystkie typy szczegółowych raportów debugowania będą również prawidłowo generowane i otrzymywane, ponieważ wszystkie szczegółowe raporty debugowania korzystają z tej samej konfiguracji i są wysyłane do tego samego punktu końcowego.
- Otwórz
chrome://attribution-internalsw przeglądarce. - Wywołaj w witrynie atrybucję (konwersję) skonfigurowaną za pomocą funkcji Raportowanie atrybucji. Biorąc pod uwagę, że przed tą konwersją nie doszło do interakcji z reklamą (wyświetlenia ani kliknięcia), możesz się spodziewać wygenerowania szczegółowego raportu debugowania typu
trigger-no-matching-source. - W sekcji
chrome://attribution-internalsotwórz kartę Szczegółowe raporty debugowania i sprawdź, czy wygenerowano szczegółowy raport debugowania typutrigger-no-matching-source. - Na serwerze sprawdź, czy punkt końcowy natychmiast otrzymał ten szczegółowy raport debugowania.
Krok 6. Obserwuj szczegółowe raporty debugowania
Szczegółowe raporty debugowania generowane w momencie wywołania zawierają klucz debugowania po stronie źródła i po stronie wywołania (jeśli istnieje pasujące źródło wywołania). Szczegółowe raporty debugowania generowane w momencie wysyłania źródła zawierają klucz debugowania po stronie źródła.
Przykład żądania zawierającego szczegółowe raporty debugowania wysłanego 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- Przyczyna wygenerowania raportu. Aby dowiedzieć się więcej o wszystkich typach raportów szczegółowych i o tym, jakie działania należy podjąć w zależności od typu raportu, zapoznaj się z informacjami o raportach szczegółowych w części 3: Przewodnik po debugowaniu.
Body- Treść raportu. Zależy to od jego rodzaju. Zapoznaj się z informacjami o raportach szczegółowych w części 3: Debugowanie.
Treść żądania będzie zawierać co najmniej 1 i co najwyżej 2 raporty szczegółowe:
- Jeden szczegółowy raport, jeśli błąd dotyczy tylko raportów na poziomie zdarzenia (lub tylko raportów z możliwością agregacji). Błąd rejestracji źródła lub aktywatora ma tylko 1 przyczynę, dlatego w przypadku każdego błędu i każdego typu raportu (na poziomie zdarzenia lub z możliwością agregacji) można wygenerować 1 szczegółowy raport.
- 2 szczegółowe raporty, jeśli błąd dotyczy zarówno raportów na poziomie zdarzenia, jak i raportów z możliwością agregacji (z wyjątkiem sytuacji, gdy przyczyna błędu jest taka sama w przypadku raportów na poziomie zdarzenia i raportów z możliwością agregacji – wtedy generowany jest tylko 1 szczegółowy raport, np.
trigger-no-matching-source).
Następny
Część 3. Przewodnik po debugowaniu