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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

تسمح واجهة برمجة التطبيقات 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 لتجنّب حدوث مشاكل في الأحرف الخاصة.

   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.

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

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

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

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

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

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