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

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

مصدر تحديد المصدر هو حدث مرتبط بالإعلان (نقرة أو مشاهدة)، ويمكن لتكنولوجيا الإعلان إرفاق الأنواع التالية من المعلومات به:

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

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

طُرق التسجيل

لتسجيل مصادر الإحالة، استخدِم عناصر HTML أو طلبات JavaScript:

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

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

تسجيل مصادر النقرات أو المشاهدات

لتسجيل مصدر تحديد مصدر إمّا للنقرات أو المشاهدات، اتّبِع الخطوات الموضّحة هنا. الخطوات الكاملة التالية في ما يلي ملخّص:

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

2. أكمِل عملية تسجيل المصدر من خلال الردّ باستخدام عنوان تسجيل المصدر. عند تلقّي هذا الطلب، يُرجى الردّ باستخدام العنوان Attribution-Reporting-Register-Source. في هذا العنوان، حدِّد إعدادات تقارير تحديد المصدر التي تم اختيارها. وتُطبَّق هذه الخطوة نفسها على كلّ من النقرات والمشاهدات.

   مثال على التقارير الموجزة:

   {
     "aggregation_keys": {
       "campaignCounts": "0x159",
       "geoValue": "0x5"
     },
     "aggregatable_report_window": "86400",
     "destination": "https://example.com"
   }
   

   مثال على التقارير على مستوى الحدث:

   {
     "source_event_id": "12340873456",
     "destination": "[eTLD+1]",
     "expiry": "[64-bit signed integer]",
     "priority": "[64-bit signed integer]",
     "event_report_window": "[64-bit signed integer]"
   }
   

السمات المطلوبة والاختيارية

عند استخدام عناصر HTML أو إجراء طلبات JavaScript لتسجيل المصادر، قد تحتاج إلى استخدام attributionsrc أو attributionReporting. يُرجى الرجوع إلى الجدول التالي لمعرفة الحالات التي يكون فيها استخدام هذه العناصر مطلوبًا.

عندما تكون السمة attributionsrc اختيارية، يشير استخدامها إلى أنّ الطلب مؤهّل لميزة "تقارير تحديد المصدر". في حال استخدام attributionsrc، يُرسِل المتصفّح العنوان Attribution-Reporting-Eligible. وهو مفيد أيضًا لقياس الأداء من التطبيق إلى الويب: إذا كان attributionsrc متوفّرًا، يُرسِل المتصفّح العنوان Attribution-Reporting-Support.

الخطوة 1: بدء تسجيل المصدر

تختلف الخطوة 1 بالنسبة إلى النقرات والمشاهدات.

لتسجيل مصدر إحالة لنقرة، يمكنك استخدام علامة <a> أو JavaScript window.open().

استخدام عنصر تثبيت

أضِف attributionsrc إلى علامات <a> الحالية التي تريد قياس مرّات ظهورها أو نقراتها:

<a href="https://shoes.example/..." attributionsrc>Click me</a>

راجِع مثال الرمز البرمجي للحصول على مزيد من المعلومات.

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

اتصل بـ window.open() باستخدام attributionsrc:

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

لكي يتم أخذ هذه الطريقة في الاعتبار، يجب استدعاؤها في غضون 5 ثوانٍ من تفاعل المستخدم.

بدلاً من إضافة attributionsrc بمفرده، يمكنك تحديد قيمة عنوان URL واحدة للصورة أو النص البرمجي:

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

في حالة JavaScript، إذا أعطيت قيمة attributionsrc، تأكَّد من ترميز عنوان URL هذا في حال كان يحتوي على أحرف خاصة مثل = التي قد تؤدي إلى تحليل المَعلمة بشكل غير صحيح.

يجب ترميزها على النحو التالي:

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

يمكن أن تأخذ attributionsrc أيضًا قائمة بعناوين URL مفصولة بمسافات كما هو موضّح هنا باستخدام علامة <a>:

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

أو كما هو موضح هنا باستخدام window.open().

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

في هذه الحالات، يتلقّى كلا عنوانَي URL طلبات attributionsrc مؤهّلة لمصدر التنقّل (الطلبات التي تتضمّن العنوان Attribution-Reporting-Eligible).

attributionsrc مع قيمة أو بدونها

كما رأيت سابقًا، يمكنك تحديد attributionsrc بدون عنوان URL. يمكنك أيضًا تحديد عنوان URL واحد. بالإضافة إلى ذلك، يمكنك استخدام قائمة بعناوين URL مفصولة بمسافات.

يؤدي استخدام عناوين URL إلى أن يبدأ المتصفّح طلب جلب منفصل للحفاظ على الاتّصال، وهو طلب واحد لكل عنوان URL، يتضمّن عنوان Attribution-Reporting-Eligible الطلب.

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

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

لتسجيل مصدر إحالة لعرض، يمكنك استخدام علامة صورة أو نص برمجي ستضيف إليه السمة attributionsrc.

بدلاً من ذلك، يمكنك استخدام JavaScript fetch() أو XMLHttpRequest().

باستخدام صورة

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

باستخدام نص

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

يمكنك اختياريًا تحديد قيمة عنوان URL لسمة attributionsrc بالطريقة نفسها التي يتم بها تحديد قيمة لسمة النقرات، أي أنّه بالنسبة إلى صورة أو نص برمجي، يمكنك ضبط عنوان URL لسمة attributionsrc أو عناوين URL على النحو التالي:

باستخدام عنوان URL واحد:

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

باستخدام قائمة عناوين URL:

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

استخدام fetch() أو XMLHttpRequest()

تحاكي هذه التعليمات البرمجية بفعالية ما سيفعله طلب HTML الذي يتضمّن attributionsrc:

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

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

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

الخطوة 2: الردّ باستخدام عنوان (النقرات والمشاهدات)

الخطوة التالية لكلّ من النقرات والمشاهدات هي الردّ باستخدام العنوان Attribution-Reporting-Register-Source.

راجِع مثال الرمز البرمجي للحصول على مزيد من المعلومات.

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

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    // Use source_event_id to map it to any granular information
    // you need at ad-serving time
    source_event_id: "412444888111012",
    destination: "https://advertiser.example",
    // Optional fields
    expiry: "604800",
    priority: "100",
    debug_key: "122939999"
  })
);

بعد تحويل الرأس إلى سلسلة، سيظهر على النحو التالي:

{"source_event_id":"412444888111012","destination":"https://advertiser.example","expiry":"604800","priority":"100","debug_key":"122939999"}

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

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