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 o debugowaniu napotkasz jakiś problem, utwórz problem w naszym repozytorium pomocy 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 dostępny tylko po wykryciu określonej 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 kontrola wykrywania cech zwraca wartość „prawda”, interfejs API jest dozwolony w kontekście (na stronie), w którym przeprowadza się kontrolę.
(Nie jest wymagane w fazie testowania: sprawdź, czy masz ustawioną Permissions-Policy)
Rozwiązywanie podstawowych problemów z integracją
Raporty debugowania są przydatne do wykrywania i analizowania 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 z Narzędziami deweloperskimi mogą mieć różne rodzaje. 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.
Weryfikowanie 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 wyrazić zgodę na otrzymywanie raportów z debugowania, w nagłówku odpowiedzi Attribution-Reporting-Info umieść report-header-errors.
Attribution-Reporting-Info: report-header-errors
Pamiętaj, że Attribution-Reporting-Info to uporządkowany nagłówek słownikaAttribution-Reporting-Info, dlatego podanie klucza report-header-errors oznacza, że ma on wartość rzeczywistą.
Raporty debugowania są natychmiast wysyłane do punktu końcowego raportowania:
https://<reporting origin>/.well-known/attribution-reporting/debug/verbose
Dane z raportu są umieszczane w treści żądania w postaci listy JSON obiektów mających ten formularz:
[{
"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 utworzony 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 konfigurować pliku cookie debugowania, aby włączyć raporty na potrzeby debugowania. Przejdź do kroku 2, aby skonfigurować klucze debugowania na potrzeby raportów o udanych testach.
Krok 2. Ustaw klucze debugowania
Każdy klucz debugowania musi być 64-bitową nieoznaczoną liczbą całkowitą w formacie base-10. Nadaj każdemu kluczowi debugowania unikalny identyfikator. Raport o powodzeniu debugowania zostanie wygenerowany tylko po ustawieniu kluczy 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 działania wyzwalacza, które mogą być przydatne 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 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.
Klucz debugowania po stronie źródła powinien być inny niż source_event_id, co umożliwi rozróżnienie poszczególnych raportów z tym samym identyfikatorem 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łowego Kod demonstracyjny: klucz debugowania aktywatora
Skonfiguruj raporty o udanym debugowaniu
Przykładowy kod w tej sekcji generuje raporty debugowania dotyczące sukcesu zarówno na poziomie zdarzenia, jak i raportów agregowanych. Raporty na poziomie zdarzenia i raporty agregowane używają 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. Powinien on być podobny do głównego punktu końcowego atrybucji, z dodatkowym ciągiem debug w ścieżce:
- Punkt końcowy raportów o powodzeniu debugowania 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:
Po aktywowaniu atrybucji przeglądarka natychmiast wyśle do tego punktu końcowego raport debugowania, używając żądania POST. Kod serwera do obsługi przychodzących raportów debugowania może wyglądać tak (tutaj 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 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-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 usłudze
chrome://attribution-internals:- Sprawdź, czy raporty atrybucji są generowane prawidłowo.
- Na karcie Raporty na poziomie zdarzenia i Raporty podlegające agregacji sprawdź, czy generowane są też raporty debugowania dotyczące sukcesu. Rozpoznaj je na liście za pomocą niebieskiej ścieżki
debug.
- Na serwerze sprawdź, czy punkt końcowy natychmiast otrzymuje te raporty debugowania. Sprawdzaj, czy są dostępne raporty debugowania na poziomie zdarzenia i możliwe do agregacji.
Krok 5. Obserwuj raporty debugowania
Raport debugowania skuteczności jest identyczny z raportami atrybucji i zawiera zarówno klucze debugowania po stronie źródła, jak 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 aktywatora
Ustaw debug_reporting na true w parametrach 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: nagłówek źródła
Kod demonstracyjny: nagłówek wyzwalacza
Krok 4. Skonfiguruj punkt końcowy, aby zbierać szczegółowe raporty na temat debugowania
Skonfiguruj punkt końcowy do zbierania raportów debugowania. Ten punkt końcowy powinien być podobny do głównego punktu końcowego atrybucji, z dodatkowym ciągiem debug/verbose w ś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 debugowania może wyglądać tak (tutaj 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 o udanym debugowaniu mamy tylko 1 punkt końcowy na potrzeby raportów szczegółowych. 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 spowoduje wygenerowanie szczegółowych raportów debugowania
Chociaż istnieje wiele typów szczegółowych raportów o debugowaniu, wystarczy, że sprawdzisz swoją szczegółową konfigurację debugowania tylko z jednym typem takiego raportu. 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 raportowaniem atrybucji. Ponieważ przed tą konwersją nie było żadnego zaangażowania reklamy (wyświetlenia ani kliknięcia), spodziewaj się wygenerowania obszernego raportu debugowania typu
trigger-no-matching-source. - W
chrome://attribution-internalsotwórz kartę Szczegółowe raporty debugowania i sprawdź, czy wygenerowano szczegółowy raport debugowania typutrigger-no-matching-source. - Sprawdź na serwerze, czy punkt końcowy od razu otrzymał ten wyczerpujący raport debugowania.
Krok 6. Przeanalizuj szczegółowe raporty debugowania
Szczegółowe raporty 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 generowane w czasie źródłowym 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 ich rodzaju, 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 a maksymalnie 2 raporty szczegółowe:
- jeden raport szczegółowy, jeśli błąd dotyczy tylko raportów na poziomie zdarzenia (lub jeśli dotyczy tylko raportów agregowanych). 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 agregowanych – z jednym wyjątkiem: jeśli przyczyna błędu jest taka sama w przypadku raportów na poziomie zdarzenia i raportów agregowanych, generowany jest tylko 1 raport szczegółowy (np.
trigger-no-matching-source).