إعداد تقارير الإحالة: نظرة عامة كاملة على النظام

نظرة عامة شاملة على الخدمات المرتبطة ببعضها في "إعداد تقارير تحديد المصدر"، تستهدف متّخذي القرارات الفنية.

تتيح Attribution Reporting API لمزوّدي تكنولوجيا الإعلان والمعلِنين قياس الحالات التي تؤدّي فيها النقرة على الإعلان أو مشاهدته إلى إحالة ناجحة، مثل عملية شراء. تعتمد واجهة برمجة التطبيقات هذه على مزيج من عمليات الدمج من جهة العميل ومن جهة الخادم، وذلك حسب احتياجات نشاطك التجاري.

قبل المتابعة، احرص على قراءة نظرة عامة حول Attribution Reporting. سيساعدك ذلك في فهم الغرض من واجهة برمجة التطبيقات وتدفّق تقارير النتائج المختلفة (التقرير على مستوى الحدث والتقارير الموجزة). إذا صادفت مصطلحات غير مألوفة، يمكنك الرجوع إلى مسرد مصطلحات "مبادرة حماية الخصوصية".

مَن هم المستخدمون المعنيّون بهذا المستند؟

عليك قراءة هذا المستند في الحالات التالية:

• أن تكون صاحب قرار تقني في مجال تكنولوجيا الإعلان أو لدى المعلِن قد تعمل في العمليات أو DevOps أو علم البيانات أو تكنولوجيا المعلومات أو التسويق أو أي دور آخر تتخذ فيه قرارات بشأن التنفيذ الفني. تتساءل عن طريقة عمل واجهات برمجة التطبيقات لقياس الأداء مع الحفاظ على الخصوصية.
• أنت ممارس تقني (مثل مطوّر أو مشغّل نظام أو مهندس نظام أو عالم بيانات) ستعمل على إعداد تجارب باستخدام واجهة برمجة التطبيقات وبيئة "خدمة التجميع".

يتضمّن هذا المستند شرحًا شاملاً وعالي المستوى لطريقة عمل الخدمات في واجهة برمجة التطبيقات Attribution Reporting API. إذا كنت من الخبراء الفنيين، يمكنك تجربة واجهة برمجة التطبيقات هذه محليًا.

نظرة عامة

تتألف واجهة برمجة التطبيقات Attribution Reporting من العديد من الخدمات التي تتطلّب إعدادًا محدّدًا وإعدادات من جهة العميل وعمليات نشر على الخادم. لتحديد ما تحتاج إليه، عليك أولاً:

• اتّخاذ قرارات التصميم: حدِّد المعلومات التي تريد جمعها، وحدِّد الإحالات الناجحة التي تتوقّعها من أي حملة معيّنة، وحدِّد نوع التقرير الذي تريد جمعه. الناتج النهائي هو أحد نوعَي التقارير أو كلاهما: التقارير على مستوى الحدث والتقارير الموجزة.

هناك دائمًا مكوّنان (وأحيانًا ثلاثة) يعملان معًا لإتاحة إعداد التقارير:

• التواصل بين الموقع الإلكتروني والمتصفّح: في الأنظمة المستندة إلى ملفات تعريف الارتباط، يتم ربط المعلومات الخاصة بالإحالات الناجحة والتفاعلات مع الإعلانات بمعرّف يتيح لك أو لخدمة إحصاءات ربط هذه الأحداث لاحقًا. باستخدام واجهة برمجة التطبيقات هذه، يربط المتصفّح الإحالات الناجحة بالنقرات على الإعلانات أو مشاهداتها، استنادًا إلى تعليماتك، قبل إرسالها لتحليلها. لذلك، يجب أن يتضمّن رمز عرض الإعلان وتتبُّع الإحالات الناجحة ما يلي:
  • تحديد الإحالات الناجحة التي يجب إسنادها إلى النقرات على الإعلانات أو مرّات ظهورها
  • أشِر إلى أي بيانات أخرى تريد تضمينها في التقارير النهائية.
• جمع البيانات: ستحتاج إلى نقطة نهاية لجامع البيانات من أجل تلقّي التقارير التي يتم إنشاؤها في متصفّحات المستخدمين. يمكن أن يكون الناتج من المتصفّحات أحد التقريرَين المحتملَين التاليَين: تقارير على مستوى الحدث وتقارير قابلة للتجميع (وهي مشفّرة وتُستخدَم لإنشاء تقارير موجزة).

