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

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

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

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

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

طرق التسجيل

لتسجيل مصادر تحديد المصدر، استخدِم عناصر 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، بما في ذلك طلب 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"}

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

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