Zarejestruj źródła atrybucji

Dowiedz się, jak rejestrować źródła, aby przypisywać kliknięcia i wyświetlenia do odpowiednich zdarzeń.

Źródło atrybucji to zdarzenie związane z reklamą (kliknięcie lub wyświetlenie), do którego technologia reklamowa może dołączyć te rodzaje informacji:

• Dane raportowania kontekstowego, takie jak identyfikator kreacji reklamy, informacje o kampanii lub regionie.
• Miejsce docelowe konwersji, czyli witryna, w której użytkownik ma dokonać konwersji.

Wykonując czynności opisane w tym dokumencie, możesz zarejestrować źródła wyświetleń reklam lub kliknięć, do których przeglądarka przypisuje konwersje.

Metody rejestracji

Aby zarejestrować źródła atrybucji, użyj elementów HTML lub wywołań JavaScript:

• Tag <a>
• Tag <img>
• Tag <script>
• fetch komponent do wykonywania połączeń
• XMLHttpRequest
• window.open komponent do wykonywania połączeń

Generuje to żądania sieci, na które odpowiadasz nagłówkiem odpowiedzi HTTP rejestracji źródła.

Rejestrowanie źródeł kliknięć lub wyświetleń

Aby zarejestrować źródło atrybucji kliknięć lub wyświetleń, wykonaj podane tutaj czynności. Poniżej znajdziesz szczegółowe instrukcje. Oto podsumowanie:

1. Zainicjuj rejestrację źródła. Aby wysłać żądanie, użyj elementu HTML lub wywołania JavaScript. Jak zobaczysz w następnych sekcjach, ten krok jest inny w przypadku kliknięć i obejrzeń.

2. Uzupełnij rejestrację źródła, odpowiadając nagłówkiem rejestracji źródła. Po otrzymaniu tej prośby odpowiedz, używając nagłówka Attribution-Reporting-Register-Source. W tym nagłówku podaj wybraną konfigurację raportowania atrybucji. Ten krok jest taki sam w przypadku kliknięć i wyświetleń.

   Przykład raportu zbiorczego:

   {
     "aggregation_keys": {
       "campaignCounts": "0x159",
       "geoValue": "0x5"
     },
     "aggregatable_report_window": "86400",
     "destination": "https://example.com"
   }
   

   Przykład raportów na poziomie zdarzenia:

   {
     "source_event_id": "12340873456",
     "destination": "[eTLD+1]",
     "expiry": "[64-bit signed integer]",
     "priority": "[64-bit signed integer]",
     "event_report_window": "[64-bit signed integer]"
   }
   

Atrybuty wymagane i opcjonalne

Jeśli używasz elementów HTML lub wywołań JavaScript, aby rejestrować źródła, możesz potrzebować elementu attributionsrc lub attributionReporting. Szczegółowe informacje o tym, kiedy są wymagane, znajdziesz w tabeli poniżej.

Jeśli parametr attributionsrc jest opcjonalny, jego użycie oznacza, że żądanie kwalifikuje się do raportowania atrybucji. Jeśli używasz parametru attributionsrc, przeglądarka wysyła nagłówek Attribution-Reporting-Eligible. Jest on też przydatny do pomiarów z aplikacji do sieci: jeśli występuje attributionsrc, przeglądarka wysyła nagłówek Attribution-Reporting-Support.

Krok 1. Rozpocznij rejestrowanie źródła

Krok 1 różni się w przypadku kliknięć i wyświetleń.

Aby zarejestrować źródło atrybucji kliknięcia, możesz użyć tagu <a> lub kodu JavaScriptwindow.open().

Używanie kotwicy

Dodaj tag attributionsrc do dotychczasowych tagów <a>, dla których chcesz mierzyć wyświetlenia lub kliknięcia:

<a href="https://shoes.example/..." attributionsrc>Click me</a>

Więcej informacji znajdziesz w przykładowym kodzie.

Za pomocą skryptu

Zadzwoń pod numer window.open(), używając attributionsrc:

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

Aby została wzięta pod uwagę, musi zostać wywołana w ciągu 5 sekund od interakcji użytkownika.