إذا جمعت تقارير قابلة للتجميع، ستحتاج إلى مكوّن ثالث:

• إنشاء تقرير موجز تجميع التقارير القابلة للتجميع في دفعات واستخدام "خدمة تجميع البيانات" لمعالجة التقارير من أجل إنشاء تقرير موجز

قرارات التصميم

من المبادئ الأساسية في Attribution Reporting اتّخاذ قرارات التصميم مبكرًا. يمكنك تحديد البيانات التي تريد جمعها في أي فئات وعدد مرات معالجة هذه البيانات. تقدّم تقارير النتائج إحصاءات عن حملاتك أو نشاطك التجاري.

يمكن أن يكون تقرير الناتج:

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

يحدّد اختيار التقرير البيانات التي عليك جمعها.

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

بعد تحديد ما تريد قياسه، يمكنك إعداد جهة العميل لواجهة برمجة التطبيقات Attribution Reporting API.

التواصل بين الموقع الإلكتروني والمتصفّح

مسار حدث تحديد المصدر

لنفترض أنّ هناك موقعًا إلكترونيًا للناشر يعرض إعلانات. يريد كل معلِن أو مزوّد تكنولوجيا إعلان التعرّف على التفاعلات مع إعلاناته ونَسب الإحالات الناجحة إلى الإعلان الصحيح. سيتم إنشاء التقارير (على مستوى الحدث والقابلة للتجميع) على النحو التالي:

1. على موقع الناشر الإلكتروني، يتمّ إعداد عنصر إعلان (علامة <a> أو <img>) باستخدام سمة خاصّة attributionsrc. وقيمته هي عنوان URL، مثل https://adtech.example/register-source/ad_id=....

   في ما يلي مثال على رابط سيسجّل مصدرًا عند النقر عليه:

   <a href="https://shoes.example/landing"
     attributionsrc="http://adtech.example/register-source?..."
     target="_blank">
   Click me</a>
   

   في ما يلي مثال على صورة ستؤدي إلى تسجيل مصدر عند عرضها:

   <img href="https://advertiser.example/landing"
     attributionsrc="https://adtech.example/register-source?..."/>
   

   بدلاً من ذلك، يمكن استخدام طلبات JavaScript بدلاً من عناصر HTML.

   في ما يلي مثال على JavaScript باستخدام window.open(). يُرجى العِلم أنّه يتم تشفير عنوان URL لتجنُّب المشاكل المتعلقة بالأحرف الخاصة.

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

2. عندما ينقر المستخدِم على الإعلان أو يشاهده، يرسل المتصفّح طلب GET إلى attributionsrc، وهو عادةً نقطة نهاية خاصة بالمعلِن أو مزوّد تكنولوجيا الإعلان.

3. عند تلقّي هذا الطلب، يقرّر المعلِن أو مزوّد تكنولوجيا الإعلان إصدار تعليمات للمتصفّح بتسجيل أحداث المصدر للتفاعلات مع الإعلان، حتى يمكن لاحقًا تحديد مصدر الإحالات الناجحة على أنّها من هذا الإعلان. لإجراء ذلك، يدرج المعلِن أو مقدّم تكنولوجيا الإعلان في استجابته عنوان HTTP خاصًا. ويتم إرفاق بيانات مخصّصة بهذا العنوان تقدّم معلومات عن الحدث المصدر (النقر على الإعلان أو مشاهدته)، وفي حال حدوث إحالة ناجحة لهذا الإعلان، سيتم عرض هذه البيانات المخصّصة في النهاية في تقرير تحديد المصدر.

   

4. في وقت لاحق، يزور المستخدم الموقع الإلكتروني للمعلِن.

5. في كل صفحة ذات صلة من الموقع الإلكتروني للمعلن، مثل صفحة تأكيد الشراء أو صفحة المنتج، يرسل بكسل الإحالة الناجحة (عنصر <img>) أو طلب JavaScript طلبًا إلى https://adtech.example/conversion?param1=...&param2=....

6. تتلقّى الخدمة المتوفّرة على عنوان URL هذا الطلب، وهي عادةً المعلِن أو مزوّد تقنية الإعلانات. يقرّر النظام تصنيف هذا الإجراء كإحالة ناجحة، لذا يجب أن يطلب من المتصفّح تسجيل إحالة ناجحة، أي بدء عملية تحديد المصدر. ولإجراء ذلك، يدرج المعلِن أو مقدّم تكنولوجيا الإعلان في رده على طلب وحدة البكسل عنوان HTTP خاصًا يتضمّن بيانات مخصّصة حول الإحالة الناجحة.

