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

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

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

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

طُرق التسجيل

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

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

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

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

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

  1. ابدأ عملية تسجيل المشغّل. استخدِم وحدة بكسل أو طلب 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 اختيارية، يشير استخدامها إلى أنّ الطلب مؤهَّل لاستخدام Attribution Reporting. في حال استخدام 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 إلى أن يبدأ المتصفّح طلب جلب منفصلاً لإبقاء الاتصال نشطًا، أي طلبًا واحدًا لكل عنوان 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"
});

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

كيفية تسجيل مصادر تحديد المصدر