Zamiast dodawać attributionsrc samodzielnie, możesz podać pojedynczą wartość adresu URL dla obrazu lub skryptu:

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

Jeśli w przypadku kodu JavaScriptu podasz wartość parametru attributionsrc, pamiętaj, aby zakodować ten adres URL, ponieważ może on zawierać znaki specjalne, np. =, które mogłyby spowodować nieprawidłowe zanalizowanie parametru.

Koduj w ten sposób:

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

attributionsrc może też przyjmować listę adresów URL oddzielonych spacjami, jak pokazano tutaj za pomocą tagu <a>:

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

lub w przypadku tego przykładu za pomocą window.open().

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

W takich przypadkach oba adresy URL otrzymują kwalifikujące się do źródeł nawigacji attributionsrcżądania (żądania zawierające nagłówek Attribution-Reporting-Eligible).

attributionsrc z wartością lub bez niej

Jak już wiesz, możesz podać attributionsrc bez adresu URL. Możesz też podać pojedynczy adres URL. Możesz też użyć listy adresów URL oddzielonych spacjami.

Użycie adresów URL powoduje, że przeglądarka inicjuje oddzielne żądanie pobierania keepalive (po jednym dla każdego adresu URL), które zawiera nagłówek Attribution-Reporting-Eligible.

Jest to przydatne, jeśli chcesz zarejestrować źródło, odpowiadając na żądanie, które jest oddzielne od głównego żądania elementu.

Jeśli na przykład chcesz rejestrować źródła kliknięć elementu kotwicy, możesz nie mieć kontroli nad miejscem docelowym. W takim przypadku możesz skonfigurować wysyłanie nagłówka rejestracji źródła w odpowiedzi na żądanie, które jest oddzielone od nawigacji i które możesz w pełni kontrolować. Określając wartość domyślną dla parametru attributionsrc, instruujesz przeglądarkę, aby wysłała dodatkowe żądanie i skonfigurowała jego miejsce docelowe.

Aby zarejestrować źródło atrybucji wyświetlenia, możesz użyć tagu obrazu lub skryptu, do którego dodasz atrybut attributionsrc.

Możesz też użyć JavaScriptu fetch() lub XMLHttpRequest().

Z obrazem

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

Z wykorzystaniem skryptu

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

Opcjonalnie możesz podać wartość adresu URL dla tagu attributionsrc w taki sam sposób jak w przypadku tagu śledzenia kliknięć. Oznacza to, że w przypadku obrazu lub skryptu możesz ustawić adres URL tagu attributionsrc w ten sposób:

Z pojedynczym adresem URL:

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

Za pomocą listy adresów URL:

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

Korzystanie z fetch() lub XMLHttpRequest()

Ten kod skutecznie symuluje działanie żądania HTML z parametrem attributionsrc:

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

// Optionally set keepalive to make sure the request outlives the page.
window.fetch("https://adtech.example/attribution_source?my_ad_id=123",
  { keepalive: true, attributionReporting });

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

const req = new XMLHttpRequest();
req.open("GET", url);
req.setAttributionReporting(attributionReporting);
req.send();

Krok 2. Odpowiedz z nagłówkiem (kliknięcia i wyświetlenia)

Kolejnym krokiem w przypadku zarówno kliknięć, jak i wyświetleń jest odpowiedź z nagłówkiem Attribution-Reporting-Register-Source.

Więcej informacji znajdziesz w przykładowym kodzie.

Po otrzymaniu żądania przeglądarki na serwerze odpowiedz i uwzględnij w swojej odpowiedzi nagłówek Attribution-Reporting-Register-Source.

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    // Use source_event_id to map it to any granular information
    // you need at ad-serving time
    source_event_id: "412444888111012",
    destination: "https://advertiser.example",
    // Optional fields
    expiry: "604800",
    priority: "100",
    debug_key: "122939999"
  })
);

Po przetworzeniu na ciąg znaków nagłówek będzie wyglądać tak:

{"source_event_id":"412444888111012","destination":"https://advertiser.example","expiry":"604800","priority":"100","debug_key":"122939999"}

Dalsze kroki

Dowiedz się, jak rejestrować reguły atrybucji.