تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

طرق التسجيل

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

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

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

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

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

بدء تسجيل المصدر. استخدم عنصر HTML أو استدعاء JavaScript لتقديم طلب. تختلف هذه الخطوة بالنسبة إلى النقرات ومرات المشاهدة، كما هو واضح في الأقسام التالية.
أكمل تسجيل المصدر من خلال الرد باستخدام عنوان تسجيل المصدر. وبعد تلقّي هذا الطلب، يمكنك الردّ باستخدام العنوان 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: بدء تسجيل المصدر

تختلف الخطوة الأولى بالنسبة إلى النقرات ومرات المشاهدة. افتح علامات التبويب المقابلة لكل منها.

لتسجيل مصدر إحالة لإحدى النقرات، يمكنك استخدام علامة <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">

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

يُرجى ترميز ما يلي:

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

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

<!-- With an anchor tag -->
<a href=... attributionsrc="https://a.example/register-source 
  https://b.example/register-source">

أو كما هي حاليًا باستخدام window.open().

// With window.open()
window.open('...', '_blank', attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2})

في هذه الحالات، يتلقّى كلا عنوانَي URL طلبات attributionsrc navigation-source-eligible (الطلبات التي تتضمّن العنوان 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=..."/>

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

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

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

من خلال قائمة بعناوين URL:

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

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

يحاكي هذا الرمز بشكل فعّال ما يمكن أن يفعله طلب HTML باستخدام attributionsrc:

// With fetch
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 });

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

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

بالنسبة إلى الخطوة 1 من تسجيل النقرات، انتقِل إلى علامات التبويب، واختَر الخطوة 1 من "النقرات".

الخطوة 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"}

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

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