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

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

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

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

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

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

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

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

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

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

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

إعداد تطبيق العيّنة واختباره

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) أو تطبيقك لتسجيل أحداث الإحالات الناجحة.
   • تشمل الاعتبارات المهمة ما يلي:
     • تحديد بيانات المشغّل مع مراعاة دقة البيانات المحدودة التي يتم عرضها: كيف ستحدّ من عدد أنواع الإحالات الناجحة التي يحتاجها المعلِنون من أجل الاستفادة من 3 بتات متاحة للنقرات وبت واحد متاح للمشاهدات؟
     • القيود المفروضة على المشغّلات المتاحة في تقارير الأحداث: كيف تخطّط لتقليل إجمالي عدد الإحالات الناجحة لكل مصدر يمكنك تلقّيه في تقارير الأحداث؟
   • تشمل الاعتبارات الاختيارية ما يلي:
     • تجنَّب إنشاء مفاتيح إزالة التكرار إلى أن تجري اختبارات الدقة.
     • تخطَّ إنشاء مفاتيح وقيم التجميع إلى أن تصبح ميزة اختبار المحاكاة جاهزة.
     • تخطَّ عمليات إعادة التوجيه إلى أن تحدّد طريقة العمل مع شركاء القياس الآخرين.
     • لا تُعدّ أولوية المشغّل ضرورية للاختبار.
     • من المحتمل أن يتم تجاهل الفلاتر عند إجراء الاختبار الأولي.
4. اختبِر أنّه يتم إنشاء أحداث المصدر للإعلانات، وأنّ المشغّلات تؤدي إلى إنشاء تقارير الأحداث.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

العمل مع منصات قياس الأداء على الأجهزة الجوّالة وغيرها

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

العمل باستخدام ميزة القياس على عدّة منصات

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