Zarejestruj reguły atrybucji

Dowiedz się, jak rejestrować wyzwalacze atrybucji, aby zliczać konwersje.

Aktywator atrybucji to zdarzenie, które informuje przeglądarkę o konieczności rejestrowania konwersji.

Wykonując czynności opisane w tym dokumencie, możesz rejestrować wyzwalacze, aby rejestrować konwersje, które przeglądarka przypisuje następnie do odpowiednich zdarzeń źródłowych, czyli wyświetleń lub kliknięć reklam.

Metody rejestracji

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

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

Generuje to żądania sieciowe, na które odpowiadasz za pomocą nagłówka odpowiedzi HTTP rejestracji aktywatora.

Rejestrowanie aktywatora w celu przypisania konwersji

Rejestrowanie zdarzenia aktywującego jest podobne do rejestrowania zdarzenia źródła atrybucji. Pełne instrukcje znajdziesz w dalszej części artykułu. Oto podsumowanie:

  1. Rozpocznij rejestrację wyzwalacza. Użyj piksela lub wywołania fetch(), aby wysłać prośbę.

  2. Zakończ rejestrację aktywatora, odpowiadając nagłówkiem rejestracji aktywatora.

    Po otrzymaniu żądania piksela wysłanego do punktu końcowego zdefiniowanego w zwykłym atrybucie src lub do punktu końcowego zdefiniowanego w atrybucie attributionsrc (jeśli zdecydujesz się użyć atrybutu attributionsrc i podasz jego wartość) odpowiedz nagłówkiem Attribution-Reporting-Register-Trigger.

    W tym nagłówku określ dane wyzwalacza, które mają być ostatecznie widoczne w raportach. Ten nagłówek może ustawić dowolna odpowiedź. Dopóki jest to odpowiedź na żądanie pochodzące z witryny, która pasuje do destination, źródła będą dopasowywane. Gdy nagłówek zostanie odebrany, przeglądarka wyszukuje pasujące źródła i planuje raport.

    Przykład raportów na poziomie zdarzenia:

    {
  "event_trigger_data": [{
    "trigger_data": "[unsigned 64-bit integer]",
    "priority": "[signed 64-bit integer]",
    "deduplication_key": "[unsigned 64-bit integer]"
  }]
}

    Przykład raportów podsumowujących:

    {
  ... // 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
  }
}

Obsługa subdomen

Jeśli destination ma wartość https://advertiser.example, można przypisywać konwersje w https://advertiser.example i jego subdomenach, np. https://shop.advertiser.example.

Jeśli destination ma wartość https://shop.advertiser.example, można przypisywać konwersje zarówno w https://advertiser.example, jak i w https://shop.advertiser.example.

Atrybuty wymagane i opcjonalne

Podczas używania elementów HTML lub wywoływania funkcji JavaScript w celu rejestrowania wyzwalaczy może być konieczne użycie znaków 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.

Metoda rejestracji Aktywator
Tag <a> Nie dotyczy: kotwice nie mogą rejestrować wyzwalacza.
Tag <img> attributionsrc jest opcjonalny. Nagłówek wystarczy do zarejestrowania wyzwalacza.
Tag <script> attributionsrc jest opcjonalny. Nagłówek wystarczy do zarejestrowania wyzwalacza.
fetch komponent do wykonywania połączeń Opcja attributionReporting jest wymagana.
XMLHttpRequest Opcja attributionReporting jest wymagana.
window.open() Nie dotyczy: window.open nie można zarejestrować aktywatora.

Krok 1. Rozpocznij rejestrację reguły

Możesz zarejestrować wyzwalacz za pomocą piksela (<img> tagu) lub tagu skryptu.

Używanie nowego lub dotychczasowego piksela konwersji

Poniższy przykład wywołuje atrybucję na istniejącym obrazie przez dodanie atrybutu attributionsrc.

Źródło attributionsrc musi być zgodne ze źródłem, które przeprowadziło rejestrację źródła.

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

W następnym przykładzie atrybucja jest wywoływana przez dodanie nowego atrybutu piksela konwersji attributionsrc.

Źródło src musi być zgodne ze źródłem, które przeprowadziło rejestrację źródła.

<img src="https://adtech.example/conversionpixel"
     attributionsrc>

Używanie tagu skryptu

Rejestrację wyzwalacza możesz przeprowadzić za pomocą tagu skryptu. Działa on identycznie jak <img>. Poniższe przykłady kodu pokazują, jak używać fetch() i XMLHttpRequest() (XHR).

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

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

// 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: false,
  triggerEligible: true,
};

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

attributionsrc z wartością lub bez niej.

Możesz dodać 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, może to być jeden lub więcej adresów URL oddzielonych spacjami.

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

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

Jeśli na przykład musisz zarejestrować wyzwalacze w elemencie obrazu, możesz nie mieć kontroli nad odpowiedzią dotyczącą obrazu. W takim przypadku warto skonfigurować wysyłanie nagłówka rejestracji wyzwalacza w odpowiedzi na żądanie, które jest oddzielone od obrazu 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.

Krok 2. Odpowiedz z nagłówkiem

Po otrzymaniu żądania przeglądarki odpowiedz i w odpowiedzi umieść nagłówek Attribution-Reporting-Register-Trigger:

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

Dalsze kroki

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