Część 2 z 3 poświęcona debugowaniu raportów atrybucji. Skonfiguruj raporty debugowania.
Glosariusz
- Źródło raportowania to źródło, które [ustawia nagłówki źródła i regułę raportowania atrybucji.
Wszystkie raporty generowane przez przeglądarkę są wysyłane do tego źródła. W tym przewodniku jako przykładowego źródła raportowania używamy
https://adtech.example. - Raport atrybucji (w skrócie raport) to raport końcowy (na poziomie zdarzenia lub z możliwością zagregowania), który zawiera żądane dane pomiarowe.
- Raport debugowania zawiera dodatkowe dane o raporcie atrybucji albo o źródle lub zdarzeniu reguły. Otrzymanie raportu debugowania nie musi oznaczać, że coś działa nieprawidłowo. Są 2 typy raportów debugowania.
- Przejściowy raport debugowania to raport debugowania, który do wygenerowania i przesłania pliku cookie wymaga ustawienia pliku cookie. Przejściowe raporty debugowania będą niedostępne, jeśli nie ustawisz pliku cookie lub gdy pliki cookie innych firm zostaną wycofane z użytku. Wszystkie raporty debugowania opisane w tym przewodniku to przejściowe raporty debugowania.
- Raporty debugowania powodzenia zawierają informacje o udanych wygenerowaniu raportu atrybucji. Są one bezpośrednio związane z raportem atrybucji. Raporty debugowania sukcesu są dostępne od wersji Chrome 101 (kwiecień 2022 r.).
- Wyczerpujące raporty debugowania pozwalają śledzić brakujące raporty i pomagać w określeniu przyczyn ich braku. Odsyłają one też sytuacje, w których przeglądarka nie zarejestrowała źródła ani zdarzenia aktywującego (co oznacza, że nie wygeneruje raportu atrybucji), oraz sytuacje, w których z jakiegoś powodu nie można wygenerować lub wysłać raportu atrybucji.
Pełne raporty debugowania zawierają pole
type, które podaje przyczynę, dla której nie wygenerowano zdarzenia źródłowego, zdarzenia reguły lub raportu atrybucji. Pełne raporty debugowania są dostępne od wersji Chrome 109 (wersja stabilna w styczniu 2023 r.). - Klucze debugowania to unikalne identyfikatory, które można ustawić zarówno po stronie źródła, jak i po stronie wyzwalacza. Klucze debugowania umożliwiają mapowanie konwersji opartych na plikach cookie i atrybucji. Gdy skonfigurujesz w systemie generowanie raportów debugowania i ustawisz klucze 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 wdrożenia?
Jeśli podczas konfigurowania raportów debugowania napotkasz jakiś problem, utwórz go w naszym repozytorium pomocy dla programistów, a my pomożemy Ci w jego rozwiązaniu.
Przygotowanie do konfigurowania raportów debugowania
Zanim skonfigurujesz raporty debugowania, wykonaj te czynności:
Sprawdź, czy zostały zastosowane sprawdzone metody integracji interfejsu API.
Upewnij się, że Twój kod nie jest objęty wykrywaniem funkcji. Aby upewnić się, że interfejs API nie jest blokowany przez zasadę Permissions-Policy, uruchom ten kod:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }Jeśli to sprawdzanie wykrywania cech zwraca wartość „prawda”, interfejs API jest dozwolony w kontekście (stronie), na którym przeprowadzane jest sprawdzanie.
(W fazie testowania nie jest to wymagane: sprawdź, czy jest ustawiona zasada Permissions-Policy).
Rozwiązywanie podstawowych problemów z integracją
Raporty debugowania są pomocne w wykrywaniu i analizowaniu strat na dużą skalę, ale niektóre problemy z integracją mogą być wykrywane lokalnie. Problemy z błędną konfiguracją źródła i aktywatora, problemy z analizą JSON, niezabezpieczony kontekst (inny niż HTTPS) oraz inne problemy, które uniemożliwiają działanie interfejsu API, będą wymienione na karcie Problemy w Narzędziach deweloperskich.
Problemy z Narzędziami deweloperskimi mogą być różnego rodzaju. Jeśli napotkasz problem z invalid header, skopiuj nagłówek do narzędzia do weryfikacji nagłówków. Pomoże Ci to zidentyfikować i naprawić pole, które powoduje problem.
Konfigurowanie raportów debugowania: czynności typowe dla raportów o powodzeniu i szczegółowych raportów
W źródle raportowania ustaw ten plik cookie:
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
Przeglądarka sprawdzi, czy ten plik cookie znajduje się zarówno w rejestracji źródłowej, jak i przy użyciu reguły. Raport z debugowania błędów jest generowany tylko wtedy, gdy plik cookie występuje 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órym wyłączone są pliki cookie innych firm, aby ułatwić testowanie i przygotowanie do wycofania plików cookie innych firm. W przypadku przeglądarek w Trybie B raporty debugowania nie wymagają tworzenia pliku cookie debugowania. Jeśli chcesz skonfigurować klucze debugowania raportów debugowania powodzenia, przejdź od razu do kroku 2.
Krok 2. Ustaw klucze debugowania
Każdy klucz debugowania musi być 64-bitową niepodpisaną liczbą całkowitą sformatowaną pod postacią ciągu znaków w formacie base-10. Ustaw każdy klucz debugowania jako unikalny identyfikator. Raport z debugowania zakończonego sukcesem jest generowany tylko po ustawieniu kluczy debugowania.
- Zmapuj klucz debugowania po stronie źródła na dodatkowe informacje o czasie źródła, które Twoim zdaniem mogą być przydatne do debugowania.
- Zmapuj klucz debugowania po stronie aktywatora na dodatkowe informacje o czasie aktywatora, które Twoim zdaniem 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 czasowa aktywatora jako klucz debugowania reguły (i rejestrowanie tej samej sygnatury czasowej w systemie opartym na plikach cookie)
Dzięki temu możesz używać informacji o konwersjach na podstawie plików cookie do wyszukiwania odpowiednich raportów debugowania lub atrybucji. Więcej informacji znajdziesz w części 3. Książka kucharska.
Różnicuj klucz debugowania po stronie źródła od klucza source_event_id. Pozwoli Ci to 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: źródłowy klucz debugowania Kod demonstracyjny: klucz debugowania aktywatora
Konfigurowanie raportów debugowania powodzenia
Przykładowy kod w tej sekcji generuje raporty debugowania powodzenia zarówno na poziomie zdarzenia, jak i raportów zbiorczych. Raporty na poziomie zdarzenia i raporty agregujące używają tych samych kluczy debugowania.
Krok 3. Skonfiguruj punkt końcowy, aby zbierać raporty debugowania powodzenia
Skonfiguruj punkt końcowy, aby zbierać raporty debugowania. Ten punkt końcowy powinien być podobny do głównego punktu końcowego atrybucji, ale mieć w ścieżce dodatkowy ciąg znaków debug:
- Punkt końcowy dla 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 powodzenia:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Punkt końcowy dla zbiorczych raportów debugowania powodzenia:
Po aktywowaniu atrybucji przeglądarka natychmiast wysyła raport debugowania za pomocą żądania POST do tego punktu końcowego. Kod serwera do obsługi przychodzących raportów debugowania powodzenia może wyglądać tak (w tym miejscu w 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 z raportów debugowania możliwy do zagregowania
Krok 4. Sprawdź, czy konfiguracja spowoduje wygenerowanie raportów debugowania powodzenia
- Otwórz
chrome://attribution-internalsw przeglądarce. - Upewnij się, że pole wyboru Pokaż raporty debugowania jest zaznaczone zarówno na karcie Raporty na poziomie zdarzenia, jak i na karcie Raporty agregowane.
- Otwórz witryny, w których masz zaimplementowane raportowanie atrybucji. Wykonaj czynności używane do generowania raportów atrybucji. Te same czynności pozwolą Ci wygenerować raporty debugowania sukcesu.
- W
chrome://attribution-internals:- Sprawdź, czy raporty atrybucji zostały prawidłowo wygenerowane.
- Na kartach Raporty na poziomie zdarzenia i Raporty zbiorcze sprawdź, czy raporty debugowania zakończone powodzeniem. Rozpoznaj je na liście dzięki niebieskiej ścieżce
debug.
- Na serwerze sprawdź, czy punkt końcowy natychmiast otrzymuje te raporty debugowania o powodzeniu. Koniecznie sprawdź raporty debugowania na poziomie zdarzenia i zbiorcze.
Krok 5. Przeanalizuj raporty debugowania powodzenia
Jest on taki sam jak raport atrybucji i zawiera klucze debugowania po stronie źródła oraz 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 aktywatora
Ustaw debug_reporting na true zarówno w Attribution-Reporting-Register-Source, jak i w 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łowy
Kod demonstracyjny: nagłówek aktywatora
Krok 4. Skonfiguruj punkt końcowy, aby zbierać szczegółowe raporty debugowania
Skonfiguruj punkt końcowy, aby zbierać raporty debugowania. Ten punkt końcowy powinien być podobny do głównego punktu końcowego atrybucji i mieć w ścieżce 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 aktywator 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 miejscu 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 szczegółowych na temat błędów w raportach możliwych jest tylko 1 punkt końcowy. Szczegółowe raporty powiązane z raportami na poziomie zdarzenia i raportami zbiorczymi będą wysyłane do tego samego punktu końcowego.
Kod demonstracyjny: punkt końcowy w szczegółowych raportach debugowania
Krok 5. Potwierdź, że konfiguracja spowoduje wygenerowanie szczegółowych raportów debugowania
Chociaż istnieje wiele rodzajów szczegółowych raportów debugowania, wystarczy, że przejrzysz konfigurację szczegółowego debugowania tylko przy użyciu jednego typu szczegółowego raportu debugowania. Prawidłowo generowany i odbierany ten jeden typ szczegółowego raportu debugowania oznacza, że wszystkie typy szczegółowych raportów debugowania również będą generowane i odbierane prawidłowo, 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. - aktywuj w swojej witrynie atrybucję (konwersję) skonfigurowaną za pomocą raportowania atrybucji. Ponieważ przed tą konwersją nie było żadnego zaangażowania w reklamę (wyświetlenia lub kliknięcia), zostanie wygenerowany szczegółowy raport debugowania typu
trigger-no-matching-source. - W usłudze
chrome://attribution-internalsotwórz kartę Wyczerpujące 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 szczegółowy raport debugowania.
Krok 6. Obserwuj szczegółowe raporty debugowania
Szczegółowe raporty debugowania wygenerowane w momencie aktywowania aktywatora obejmują klucz debugowania po stronie źródła i po stronie aktywatora (jeśli występuje dopasowanie źródła dla danej reguły). Szczegółowe raporty debugowania wygenerowane w czasie źródła zawierają klucz debugowania po stronie źródła.
Przykład żądania zawierającego szczegółowe raporty o debugowaniu 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 raport szczegółowy zawiera te pola:
Type- Co spowodowało wygenerowanie raportu. Informacje o wszystkich typach raportów szczegółowych i o działaniach podejmowanych w przypadku poszczególnych z nich znajdziesz w sekcji dotyczącej raportów szczegółowych w części 3. Debugowanie.
Body- Treść raportu. Zależy to od jego typu. Zapoznaj się ze szczegółowym opisem raportów w części 3. Debugowanie książki kucharskiej.
Treść żądania będzie zawierać od 1 do 2 szczegółowych raportów:
- 1 szczegółowy raport, jeśli błąd dotyczy tylko raportów na poziomie zdarzenia (lub tylko raportów zbiorczych). Niepowodzenie rejestracji źródła lub aktywatora może mieć tylko jedną przyczynę. Dlatego dla każdego błędu i jego typu (zbiorczy lub na poziomie zdarzenia) może zostać wygenerowany jeden szczegółowy raport.
- 2 szczegółowe raporty, jeśli błąd dotyczy zarówno raportów na poziomie zdarzenia, jak i raportów zbiorczych. Wyjątkiem: jeśli przyczyna błędu jest taka sama w raportach na poziomie zdarzenia i raportach zbiorczych, generowany jest tylko jeden szczegółowy raport (np.
trigger-no-matching-source)