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 platforma reklamowa może dołączyć te rodzaje informacji:

• Dane raportowania kontekstowego, takie jak identyfikator kreacji reklamy, informacje o kampanii czy lokalizacja geograficzna.
• Miejsce docelowe konwersji, czyli witryna, w której spodziewasz się konwersji dokonanych przez użytkowników.

Wykonując czynności opisane w tym dokumencie, możesz zarejestrować źródła – wyświetlenia lub kliknięcia reklam – 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 sieciowe, na które odpowiadasz za pomocą nagłówka odpowiedzi HTTP rejestracji źródła.

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

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

1. Zainicjuj rejestrację źródła. Aby wysłać żądanie, użyj elementu HTML lub wywołania JavaScript. Ten krok różni się w przypadku kliknięć i wyświetleń, o czym przekonasz się w kolejnych sekcjach.

2. Zakończ rejestrację źródła, odpowiadając nagłówkiem rejestracji źródła. Po otrzymaniu takiego żądania odpowiedz nagłówkiem Attribution-Reporting-Register-Source. W tym nagłówku określ wybraną konfigurację raportowania atrybucji. Ten krok jest taki sam w przypadku kliknięć i wyświetleń.

   Przykład raportów podsumowujących:

   {
     "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

Podczas używania elementów HTML lub wywoływania JavaScriptu w celu rejestrowania źródeł może być konieczne użycie attributionsrc lub attributionReporting. Szczegółowe informacje o tym, kiedy są one wymagane, znajdziesz w tabeli poniżej.

Gdy wartość parametru attributionsrc to optional, jego użycie oznacza, że żądanie kwalifikuje się do raportowania atrybucji. Jeśli używasz attributionsrc, przeglądarka wysyła nagłówek Attribution-Reporting-Eligible. Jest to też przydatne w przypadku pomiarów w przejściu z aplikacji do sieci: jeśli występuje attributionsrc, przeglądarka wysyła nagłówek Attribution-Reporting-Support.

Krok 1. Rozpocznij rejestrację ź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ć <a>tagu lub kodu JavaScriptwindow.open().

Używanie kotwicy

Dodaj znak attributionsrc do istniejących tagów <a>, w przypadku 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.

Używanie skryptu

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

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

Aby ta metoda została uwzględniona, musi zostać wywołana w ciągu 5 sekund od interakcji użytkownika.

Zamiast dodawać sam element attributionsrc, w przypadku obrazu lub skryptu możesz określić pojedynczą wartość adresu URL:

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

W przypadku JavaScriptu, jeśli podasz wartość attributionsrc, pamiętaj, aby zakodować ten adres URL, jeśli zawiera znaki specjalne, takie jak =, które mogłyby spowodować nieprawidłowe przeanalizowanie parametru.

Zakoduj w ten sposób:

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

Tag attributionsrc może też zawierać listę adresów URL oddzielonych spacjami, jak pokazano tutaj w przypadku tagu <a>:

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

lub tak jak tutaj, używając znaku window.open().

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

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

attributionsrc z wartością lub bez niej.

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

Używanie adresów URL powoduje, że przeglądarka inicjuje osobne żądanie pobierania typu keepalive – po jednym dla każdego adresu URL – które zawiera nagłówek żądania Attribution-Reporting-Eligible.

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

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

Aby zarejestrować źródło atrybucji dla 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=...">

Ze skryptem

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

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

Pojedynczy adres URL:

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

W przypadku listy adresów URL:

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

Używasz fetch() lub XMLHttpRequest()

Ten kod symuluje działanie żądania HTML z atrybutem 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 za pomocą nagłówka (kliknięcia i wyświetlenia)

W przypadku kliknięć i wyświetleń kolejnym krokiem 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 dołącz do 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 przekształceniu w ciąg nagłówek wygląda tak:

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

Dalsze kroki

Dowiedz się, jak rejestrować wyzwalacze atrybucji.