تسجيل مشغّلات الإحالة

تعرَّف على كيفية تسجيل عوامل تشغيل تحديد المصدر لاحتساب إحالاتك الناجحة.

مشغّل الإحالة هو الحدث الذي يخبر المتصفّح بتسجيل الإحالات الناجحة.

باتّباع الخطوات الواردة في هذا المستند، يمكنك تسجيل عوامل التشغيل لتسجيل الإحالات الناجحة التي ينسبها المتصفّح بعد ذلك إلى أحداث المصدر ذات الصلة، وتحديدًا مرّات ظهور الإعلان أو النقرات على الإعلان.

طرق التسجيل

لتسجيل المشغلات، استخدم عناصر HTML أو استدعاءات JavaScript:

  • علامة <img>
  • علامة <script>
  • مكالمة واحدة (fetch)
  • XMLHttpRequest

يؤدي هذا إلى إنشاء طلبات الشبكة التي تستجيب لها باستخدام عنوان استجابة HTTP لتسجيل المُشغِّل.

تسجيل مشغِّل لتحديد مصدر إحالة ناجحة

يشبه تسجيل المشغل تسجيل حدث مصدر إحالة. ويتم توضيح الخطوات الكاملة لاحقًا. وفي ما يلي الملخص:

  1. ابدأ تسجيل العامل المشغِّل. يمكنك استخدام هاتف pixel أو fetch() لإجراء مكالمة. لطلب ما.

  2. إكمال تسجيل العامل المشغِّل من خلال الرد باستخدام العامل المُشغِّل عنوان التسجيل:

    عند استلام طلب وحدة البكسل، يتم إرساله إما إلى نقطة نهاية محددة في السمة src المعتادة، أو إلى نقطة النهاية المحددة في "attributionsrc" إذا اخترت استخدام "attributionsrc" ومنحته قيمة — تتجاوب مع العنوان Attribution-Reporting-Register-Trigger.

    في هذا العنوان، حدِّد بيانات عامل التفعيل التي تريد عرضها في التقارير في النهاية. ويمكن لأي استجابة ضبط هذا العنوان. طالما أنه ردّ على طلب مقدّم من موقع إلكتروني يتطابق مع 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 أو تجري استدعاءات JavaScript لتسجيل المشغلات، يمكنك قد يحتاج إلى استخدام 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,
};

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

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 });

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 إلى بدء المتصفِّح لطلب جلب منفصل للتحقُّق من الاتصال، واحدًا لكل عنوان URL، بما في ذلك طلب Attribution-Reporting-Eligible .

يكون هذا مفيدًا إذا كنت تريد إجراء تسجيل المشغل من خلال الرد على منفصلة عن الطلب الرئيسي للعنصر.

على سبيل المثال، إذا كنت بحاجة إلى تسجيل المشغلات على عنصر صورة، قد لا تكون متحكّمًا في استجابة الصورة في هذه الحالة، ستحتاج إلى تهيئة حيث ترسل من خلالها رأس تسجيل المشغل كاستجابة لطلب وهي منفصلة عن الصورة، ويمكنك التحكم فيها بشكل كامل. من تحدد قيمة صريحة لـ attributionsrc، فأنت توجه المتصفح لإرسال هذا الطلب الإضافي وإعداد وجهته.

الخطوة 2: الرد باستخدام عنوان

عند تلقّي طلب المتصفّح، يُرجى الردّ على العنوان وتضمين عنوان Attribution-Reporting-Register-Trigger في ردك:

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

الخطوات التالية

تعرَّف على كيفية تسجيل مصادر تحديد المصدر.