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

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

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

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

طرق التسجيل

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

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

يؤدّي هذا إلى إنشاء طلبات الشبكة التي تردّ عليها بعد ذلك باستخدام رأس استجابة 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]"
  }]
}
```

**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
  }
}
```

التعامل مع النطاقات الفرعية

وإذا كانت قيمة 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>) أو علامة نص برمجي.

استخدام وحدة بكسل إحالة ناجحة جديدة أو حالية

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

استخدام علامة نص برمجي

يمكنك تسجيل المشغِّل باستخدام علامة نص برمجي، وهي تعمل تمامًا مع <img>. توضّح نماذج الرموز التالية استخدام fetch() وXMLHttpRequest() (XHR).

يحاكي هذا الرمز بشكل فعّال ما يمكن أن يفعله طلب HTML باستخدام 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();

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

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

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