Attribution Reporting API: دليل الدمج

الإصدار التجريبي للمطوّرين الإصدار التجريبي

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

---

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

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

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

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

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

الشكل 1: سير عمل دمج تحديد المصدر

المتطلّبات الأساسية والإعداد

أكمِل الخطوات الواردة في هذا القسم لتحسين فهمك لواجهة برمجة التطبيقات Attribution Reporting API. ستساعدك هذه الخطوات في جمع نتائج مفيدة عند استخدام واجهة برمجة التطبيقات في منظومة تكنولوجيا الإعلان المتكاملة.

التعرّف على واجهة برمجة التطبيقات

1. اطّلِع على اقتراح التصميم للتعرّف على Attribution Reporting API وإمكاناتها.
2. اطّلِع على دليل المطوّر للتعرّف على كيفية دمج الرموز البرمجية وطلبات واجهة برمجة التطبيقات التي ستحتاج إليها لحالات الاستخدام.
3. اشترِك لتلقّي آخر الأخبار حول واجهة برمجة التطبيقات لتقارير تحديد المصدر. سيساعدك ذلك في الاطّلاع على الميزات الجديدة التي يتم طرحها في الإصدارات القادمة.

إعداد نموذج التطبيق واختباره

1. بعد أن تصبح مستعدًا لبدء عملية الدمج، يمكنك البدء باستخدام أحدث إصدار من "معاينة المطوّر" في "استوديو Android".
2. إعداد نقاط نهاية الخادم النموذجي لتسجيلات الأحداث وإرسال التقارير لقد قدّمنا نماذج يمكنك استخدامها مع الأدوات المتاحة على الإنترنت.
3. نزِّل الرمز وشغِّله في نموذج التطبيق للتعرّف على تسجيل المصادر وعوامل التفعيل.
1. اضبط الفترة الزمنية لإرسال التقارير. تتيح واجهة برمجة التطبيقات فترات تبلغ يومَين أو 7 أيام أو فترة مخصّصة تتراوح بين يومَين و30 يومًا.
2. بعد تسجيل المصادر وعوامل التشغيل من خلال تشغيل ملف برمجي نموذجي واستخدامه، والتحقّق من انقضاء الفترة الزمنية المحدّدة، تأكَّد من أنّك تلقّيت تقريرًا على مستوى الحدث وتقريرًا مشفّرًا قابلاً للتجميع. إذا كنت تحتاج إلى تصحيح أخطاء التقارير، يمكنك إنشاؤها بسرعة أكبر من خلال تنفيذ مهام إعداد التقارير بشكلٍ قسري.
3. راجِع نتائج تحديد المصدر من تطبيق إلى آخر. تأكَّد من أنّ البيانات الواردة في هذه النتائج على النحو المتوقّع لكلّ من حالات نقطة الاتصال الأخيرة وحالات ما بعد التثبيت.
4. بعد التعرّف على طريقة عمل واجهة برمجة التطبيقات للعميل والخادم معًا، استخدِم نموذج التطبيق كمثال لإرشادك في عملية الدمج. يمكنك إعداد خادم الإنتاج الخاص بك وإضافة طلبات تسجيل الأحداث إلى تطبيقاتك.

مرحلة ما قبل الدمج

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

تفاعل الشركاء

غالبًا ما ينشئ شركاء تكنولوجيا الإعلان (MMP/SSP/DSP) حلول تحديد مصدر مدمجة. تساعدك الخطوات الواردة في هذا القسم على الاستعداد لتحقيق النجاح في التفاعل مع شركاء تكنولوجيا الإعلان.

