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

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

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

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

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

طرق التسجيل

لتسجيل مصادر تحديد المصدر، استخدِم عناصر 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.

طريقة التسجيل المصدر
علامة <a> (مصدر التنقُّل)
attributionsrc مطلوب.
علامة <img> (مصدر الحدث)
attributionsrc مطلوب.
علامة <script> (مصدر الحدث)
attributionsrc مطلوب.
مكالمة واحدة (fetch) إنّ الخيار attributionReporting مطلوب.
XMLHttpRequest إنّ الخيار attributionReporting مطلوب.
مكالمة واحدة (window.open) (مصدر التنقّل)
attributionsrc مطلوب.

الخطوة 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، بحيث يتضمّن كل عنوان 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 ensure 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"}

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

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