7. يتلقّى المتصفّح هذه الاستجابة على جهاز المستخدِم المحلي، ويطابق بيانات الإحالة الناجحة مع حدث المصدر الأصلي (النقر على الإعلان أو مشاهدته).

8. يحدّد المتصفّح موعدًا لإرسال تقرير إلى attributionsrc. يتضمّن هذا التقرير ما يلي:

   1. بيانات إعدادات تحديد المصدر المخصّصة التي أرفقها مقدّم تكنولوجيا الإعلان أو المعلِن بحدث المصدر في الخطوة 3
   2. مجموعة بيانات الإحالات الناجحة المخصّصة في الخطوة 6

   

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

مشغّلات تحديد المصدر (الموقع الإلكتروني للمعلن)

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

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

يؤكّد ذلك أنّ النتائج المجمّعة مفصّلة ودقيقة لهذه الأحداث.

ربط مصادر البيانات بالعوامل المشغِّلة

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

على سبيل المثال، عندما يتلقّى المتصفّح مشغّلاً لتحديد المصدر من adtech.example على shoes.example/shoes123، يبحث المتصفّح عن مصدر في وحدة التخزين المحلية يتطابق مع كل من adtech.example وshoes.example.

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

في حال العثور على مصادر تحديد مصدر متعددة في مساحة التخزين المحلية، يختار المتصفّح المصدر الذي تم تخزينه مؤخرًا. في بعض الحالات التي يتم فيها تحديد أولوية لمصادر تحديد المصدر، سيختار المتصفّح المصدر الذي لديه الأولوية الأعلى.

جمع البيانات

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

تُستخدَم التقارير القابلة للتجميع لإنشاء تقارير موجزة. التقرير القابل للتجميع هو مزيج من البيانات التي يتم جمعها من الإعلان (على موقع الناشر) وبيانات الإحالات الناجحة (من موقع المعلِن)، ويتم إنشاؤه وتشفيره بواسطة المتصفّح على جهاز المستخدِم قبل أن تجمعها تكنولوجيا الإعلان.

تتأخّر التقارير على مستوى الحدث بين يومَين و30 يومًا. يتم إرسال التقارير القابلة للتجميع مع تأخير عشوائي خلال ساعة واحدة، ويجب أن تتناسب الأحداث مع ميزانية المساهمة. تحمي هذه الخيارات الخصوصية وتمنع استغلال إجراءات أي مستخدم فردي.

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

إنشاء تقرير موجز

لإنشاء تقارير موجَزة، عليك استخدام خدمة تجميع البيانات (التي يديرها مزوّد تكنولوجيا الإعلان) لمعالجة التقارير القابلة للتجميع. تضيف "خدمة تجميع البيانات" تشويشًا لحماية خصوصية المستخدم وتعرض التقرير التلخيصي النهائي.

التقارير المجمَّعة القابلة للتجميع على دفعات

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

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

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

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

تتولّى خدمة تجميع البيانات مسؤولية معالجة التقارير القابلة للتجميع من أجل إنشاء تقرير موجَز. يتم تشفير التقارير القابلة للتجميع، ولا يمكن قراءتها إلا من خلال "خدمة تجميع البيانات" التي تعمل في بيئة تنفيذ موثوقة (TEE).

تطلب "خدمة تجميع البيانات" مفاتيح فك التشفير من المنسّق لفك تشفير البيانات وتجميعها. وبعد فك ترميز النتائج وتجميعها، يتم تشويشها للحفاظ على الخصوصية وعرضها كتقرير تلخيصي.

يمكن للممارسين إنشاء تقارير نصية عادية قابلة للتجميع من أجل اختبار "خدمة تجميع البيانات" على الجهاز. أو يمكنك الاختبار باستخدام التقارير المشفّرة على AWS مع Nitro Enclaves.

ما هي الخطوات التالية؟

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

مناقشة واجهة برمجة التطبيقات

وكما هو الحال مع واجهات Privacy Sandbox API الأخرى، تم توثيق واجهة برمجة التطبيقات هذه ومناقشتها بشكل علني.

تجربة واجهة برمجة التطبيقات

يمكنك تجربة واجهة برمجة التطبيقات Attribution Reporting API والمشاركة في محادثة حولها.