Zarejestruj reguły atrybucji

Dowiedz się, jak rejestrować reguły atrybucji na potrzeby zliczania konwersji.

Reguła atrybucji to zdarzenie, które informuje przeglądarkę, że ma zarejestrować konwersje.

Wykonując czynności opisane w tym dokumencie, możesz rejestrować reguły rejestracji konwersji, które przeglądarka przypisuje do odpowiednich zdarzeń źródłowych, np. wyświetleń lub kliknięć reklam.

Metody rejestracji

Aby zarejestrować reguły, użyj elementów HTML lub wywołań JavaScript:

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

Spowoduje to wygenerowanie żądań sieciowych, na które możesz następnie odpowiedzieć za pomocą nagłówka odpowiedzi HTTP rejestracji aktywatora.

Zarejestruj regułę, aby przypisać konwersję

Rejestrowanie reguły przypomina rejestrowanie zdarzenia źródła atrybucji. Pełne instrukcje znajdziesz w dalszej części artykułu. Oto podsumowanie:

1. Rozpocznij rejestrację reguły. Wyślij żądanie za pomocą piksela lub wywołania fetch().

2. Dokończ rejestrację aktywatora, odpowiadając za pomocą nagłówka rejestracji aktywatora.
   
   

   Po otrzymaniu żądania piksela, które jest wysyłane do punktu końcowego zdefiniowanego w zwykłym atrybucie src lub do punktu końcowego zdefiniowanego w zasadzie attributionsrc, jeśli używasz elementu attributionsrc i nadajesz mu wartość, wyślij odpowiedź z nagłówkiem Attribution-Reporting-Register-Trigger.
   
   

   W tym nagłówku określ dane reguły, które mają się ostatecznie pojawiać w raportach. Ten nagłówek może być ustawiany przez każdą odpowiedź. Jeśli jest to odpowiedź na żądanie wysłane z witryny, która pasuje do destination, źródła będą dopasowywane. Po otrzymaniu nagłówka przeglądarka szuka pasujących źródeł i planuje wysłanie raportu.

   Przykładowe raporty na poziomie zdarzenia:

   {
     "event_trigger_data": [{
       "trigger_data": "[unsigned 64-bit integer]",
       "priority": "[signed 64-bit integer]",
       "deduplication_key": "[unsigned 64-bit integer]"
     }]
   }
   ```
   
   **Example for summary reports:**
   
   ```json
   {
     ... // existing fields, such as "event_trigger_data"
   
     "aggregatable_trigger_data": [
      {
        "key_piece": "0x400",
        "source_keys": ["campaignCounts"]
      },
      {
        "key_piece": "0xA80",
        "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"]
      }
     ],
     "aggregatable_values": {
       "campaignCounts": 32768,
       "geoValue": 1664
     }
   }
   ```
   

Uwaga: gdy przeglądarka otrzyma z adresu URL Attributionsrc na danej stronie odpowiedź aktywującą atrybucję, przeprowadzamy wyszukiwanie w pamięci lokalnej, aby znaleźć źródło pasujące zarówno do źródła atrybucji, jak i adresu eTLD + 1 adresu URL tej strony. <br> W przypadku wielu źródeł przeglądarka wybiera to, które zostało zapisane jako ostatnie, chyba że źródła mają różne priorytety – to z kolei wybiera to, które ma najwyższy priorytet.

Obsługa subdomen

Jeśli destination ma wartość https://advertiser.example, mogą być przypisywane konwersje zarówno w domenie https://advertiser.example, jak i w jej subdomenach, takich jak https://shop.advertiser.example.

Jeśli destination ma wartość https://shop.advertiser.example, można przypisywać udział w konwersjach zarówno ze strony https://advertiser.example, jak i z https://shop.advertiser.example.

Atrybuty wymagane i opcjonalne

Do rejestrowania reguł używasz elementów HTML lub wywołań JavaScriptu, dlatego może być konieczne użycie metody attributionsrc lub attributionReporting. W tabeli poniżej znajdziesz szczegółowe informacje o tym, kiedy są one wymagane.

Gdy pole attributionsrc ma wartość opcjonalne, wskazuje, że żądanie kwalifikuje się do raportowania atrybucji. Jeśli użyjesz właściwości attributionsrc, przeglądarka wysyła nagłówek Attribution-Reporting-Eligible. Jest to też przydatne w przypadku pomiarów między aplikacją a stroną internetową: jeśli atrybut attributionsrc jest podany, przeglądarka wysyła nagłówek Attribution-Reporting-Support.

Metoda rejestracji	Aktywator
Tag <a>	Nie dotyczy Kotwice nie mogą rejestrować reguły.
Tag <img>	Pole attributionsrc jest opcjonalne. Nagłówek jest wystarczający do zarejestrowania aktywatora.
Tag <script>	Pole attributionsrc jest opcjonalne. Nagłówek wystarcza do zarejestrowania aktywatora.
fetch komponent do wykonywania połączeń	Opcja attributionReporting jest wymagana.
XMLHttpRequest	Opcja attributionReporting jest wymagana.
window.open()	Nie dotyczy window.open nie może zarejestrować reguły.

Krok 1. Rozpocznij rejestrację aktywatora

Reguła możesz zarejestrować za pomocą piksela (tagu <img>) lub tagu skryptu.

Używanie nowego lub istniejącego piksela konwersji

<img src="https://ad-tech.example/conversionpixel"
     attributionsrc="https://adtech.example/attribution_trigger?purchase=13">

Ważne: * źródło src musi być zgodny z pierwotnym źródłem rejestracji. * Atrybucję można aktywować tylko na stronie, której parametr eTLD+1 jest zgodny z witryną podaną w miejscu docelowym podczas rejestracji źródła.

Używanie tagu skryptu

Rejestrowanie reguły możesz przeprowadzić za pomocą tagu skryptu. Działa on identycznie jak tag <img>. Poniższe przykłady kodu ilustrują użycie funkcji fetch() i XMLHttpRequest() (XHR).

Ten kod skutecznie symuluje działanie żądania HTML z użyciem elementu attributionsrc:

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

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

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

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

Ważne: źródło parametru <code>src</code> musi odpowiadać źródłom, w którym nastąpiła rejestracja źródła. – Atrybucja może zostać wywołana tylko na stronie, której <a href="https://web.dev/same-site-same-origin/#%22schemeful-same-site%22">eTLD+1</a> jest zgodne z witryną podaną w <code>miejscu docelowym</code> w momencie rejestracji źródłowej.

attributionsrc z wartością lub bez niej

Możesz dodać właściwość attributionsrc z wartością lub bez niej.

<!-- Without a value -->
<img src="..." width="1" height="1" attributionsrc>

<!--With a value (URL) -->
<img src="..." width="1" height="1" attributionsrc="https://...">

Jeśli ustawisz wartość parametru attributionsrc, powinna to być pojedynczy adres URL.

Użycie adresu URL powoduje, że przeglądarka wysyła osobne żądanie pobierania podtrzymujące aktywność – po jednym na każdy adres URL – wraz z nagłówkiem żądania Attribution-Reporting-Eligible.

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

Jeśli np. musisz zarejestrować źródła dla kliknięć elementu zakotwiczonego, możesz nie mieć kontroli nad miejscem docelowym. W tym przypadku potrzebujesz konfiguracji, w której wysyłasz nagłówek rejestracji źródłowej jako odpowiedź na żądanie, które jest niezależne od nawigacji i które możesz w pełni kontrolować. Określając jawną wartość atrybutu attributionsrc, informujesz przeglądarkę, że ma wykonać dodatkowe żądanie i skonfigurować miejsce docelowe.

Krok 2. Odpowiedz z nagłówkiem

Po otrzymaniu żądania przeglądarki wyślij odpowiedź z nagłówkiem Attribution-Reporting-Register-Trigger w swojej odpowiedzi:

JSON.stringify({event_trigger_data: [{
      trigger_data: '412444888111012',
      // Optional
      priority: '1000000000000',
      deduplication_key: '2345698765'
    }], debug_key: '1115698977'})

Uwaga: wartość pola event_trigger_data musi być zagnieżdżone w nawiasach kwadratowych, ponieważ przeglądarka oczekuje tablicy JSON. Jest to przydatne w przypadku filtrów.

Dalsze kroki

Dowiedz się, jak zarejestrować źródła atrybucji.