ثبت محرک های انتساب

بیاموزید که چگونه محرک‌های انتساب را برای شمارش تبدیل‌های خود ثبت کنید.

یک محرک انتساب رویدادی است که به مرورگر می‌گوید تبدیل‌ها را ثبت کند.

با دنبال کردن مراحل موجود در این سند، می‌توانید محرک‌هایی را برای ثبت تبدیل‌هایی ثبت کنید که مرورگر سپس آنها را به رویدادهای منبع مربوطه - یعنی نمایش تبلیغات یا کلیک‌های تبلیغاتی - نسبت می‌دهد.

روش‌های ثبت نام

برای ثبت تریگرها، از عناصر HTML یا فراخوانی‌های جاوا اسکریپت استفاده کنید:

  • تگ <img>
  • تگ <script>
  • fetch واکشی
  • XMLHttpRequest

این درخواست‌های شبکه‌ای ایجاد می‌کند که شما سپس با یک هدر پاسخ HTTP ثبت تریگر به آنها پاسخ می‌دهید.

یک تریگر برای نسبت دادن یک تبدیل ثبت کنید

ثبت یک تریگر مشابه ثبت یک رویداد منبع انتساب است. مراحل کامل بعداً شرح داده می‌شوند. خلاصه در اینجا آمده است:

  1. ثبت تریگر را آغاز کنید. برای ایجاد درخواست از یک پیکسل یا فراخوانی fetch() استفاده کنید.

  2. ثبت تریگر را با پاسخ دادن به هدر ثبت تریگر تکمیل کنید .

    پس از دریافت درخواست پیکسل - که یا به نقطه پایانی تعریف شده در ویژگی src معمول ارسال می‌شود، یا اگر تصمیم به استفاده از attributionsrc گرفته‌اید و به آن مقداری داده‌اید، به نقطه پایانی تعریف شده در attributionsrc ارسال می‌شود - با هدر Attribution-Reporting-Register-Trigger پاسخ دهید.

    در این هدر، داده‌های تریگر (trigger data) مورد نظر خود را که می‌خواهید در نهایت در گزارش‌ها نمایش داده شوند، مشخص کنید. هر پاسخی می‌تواند این هدر را تنظیم کند. تا زمانی که پاسخی به درخواستی باشد که از سایتی ارسال شده است که با destination مطابقت دارد، منابع مطابقت داده می‌شوند. وقتی هدر دریافت می‌شود، مرورگر به دنبال منابع منطبق می‌گردد و گزارش را زمان‌بندی می‌کند.

    مثال برای گزارش‌های سطح رویداد:

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

    مثال برای گزارش‌های خلاصه:

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

کار با زیر دامنه‌ها

اگر destination https://advertiser.example باشد، تبدیل‌ها هم در https://advertiser.example و هم در زیردامنه‌های آن، مانند https://shop.advertiser.example ، قابل نسبت دادن هستند.

اگر destination https://shop.advertiser.example باشد، تبدیل‌ها در هر دو https://advertiser.example و https://shop.advertiser.example قابل نسبت دادن هستند.

ویژگی‌های الزامی و اختیاری

همانطور که از عناصر HTML استفاده می‌کنید یا فراخوانی‌های جاوا اسکریپت را برای ثبت تریگرها انجام می‌دهید، ممکن است نیاز به استفاده attributionsrc یا attributionReporting داشته باشید. برای جزئیات بیشتر در مورد زمان مورد نیاز به این موارد، به جدول زیر مراجعه کنید.

وقتی attributionsrc اختیاری است، استفاده از آن نشان می‌دهد که درخواست واجد شرایط گزارش‌دهی نسبت‌دهی است. اگر از attributionsrc استفاده کنید، مرورگر هدر Attribution-Reporting-Eligible را ارسال می‌کند. همچنین برای اندازه‌گیری از برنامه به وب مفید است: اگر attributionsrc وجود داشته باشد، مرورگر هدر Attribution-Reporting-Support را ارسال می‌کند.

روش ثبت نام ماشه
تگ <a> نامربوط : انکرها نمی‌توانند تریگر ثبت کنند.
تگ <img> attributionsrc اختیاری است. هدر برای ثبت یک تریگر کافی است.
تگ <script> attributionsrc اختیاری است. هدر برای ثبت یک تریگر کافی است.
fetch واکشی گزینه attributionReporting الزامی است.
XMLHttpRequest گزینه attributionReporting الزامی است.
window.open() نامربوط: window.open نمی‌تواند یک تریگر ثبت کند.

مرحله 1: ثبت تریگر را آغاز کنید

شما می‌توانید یک تریگر را با استفاده از یک پیکسل (تگ <img> ) یا تگ اسکریپت ثبت کنید.

استفاده از پیکسل تبدیل جدید یا موجود

مثال زیر با اضافه کردن ویژگی attributionsrc انتساب را روی یک تصویر موجود فعال می‌کند.

مبدا attributionsrc باید با مبدایی که ثبت منبع را انجام داده است، مطابقت داشته باشد.

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

مثال بعدی با اضافه کردن یک ویژگی جدید attributionsrc برای پیکسل تبدیل، انتساب را فعال می‌کند.

مبدا src باید با مبدایی که ثبت مبدا را انجام داده است، مطابقت داشته باشد.

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

استفاده از تگ اسکریپت

شما می‌توانید ثبت تریگر را با یک تگ اسکریپت انجام دهید؛ این تگ دقیقاً مانند <img> رفتار می‌کند. نمونه‌های کد زیر نحوه‌ی استفاده از fetch() و XMLHttpRequest() (XHR) را نشان می‌دهند.

این کد به طور مؤثر کاری را که یک درخواست HTML با 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 با یا بدون مقدار

شما می‌توانید attributionsrc با یا بدون مقدار اضافه کنید.

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

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

اگر مقداری برای attributionsrc تعیین کنید، می‌تواند یک یا چند URL باشد که با فاصله از هم جدا شده‌اند.

استفاده از یک URL باعث می‌شود مرورگر یک درخواست جداگانه برای دریافت keepalive - یکی برای هر URL - که شامل هدر درخواست Attribution-Reporting-Eligible ، آغاز کند.

این مورد زمانی مفید است که بخواهید ثبت تریگر را با پاسخ به درخواستی جدا از درخواست اصلی عنصر انجام دهید.

برای مثال، اگر نیاز به ثبت تریگرها روی یک عنصر تصویر دارید، ممکن است در واقع کنترلی روی پاسخ تصویر نداشته باشید؛ در این حالت، به پیکربندی نیاز خواهید داشت که به موجب آن، هدر ثبت تریگر را به عنوان پاسخی به درخواستی جدا از تصویر ارسال کنید و بتوانید آن را کاملاً کنترل کنید. با تعیین یک مقدار صریح برای attributionsrc ، به مرورگر دستور می‌دهید که آن درخواست اضافی را ایجاد کرده و مقصد آن را پیکربندی کند.

مرحله ۲: با یک هدر پاسخ دهید

پس از دریافت درخواست مرورگر، پاسخ دهید و در پاسخ خود هدر Attribution-Reporting-Register-Trigger را وارد کنید:

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

مراحل بعدی

یاد بگیرید که چگونه منابع استناد را ثبت کنید .