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

نظرة عامة شاملة على الخدمات المرتبطة بإعداد تقارير تحديد المصدر، موجَّهة إلى صنّاع القرار التقنيين.

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

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

من هم المستخدمون المعنيون بهذه المقالة؟

يجب قراءة هذه المقالة في الحالات التالية:

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

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

نظرة عامة

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

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

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

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

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

• إنشاء تقرير الملخص: الدفعة التقارير القابلة للتجميع واستخدام خدمة التجميع لمعالجة التقارير لإنشاء تقرير ملخص.

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

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

يمكن أن يكون تقرير المخرجات على النحو التالي:

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

تحدِّد التقارير التي تختارها البيانات التي ستحتاج إلى جمعها.

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

بمجرد أن تقرر ما تريد قياسه، يمكنك إعداد لـ 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 يكون بترميز url لتجنُّب حدوث مشاكل عند استخدام الرموز الخاصة.

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

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

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

   

3. بعد ذلك، يزور المستخدم الموقع الإلكتروني للمعلِن.

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

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

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

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

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

   

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

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

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

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

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

مطابقة المصادر بالعوامل المُشغِّلة

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

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

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

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

جمع البيانات

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

التقارير القابلة للتجميع تُستخدم لإنشاء تقارير موجزة. التقرير القابل للتجميع هو تركيبة من البيانات التي تم جمعها من الإعلان (على الموقع الإلكتروني للناشر) وبيانات الإحالات الناجحة (من موقع المعلن) الذي ينشئه المتصفح ويشفره على جهاز المستخدم قبل أن تجمعها تكنولوجيا الإعلان.

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

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

إنشاء تقرير الملخّص

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

التقارير القابلة للتجميع المجمّعة

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

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

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

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

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

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

يمكن للممارسين إنشاء تقارير مجمعة بنص واضح اختبار خدمة التجميع محليًا. يمكنك بدلاً من ذلك إجراء اختبارات باستخدام التقارير المشفَّرة على AWS باستخدام Nitro Enclaves.

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

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

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

مثل واجهات برمجة تطبيقات "مبادرة حماية الخصوصية" الأخرى، يتم توثيق واجهة برمجة التطبيقات تمت مناقشته بشكل علني

إجراء التجارب باستخدام واجهة برمجة التطبيقات

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