1. حدِّد موعدًا لمناقشة مع أهم شركاء القياس لمناقشة اختبار واجهة برمجة التطبيقات Attribution Reporting API واستخدامها. يمكن أن تشمل شركاء القياس شبكات تكنولوجيا الإعلان أو منصّات عرض الإعلانات أو منصّات إدارة الأداء أو المعلِنين أو أي شريك آخر تتعامل معه حاليًا أو تريد التعامل معه.
2. تعاون مع شركاء القياس لتحديد المخططات الزمنية لتكامل الميزة، بدءًا من الاختبار الأولي إلى الاستخدام.
3. حدِّد مع شركاء القياس المجالات التي سيغطيها كلّ منكما في تصميم عملية تحديد المصدر.
4. أنشئ قنوات اتصال بين شركاء القياس لمزامنة المخططات الزمنية والاختبارات الشاملة.
5. تصميم عمليات تدفق البيانات على مستوى عالٍ بين شركاء القياس تشمل الاعتبارات الرئيسية ما يلي:
   • كيف سيسجّل شركاء القياس مصادر الإحالة باستخدام واجهة برمجة التطبيقات Attribution Reporting API؟
   • كيف ستسجِّل شبكات تكنولوجيا الإعلان عوامل التفعيل باستخدام واجهة برمجة التطبيقات Attribution Reporting API؟
   • كيف ستتحقّق كل تقنية إعلان من طلبات واجهة برمجة التطبيقات وتُرسل الردود اللازمة لإكمال عمليات تسجيل المصادر وإجراءات التفعيل؟
   • هل هناك أي تقارير يجب مشاركتها مع الشركاء خارج Attribution Reporting API؟
   • هل هناك أي نقاط دمج أو توافق أخرى مطلوبة على مستوى الشركاء؟ على سبيل المثال، هل تحتاج أنت وشركاؤك إلى العمل على إزالة تكرار الإحالات الناجحة، أو المواءمة مع مفاتيح التجميع؟
6. إذا كان تحديد مصدر الإحالات الناجحة من التطبيق إلى الموقع الإلكتروني منطبقًا، يمكنك تحديد موعد لمناقشة مع شركاء القياس على الويب لمناقشة تصميم واختبار واستخدام واجهة برمجة التطبيقات Attribution Reporting API. يمكنك الرجوع إلى الأسئلة الواردة في الخطوة السابقة عند بدء محادثات مع شركاء الويب.

النموذج الأولي لتحديد المصدر على مستوى الحدث من تطبيق إلى آخر

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

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

اختبار المحاكاة

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

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

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

1. إعداد "مكتبة محاكاة القياس" على جهاز محلي
2. اطّلِع على المواصفات المتعلّقة بكيفية تنسيق بيانات إحالاتك الناجحة لتكون متوافقة مع أداة إنشاء التقارير المحاكية.
3. تصميم مفاتيح التجميع استنادًا إلى متطلبات النشاط التجاري
   • تشمل الاعتبارات المهمة ما يلي:
     • ننصحك بالتركيز على السمات المهمة التي يحتاجها عملاؤك أو شركاؤك لجمعها وتقييمها.
     • حدِّد الحد الأدنى لعدد السمات المجمّعة وعدد القيم الفريدة لسمة معيّنة المطلوب لتلبية متطلباتك.
     • تأكَّد من أنّ أجزاء المفتاح من جهة المصدر والجانب المشغِّل لا تتجاوز 128 بت.
     • إذا كانت حلولك تساهم في قيم متعدّدة لكل بدء حدث، احرص على توسيع نطاق القيم وفقًا لميزانية المساهمين القصوى ، أي المستوى 1. سيساعد ذلك في تقليل تأثير الضوضاء.
     • في ما يلي مثال يوضّح تفاصيل ضبط مفتاح لجمع أعدَد الإحالات الناجحة المُجمّعة على مستوى الحملة، ومفتاح لجمع قيم عمليات الشراء المُجمّعة على مستوى الموقع الجغرافي.
4. شغِّل أداة إنشاء التقارير لإنشاء تقارير عن الأحداث والتقارير القابلة للتجميع.
5. يمكنك تشغيل التقارير القابلة للتجميع من خلال خوادم التجميع المحاكية للحصول على تقارير موجزة.
6. إجراء تجارب أدوات:
   • قارِن إجماليات الإحالات الناجحة من التقارير على مستوى الحدث والتقارير التلخيصية مع بيانات الإحالات الناجحة السابقة لتحديد دقة إعداد تقارير الإحالات الناجحة. للحصول على أفضل النتائج، عليك إجراء اختبارات إعداد التقارير والمقارنات على جزء واسع وممثّل من قاعدة المعلِنين.
   • أعِد تدريب نماذجك استنادًا إلى بيانات التقارير على مستوى الحدث، وربما بيانات التقارير التلخيصية. مقارنة الدقة بالنماذج التي تم إنشاؤها استنادًا إلى data التدريب السابقة
   • جرِّب استراتيجيات مختلفة لتجميع المحتوى ولاحظ تأثيرها في النتائج.
     • تشمل الاعتبارات المهمة ما يلي:
     • توقيت نشر التقارير التلخيصية لتعديل عروض الأسعار
     • متوسّط معدّلات تكرار الأحداث التي يمكن تحديد مصدرها على الجهاز على سبيل المثال، المستخدمون الذين توقّفوا عن استخدام التطبيق ثم عادوا استنادًا إلى بيانات أحداث الشراء السابقة.
     • مستوى الضوضاء كلما زاد عدد الدفعات، قلّ حجم التجميع، وكلما قلّ حجم التجميع، زادت التشويشات.

