تسجيل مشغّلات الإحالة

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

مشغّل الإحالة هو الحدث الذي يخبر المتصفّح بتسجيل الإحالات الناجحة.

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

طرق التسجيل

لتسجيل المشغلات، استخدم عناصر HTML أو استدعاءات JavaScript:

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

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

تسجيل مشغِّل لتحديد مصدر إحالة ناجحة

ويشبه تسجيل مشغِّل تسجيل حدث مصدر تحديد مصدر. ويتم توضيح الخطوات الكاملة لاحقًا. وفي ما يلي الملخص:

1. ابدأ تسجيل العامل المشغِّل. يمكنك استخدام هاتف pixel أو fetch() لتقديم طلب.

2. أكمِل عملية تسجيل المشغِّل من خلال الردّ باستخدام عنوان تسجيل المُشغِّل.
   
   

   عند تلقّي طلب وحدة البكسل، الذي يتم إرساله إما إلى نقطة النهاية المحدّدة في السمة src المعتادة، أو إلى نقطة النهاية المحدّدة في attributionsrc إذا اخترت استخدام attributionsrc ومنحتها قيمة، يمكنك الردّ مع العنوان Attribution-Reporting-Register-Trigger.
   
   

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

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

   {
     "event_trigger_data": [{
       "trigger_data": "[unsigned 64-bit integer]",
       "priority": "[signed 64-bit integer]",
       "deduplication_key": "[unsigned 64-bit integer]"
     }]
   }
   ```
   
   **Example for summary reports:**
   
   ```json
   {
     ... // existing fields, such as "event_trigger_data"
   
     "aggregatable_trigger_data": [
      {
        "key_piece": "0x400",
        "source_keys": ["campaignCounts"]
      },
      {
        "key_piece": "0xA80",
        "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"]
      }
     ],
     "aggregatable_values": {
       "campaignCounts": 32768,
       "geoValue": 1664
     }
   }
   ```
   

التعامل مع النطاقات الفرعية

إذا كانت قيمة destination هي https://advertiser.example، يمكن تحديد مصدر الإحالات الناجحة على كلٍّ من https://advertiser.example ونطاقاته الفرعية، مثل https://shop.advertiser.example.

إذا كانت قيمة destination هي https://shop.advertiser.example، يمكن تحديد مصدر الإحالات الناجحة في كلّ من https://advertiser.example وhttps://shop.advertiser.example.

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

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

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

طريقة التسجيل	عامل التفعيل
علامة <a>	لا ينطبق لا يمكن لعلامات الارتساء تسجيل عامل تشغيل.
علامة <img>	attributionsrc اختياري. يكفي العنوان لتسجيل المشغّل.
علامة <script>	attributionsrc اختياري. العنوان كافٍ لتسجيل المشغل.
مكالمة واحدة (fetch)	إنّ الخيار attributionReporting مطلوب.
XMLHttpRequest	إنّ الخيار attributionReporting مطلوب.
window.open()	لا ينطبق لا يمكن لـ window.open تسجيل مشغِّل.

الخطوة 1: بدء تسجيل المشغِّل

يمكنك تسجيل مشغِّل باستخدام علامة بكسل (علامة <img>) أو علامة نص برمجي.

استخدام وحدة بكسل إحالة ناجحة جديدة أو حالية

يؤدي المثال التالي إلى بدء نسب العمل إلى صورة حالية من خلال إضافة سمة attributionsrc.

يجب أن يتطابق أصل attributionsrc مع المصدر الذي تم تسجيل المصدر فيه.

<img src="https://advertiser.example/conversionpixel"
     attributionsrc="https://adtech.example/attribution_trigger?purchase=13">

يؤدّي المثال التالي إلى بدء عملية تحديد المصدر من خلال إضافة سمة جديدة لوحدات بكسل الإحالة الناجحة attributionsrc.

يجب أن يتطابق أصل src مع المصدر الذي تم تسجيل المصدر فيه.

<img src="https://adtech.example/conversionpixel"
     attributionsrc>

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

يمكنك إجراء تسجيل المشغِّل باستخدام علامة نص برمجي، وتعمل هذه العلامة مثل <img>. توضح نماذج الرموز التالية استخدام fetch() وXMLHttpRequest() (XHR).

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

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

// 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 XMLHttpRequest:
const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

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

attributionsrc بقيمة أو بدون قيمة

يمكنك إضافة attributionsrc إما بقيمة أو بدونها.

<!-- Without a value -->
<img src="..." width="1" height="1" attributionsrc>

<!--With a value (URL) -->
<img src="..." width="1" height="1" attributionsrc="https://...">

وفي حال ضبط قيمة للسمة attributionsrc، يجب أن تكون القيمة عنوان URL واحدًا.

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

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

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

الخطوة 2: الرد باستخدام عنوان

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

JSON.stringify({event_trigger_data: [{
      trigger_data: '412444888111012',
      // Optional
      priority: '1000000000000',
      deduplication_key: '2345698765'
    }], debug_key: '1115698977'})

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

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