Część 2 z 3 dotycząca debugowania raportowania atrybucji. Skonfiguruj raporty debugowania.
Słowniczek
- Źródło raportowania to źródło, które ustawia źródło i aktywator funkcji Attribution Reporting.
Wszystkie raporty generowane przez przeglądarkę są wysyłane do tego źródła. W tych wskazówkach jako przykładowego źródła zgłoszenia używamy
https://adtech.example. - Raport atrybucji (w skrócie raport) to raport końcowy (na poziomie zdarzenia lub agregowany) zawierający żądane dane pomiarowe.
- Raport debugowania zawiera dodatkowe dane o raporcie atrybucji albo o źródle lub zdarzeniu reguły. Otrzymanie raportu na temat debugowania nie musi oznaczać, że coś działa nieprawidłowo. Istnieją 2 typy raportów debugowania.
- Przejściowy raport debugowania to raport debugowania, który wymaga skonfigurowania pliku cookie w celu wygenerowania i wysłania. Jeśli plik cookie nie zostanie skonfigurowany i po wycofaniu plików cookie innych firm, raporty dotyczące debugowania przejściowych będą niedostępne. Wszystkie raporty na temat debugowania opisane w tym przewodniku to raporty na temat debugowania.
- Raporty na temat pomyślnego debugowania pozwalają śledzić udane wygenerowanie raportu atrybucji. Mają bezpośredni związek z raportem atrybucji. Raporty o udanym debugowaniu są dostępne od wersji Chrome 101 (kwiecień 2022 r.).
- Szczegółowe raporty debugowania pozwalają śledzić brakujące raporty i ustalać, dlaczego ich brakuje. Wskazują przypadki, w których przeglądarka nie zarejestrowała zdarzenia źródła ani nie wywołała tego zdarzenia (co oznacza, że nie generuje raportu atrybucji), oraz przypadki, gdy z jakiegoś powodu nie można wygenerować lub wysłać raportu atrybucji.
Szczegółowe raporty debugowania zawierają pole
type, które podaje powód, dla którego zdarzenie źródłowe, zdarzenie reguły lub raport atrybucji nie zostały wygenerowane. Szczegółowe raporty dotyczące debugowania są dostępne w Chrome od wersji 109 (stabilnej wersji od stycznia 2023 r.). - Klucze debugowania to unikalne identyfikatory, które możesz ustawić zarówno po stronie źródła, jak i po stronie reguły. Klucze debugowania umożliwiają mapowanie konwersji opartych na plikach cookie i atrybucji. Gdy skonfigurujesz system do generowania raportów debugowania i ustawiania kluczy debugowania, przeglądarka będzie uwzględniać te klucze debugowania we wszystkich raportach atrybucji i raportach debugowania.
Więcej pojęć i kluczowych terminów używanych w naszej dokumentacji znajdziesz w słowniczku Piaskownicy prywatności.
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 za pomocą funkcji wykrywania. 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 (na stronie), w którym wykonywane jest sprawdzanie.
(Nie jest wymagane w fazie testowania: sprawdź, czy masz ustawione Permissions-Policy).
Rozwiązywanie podstawowych problemów z integracją
Raporty debugowania mogą Ci pomóc w wykrywaniu i analizowaniu strat na dużą skalę, ale 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.
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
}
}]
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 sukcesu 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 musi mieć unikalny identyfikator. Raport debugowania powodzenia 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 podczas debugowania.
- Przypisz klucz debugowania po stronie wyzwalacza do dodatkowych informacji o czasie wyzwalania, które według Ciebie są 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 (i zapisywanie 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 jako 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 dotyczących skuteczności
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 udanych próbach
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 wynikach:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Punkt końcowy dla zbiorczych raportów debugowania o udanych wynikach:
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 z debugowania z możliwością agregacji
Krok 4. Sprawdź, czy Twoja konfiguracja będzie generować raporty debugowania z dodatkiem informacji o skuteczności
- Otwórz
chrome://attribution-internalsw 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
debugna liście.
- Na serwerze sprawdź, czy punkt końcowy natychmiast otrzymuje te raporty debugowania. Sprawdź raporty debugowania dotyczące zarówno sukcesu na poziomie zdarzenia, jak i możliwości agregacji.
Krok 5. Sprawdź raporty debugowania dotyczące sukcesu
Raport debugowania skuteczności 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 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
Przykładowy kod: nagłówek wyzwalacza
Krok 4. Skonfiguruj punkt końcowy do zbierania szczegółowych 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 błędami może wyglądać tak (tutaj w węźle punktu końcowego):
// 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 raportów na poziomie zdarzenia i zagregowanych będą wysyłane do tego samego punktu końcowego.
Kod demonstracyjny: punkt końcowy szczegółowych raportów z 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.
- Otwórz
chrome://attribution-internalsw przeglądarce. - Wywołaj atrybucję (konwersję) w witrynie skonfigurowanej z użyciem raportowania 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. - W
chrome://attribution-internalsotwórz kartę Szczegółowe raporty debugowania i sprawdź, czy został wygenerowany szczegółowy raport debugowania typutrigger-no-matching-source. - 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- Co spowodowało wygenerowanie 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 każdego z nich, zapoznaj się z informacjami o tych raportach w artykule Część 3. Przewodnik po debugowaniu.
Body- Treść raportu. 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 i 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 zsumowania – 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 zsumowania, generowany jest tylko 1 raport szczegółowy (np.
trigger-no-matching-source).