Część 2 z 3 dotycząca debugowania interfejsu Attribution Reporting API. 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.
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