تحديد مصدر خادم تجميع النماذج الأولية: الإعداد

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

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

تحديد مصدر خادم تجميع النماذج الأولية: الدمج

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

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

تكرار التصميم باستخدام ميزات اختيارية

في ما يلي ميزات إضافية يمكنك تضمينها في حلول القياس.

استخدام Debug API لإنشاء مفاتيح تصحيح الأخطاء (إجراء يُنصح به بشدة)

ملاحظة: ستتوفّر هذه الميزة في الإصدار التجريبي المفتوح.

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

تخصيص سلوكيات تحديد المصدر

1. تحديد المصدر لعوامل تشغيل ما بعد التثبيت
   • يمكن استخدام هذه الميزة في حال كان يجب تحديد مصدر تحديد المصدر نفسه الذي أدّى إلى عملية التثبيت لتحديد مصدر بدء التفاعلات التي حدثت بعد التثبيت، حتى إذا كانت هناك مصادر تحديد مصدر أخرى مؤهّلة حدثت مؤخرًا.
   • على سبيل المثال، قد ينقر أحد المستخدِمين على إعلان يؤدّي إلى تسجيل عملية تثبيت. بعد التثبيت، ينقر المستخدم على إعلان آخر ويُجري عملية شراء. في هذه الحالة، قد تريد شركة تكنولوجيا الإعلان أن تُنسَب عملية الشراء إلى النقرة الأولى بدلاً من النقرة التي أدّت إلى إعادة التفاعل.
2. استخدام الفلاتر لتحسين البيانات في تقاريرك على مستوى الحدث
   • يمكن ضبط فلاتر الإحالات الناجحة لتجاهل عوامل التشغيل المحدّدة واستبعادها من تقارير الأحداث. بسبب الحدود المفروضة على عدد عوامل التفعيل لكل مصدر تحديد المصدر، تسمح لك الفلاتر بتضمين عوامل التفعيل فقط التي تقدّم المعلومات الأكثر فائدة في تقارير الأحداث.
   • يمكن أيضًا استخدام الفلاتر لفلترة بعض عوامل التفعيل بشكل انتقائي، وبالتالي تجاهلها بفعالية. على سبيل المثال، إذا كانت لديك حملة تستهدف تثبيتات التطبيق، قد تحتاج إلى فلترة عوامل التفعيل بعد التثبيت كي لا يتم تحديد مصدرها على أنّه من تلك الحملة.
   • يمكن أيضًا استخدام الفلاتر لتخصيص بيانات العوامل المشغِّلة استنادًا إلى بيانات المصدر. على سبيل المثال، يمكن أن يحدّد المصدر "product" : ["1234"] حيث يكون product هو مفتاح الفلتر و1234 هي القيمة. يتم تجاهل أيّ عامل تشغيل يحتوي على مفتاح فلتر هو "product" وقيمة غير "1234".
3. أولوية المصدر والعامل المشغِّل المخصّصة
   • في حال إمكانية ربط مصادر تحديد مصدر متعددة بأحد المشغّلات، أو إمكانية تحديد مصدر إحالة ناجحة لعدة مشغّلات، يمكنك استخدام عدد تكاملي موقَّع 64 بت لمنح الأولوية لتحديدات مصدر/مشغّل معيّنة على غيرها.

العمل مع منصّات إدارة الأداء (MMP) وغيرها

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

العمل مع ميزة القياس على جميع المنصات

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