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

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

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

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

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

طُرق التسجيل

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

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

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

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

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

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

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

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

   {
     "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 اختيارية، يشير استخدامها إلى أنّ الطلب مؤهَّل لاستخدام Attribution Reporting. في حال استخدام attributionsrc، يرسل المتصفّح العنوان Attribution-Reporting-Eligible. ويفيد أيضًا في قياس الأداء من التطبيق إلى الويب: إذا كانت attributionsrc متوفّرة، يرسل المتصفّح العنوان Attribution-Reporting-Support.

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

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

لتسجيل مصدر تحديد المصدر لنقرة، يمكنك استخدام علامة <a> أو JavaScriptwindow.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 أو عناوين URL الخاصة بـ attributionsrc على النحو التالي:

باستخدام عنوان 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"}

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

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