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

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

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

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

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

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

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

مخطط سير عمل دمج الإحالة

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

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

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

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

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

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

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

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

قبل الدمج

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

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

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

  1. حدِّد موعد مناقشة مع أبرز شركاء القياس لديك لمناقشة اختبار واستخدام Attribution Reporting API. يمكن أن يشمل شركاء القياس شبكات تكنولوجيا الإعلان أو أنظمة وسيط عرض الإعلان (SSP) أو أنظمة وسيط عرض الطلب (DSP) أو المعلنين أو أي شريك آخر تعمل معه حاليًا أو تريد العمل معه.
  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. اقرأ spec المتعلّقة بكيفية تنسيق بيانات الإحالات الناجحة لتكون متوافقة مع أداة إنشاء التقارير التي تمّت محاكاتها.
  3. صمم مفاتيح التجميع وفقًا لمتطلبات العمل.
    • وتشمل الاعتبارات المهمة ما يلي:
      • ضع في اعتبارك الأبعاد المهمة التي يحتاجها عملاؤك أو شركاؤك لتجميع تقييمك وتركيزه عليها.
      • حدِّد الحد الأدنى لعدد السمات المجمّعة والأعداد الأساسية اللازمة لمتطلباتك.
      • تأكد من أن الأجزاء الرئيسية من جهة المصدر ومن جهة المشغِّل لا تتجاوز 128 بت.
      • إذا كانت حلولك تتضمن المساهمة في قيم متعددة لكل حدث مشغِّل، فتأكد من قياس القيم وفقًا لميزانية الحد الأقصى للمساهمة، المستوى 1. سيساعد ذلك في تقليل تأثير الضوضاء.
      • في ما يلي مثال يوضح بالتفصيل ضبط مفتاح لجمع أعداد الإحالات الناجحة المجمَّعة على مستوى الحملة، ومفتاح لجمع قيم عمليات الشراء المجمّعة على المستوى الجغرافي.
  4. شغِّل أداة إنشاء التقارير لإنشاء الأحداث والتقارير القابلة للتجميع.
  5. تشغيل التقارير التجميعية من خلال خوادم التجميع التي تمت محاكاتها للحصول على تقارير ملخصة
  6. نفِّذ تجارب للخدمات:
    • قارِن إجماليات الإحالات الناجحة من التقارير على مستوى الحدث والتقارير التلخيصية ببيانات الإحالات الناجحة السابقة لتحديد دقة إعداد تقارير الإحالات الناجحة. للحصول على أفضل النتائج، نفِّذ اختبارات ومقارنات إعداد التقارير على جزء كبير وممثِّل من قاعدة المعلِنين.
    • أعِد تدريب النماذج استنادًا إلى بيانات التقارير على مستوى الحدث، وربما بيانات التقرير الموجزة. قارن الدقة مع النماذج المبنية على بيانات التدريب التاريخية.
    • جرِّب استراتيجيات مختلفة لتجميع البيانات واعرف مدى تأثيرها على النتائج.
      • تشمل الاعتبارات الحرجة ما يلي:
      • توقيت تقديم التقارير الموجزة لتعديل عروض الأسعار.
      • متوسط معدّل تكرار الأحداث المنسوبة على الجهاز على سبيل المثال، يعود المستخدمون غير النشطين استنادًا إلى بيانات أحداث الشراء السابقة.
      • مستوى الضوضاء يعني المزيد من الدفعات تجميعًا أصغر، يعني التجميع الأصغر تطبيق المزيد من التشويش.

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

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

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

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

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

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

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

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

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

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

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

العمل مع MMP وغيرها

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

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

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