إتاحة التوسّط في وقت تشغيل حزمة تطوير البرامج (SDK)

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

يوضّح هذا المستند التغييرات الرئيسية في سير عمل التوسّط في حِزم تطوير البرامج (SDK) Runtime. ويتناول هذا الدليل المواضيع التالية:

  • الاختلافات بين عمليات التوسّط السابقة ودعم التوسّط الحالي في وقت التشغيل لـ SDK
  • إعداد الإجراءات لسير عمل التوسّط في "وقت تشغيل حزمة تطوير البرامج (SDK)"، والمراحل المختلفة للتحوّل
  • إرشادات حول كيفية التعامل مع السيناريوهات التي لم يتم فيها نقل جميع حِزم SDK إلى Runtime

تتوفّر ميزة الإعلانات التوسّطية في "وقت تشغيل حزمة تطوير البرامج (SDK)" من AGP 8.5 والإصدارات التالية من مكتبات SDK Runtime Jetpack:

مكتبة Androidx الإصدار
androidx.privacysandbox.activity 1.0.0-alpha01
androidx.privacysandbox.sdkruntime 1.0.0-alpha13
androidx.privacysandbox.tools 1.0.0-alpha08
androidx.privacysandbox.ui 1.0.0-alpha09

مسرد المصطلحات

إنّ المصطلحات التالية هي مفاتيح فهم التوسّط في "وقت تشغيل حزمة تطوير البرامج (SDK)":

  • حزمة SDK المفعَّلة في وقت التشغيل (RE SDK): هي حزمة SDK تم إنشاؤها للتشغيل في بيئة SDK Runtime والتواصل مع التطبيق من خلال ميزة "التواصل بين العمليات" (IPC).
  • حزمة SDK مدركة لوقت التشغيل (RA SDK): هي حزمة SDK غير مفعَّلة في وقت التشغيل، وهي مرتبطة بالتطبيق بشكل ثابت، وقد تحتوي على رمز حزمة SDK الحالي بالإضافة إلى رمز جديد للاستدعاء إلى حزمة SDK مفعَّلة في وقت التشغيل.
  • حزمة SDK داخل التطبيق: هي حزمة SDK يتم تشغيلها مرتبطة بالتطبيق بشكل ثابت، ولا تتمكّن من معرفة وقت تشغيل حزمة SDK. قد تكون هذه شبكة مواقع إعلانية لم يتم نقلها إلى SDK Runtime أو محوِّل مخصّص للناشر.
  • الوسيط: حزمة تطوير برامج التوسّط الإعلاني التي توفّر خدمة توسّط على الجهاز من خلال التفاعل مع حِزم تطوير برامج شبكات الإعلانات الأخرى
  • Mediatee: حزمة تطوير البرامج (SDK) لشبكة المواقع الإعلانية التي يستدعيها الوسيط لتوفير إعلان و عرضه.
  • محوِّل التوسّط: حِزم SDK التي تستخدمها حزمة SDK للتوسّط من أجل توفير ترجمة واجهة برمجة التطبيقات لإمكانية التفاعل مع حِزم SDK المختلفة التي توفّرها الجهة التوسّطة ويمكن أن تكون هذه الوظائف على دراية بوقت التشغيل أو غير مدركة له.

مسارات التوسّط المعتادة

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

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

نظرًا للاختلاف في عمليات تنفيذ عملية التوسّط، نركّز على العمليتين الرئيسيتَين التاليتَين:

  • الإعداد (بما في ذلك اكتشاف شبكات الإعلانات والتواصل)
  • عرض واجهة مستخدِم الإعلان (UI)

الإعداد

يمثّل ما يلي عملية إعداد عادية واكتشاف شبكة إعلانية و مسار تواصل:

  1. يبدأ تطبيق العميل الوسيط
  2. يرصد الوسيط العناصر الوسيطة والمحوِّلات ذات الصلة ويُنشئها.
  3. يستخدم الوسيط محوِّلاته للتواصل مع كل وسيط.
  4. يطلب تطبيق العميل من الوسيط تحميل إعلان.
  5. يطلب تطبيق العميل من الوسيط عرض هذا الإعلان.

عرض واجهة المستخدم للإعلان

في ما يتعلّق بعرض الإعلان بعد الطلب النهائي في الخطوة السابقة، يعتمد المسار على نوع الإعلان:

إعلانات البانر الإعلانات بملء الشاشة الإعلانات المدمجة مع المحتوى
تنشئ حزمة SDK للوسيط عرض إعلان يُغلِّف عرض إعلان الوسيط الفائز.

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

عمليات التوسّط في وقت تشغيل حزمة تطوير البرامج (SDK)

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

  • يتوفّر كلّ من الوسيط والوسيط المعنيّ في وقت تشغيل حزمة تطوير البرامج (SDK): RE mediatee
  • يكون الوسيط في "وقت تشغيل حزمة SDK"، ويكون الوسيط داخل التطبيق: الوسيط داخل التطبيق

RE Mediatee

يعرض مخطّط المخطّط البياني التالي نظرة عامة عالية المستوى على التفاعل بين حِزم تطوير البرامج (SDK) المتوافقة مع وقت التشغيل (RE) وتلك المتوافقة مع وقت التشغيل (RA) الخاصة بالوسيط، ومحوِّلات التوسّط المتوافقة مع وقت التشغيل وحِزم تطوير البرامج (SDK) المتوافقة مع وقت التشغيل الخاصة بالوسطاء.

يجب أن تكون محوِّلات التوسّط في العملية نفسها التي يتفاعل معها الوسيط، لذا سيكون عليهم أيضًا نقل البيانات إلى SDK Runtime.

مخطّط بياني للبنية يعرض نظرة عامة عالية المستوى على تفاعل حِزم تطوير البرامج (SDK) المتوافقة مع وقت التشغيل (RE) وتلك المتوافقة مع وقت التشغيل (RA) الخاصة بالوسيط، ومحوِّلات التوسّط المتوافقة مع وقت التشغيل، وحِزم SDK المتوافقة مع وقت التشغيل الخاصة بالوسطاء
الشكل 1. كلّ من الوسيط والوسيط هو حزمة تطوير برامج (SDK) لتكنولوجيا الواقع المعزّز.

الإعداد

عند النظر في عملية الإعداد والاكتشاف والتواصل لكلٍّ من الوسيط المفعَّل في وقت التشغيل والوسيط، ستتّبع العملية الخطوات التالية:

  1. يحمِّل التطبيق (أو حزمة تطوير البرامج لعرض الإعلانات المتجاوبة) حزمة تطوير البرامج الوسيطة ويُعدّها باستخدام SdkSandboxManager#loadSdk.
  2. أثناء إعداد حزمة SDK الوسيطة، تحمّل هذه الحزمة أيّ وسائط مطلوبة في "وقت تشغيل حزمة SDK" وتبدأ إعدادها باستخدام SdkSandboxController#loadSdk.
  3. يمكن لحزمة RE SDK اكتشاف جميع حِزم SDK المحمَّلة في وقت التشغيل من خلال استدعاء SdkSandboxController#getSandboxedSdks.
RE - مخطّط تسلسل التوسّط في RE يعرض المسار الموضّح سابقًا
الشكل 2. عملية إعداد وسيط إعادة التوجيه

عرض واجهة المستخدم للإعلان

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

إعلانات البانر في RE Mediatee

في حال تلقّي طلب من التطبيق لتحميل إعلان بانر، يكون المسار لإكمال العرض على النحو التالي:

  1. يختار الوسيط المساحة الإعلانية الفائزة لهذا الإعلان.
  2. يحصل الوسيط على SandboxedUiAdapter من الطرف المعنيّ بالتوسّط.
  3. يعيد الوسيط توجيه UiAdapter إلى التطبيق.
مسار إكمال عرض إعلان بانر في التوسّط من النوع RE-RE
الشكل 3. مسار إكمال عرض بانر من وسيط إعادة التوجيه

مزيد من المعلومات حول استخدام SandboxedUiAdapter و"مكتبة واجهة المستخدم لوقت تشغيل حزمة تطوير البرامج (SDK)"

الإعلانات التي تظهر على سطح الفيديو في إعلانات البانر

إذا أراد التوسّطون إضافة تراكب إلى الإعلان، عليهم تعديل العملية على النحو التالي:

  1. ينشئ الوسيط تنسيقًا يتضمّن المحتوى المركّب وSandboxedSdkView.
  2. يختار الوسيط المساحة الإعلانية الفائزة لهذا الإعلان.
  3. يحصل الوسيط على SandboxedUiAdapter من الطرف المعنيّ بالتوسّط.
  4. يضبط الوسيط UiAdapter للوسيط على SandboxedSdkView.
  5. يشارك الوسيط العرض المعبّأ مع التطبيق.
مسار لعرض إعلان بانر تم الحصول عليه من RE Mediatee على سطح الفيديو
مسار تراكيب العرض على إعلان بانر تم الحصول عليه من وسيط إعادة الشراء
إعلانات RE Mediatee بملء الشاشة

عند تلقّي طلب من التطبيق لتحميل إعلان بملء الشاشة، تتّبع العملية الخطوات التالية:

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

مزيد من المعلومات عن إتاحة النشاط للإعلانات على الشاشة الكاملة في وقت تشغيل حزمة تطوير البرامج (SDK)

Mediatee داخل التطبيق

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

مخطّط بياني للبنية يعرض نظرة عامة على مستوى عالٍ على تفاعل حِزم SDK لعرض الإعلانات والإعلانات الديناميكية للوسيط، ومحوِّلات التوسّط التي لا تعرف وقت تشغيل حزمة SDK، وحِزم SDK للوسطاء المرتبطة بشكل ثابت بالتطبيق (التي لا تعرف وقت التشغيل أيضًا).
الشكل 5. يكون الوسيط مرتبطًا بشكل ثابت بالتطبيق، حتى إذا كان على دراية بحزمة RE SDK.

الإعداد

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

من المفترض أن يكون بالإمكان الوصول إلى عملية التسجيل هذه باستخدام واجهة برمجة تطبيقات الوسيط، ولكن يتم تحديد تفاصيل التنفيذ وفقًا لتقدير كل وسيط. نُطلِق على واجهة برمجة التطبيقات هذه اسم MediationSandboxedSdk#registerInAppMediatee.

عند التفكير في عملية إعداد حزمة تطوير البرامج (SDK) لوسيط إعادة التوجيه واكتشافها والتواصل معها، بالإضافة إلى حِزم تطوير البرامج (SDK) للوسيط داخل التطبيق، سيتّبع المسار الخطوات التالية:

  1. يحمِّل التطبيق حزمة تطوير البرامج (SDK) المتوافقة مع وقت التشغيل الخاصة بالوسيط ويُعدّها.
  2. حزمة تطوير البرامج (SDK) لواقع معزّز لدى التوسّط:
    1. يبدأ الوسيط حزمة تطوير البرامج (SDK) لإعادة التفاعل باستخدام SdkSandboxManager#loadSdk.
    2. لإعداد جميع حِزم تطوير البرامج (SDK) للوسطاء داخل التطبيق
    3. رصد حِزم SDK الوسيطة داخل التطبيق وتسجيلها باستخدام واجهة برمجة التطبيقات التي يوفّرهاMediationSandboxedSdk#registerInAppMediate، حزمة SDK لإعادة الشراء

بالإضافة إلى تسجيل جميع حِزم SDK للوسيط داخل التطبيق، يمكن لحزمة RE SDK الخاصة بالوسيط اكتشاف جميع حِزم SDK المحمَّلة في وقت تشغيل حزمة SDK باستخدام SdkSandboxController#getSandboxedSdks.

تسلسل يوضّح الخطوات الموضّحة لبدء عملية التوسّط داخل التطبيق
الشكل 6. يُرجى العلم أنّنا نستخدم واجهة برمجة التطبيقات الخاصة بالوسيط المقترَح لتسجيل الإشارة إلى الوسطاء داخل التطبيق.

عرض واجهة المستخدم للإعلان

يتناول القسم التالي تحميل إعلانات البانر والإعلانات بملء الشاشة من ملف وسائط داخل التطبيق.

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

في حال تلقّي طلب من التطبيق لتحميل إعلان بانر، يكون المسار لإكمال العرض على النحو التالي:

  1. تعيد توجيه حزمة SDK المتوافقة مع وقت التشغيل في التوسّط طلب التطبيق إلى حزمة SDK المتوافقة مع وقت التشغيل.
  2. تختار حزمة RE SDK الخاصة بالوسيط الوسيط ذي الصلة.
  3. تسترجع حزمة تطوير البرامج (SDK) لعرض الإعلانات على الشبكة الإعلانية (RE) الإشارة إلى الوسيط، وتطلب تحميل إعلان من خلال حزمة تطوير البرامج (SDK) لعرض الإعلانات على الشبكة الإعلانية (RA).
  4. تحصل حزمة تطوير البرامج (SDK) لعرض الإعلانات أثناء التشغيل على عرض من الوسيط داخل التطبيق.
  5. تنشئ حزمة تطوير البرامج (SDK) لعرض الإعلانات أثناء التشغيل ملفًا شخصيًا بعنوان SandboxedUiAdapter للعرض الذي تلقّته.
  6. تعيد توجيه حزمة تطوير البرامج (SDK) لعرض الإعلانات على شبكة البحث UiAdapter إلى حزمة تطوير البرامج (SDK) لعرض الإعلانات على شبكة Google الإعلانية.
  7. تعيد توجيه حزمة تطوير البرامج (SDK) لتطبيق RealEstate UiAdapter إلى التطبيق.
مسار إكمال عرض إعلانات البانر من وسيط داخل التطبيق
الشكل 7. يُرجى العلم أنّ الوسيط يجب ألا يضيف مشاهدات على V1 عند الحصول عليها من وسيط داخل التطبيق.
الإعلانات بملء الشاشة التي تتمّ التوسّط فيها داخل التطبيق

عند تلقّي طلب من التطبيق لتحميل إعلان بملء الشاشة، يتم اتّباع الخطوات التالية:

  1. يُرسِل التطبيق SdkActivityLauncher إلى حزمة تطوير البرامج (SDK) لعرض الإعلانات التابعة للوسيط مع طلب تحميل إعلان.
    1. يمكن للعميل تقييد إنشاء الأنشطة باستخدام تعبير وصفي.
  2. تعيد توجيه حزمة تطوير البرامج (SDK) لعرض الإعلانات على الشبكة الإعلانية (RA) التابعة للوسيط طلب التطبيق إلى حزمة تطوير البرامج (SDK) لعرض الإعلانات على الشبكة الإعلانية (RE).
  3. حزمة تطوير البرامج (SDK) لإعادة التوجيه الخاصة بالوسيط:
    1. اختيار الوسيط ذي الصلة
    2. يسترجع هذا الإجراء الإشارة إلى الوسيط داخل التطبيق.
    3. طلبات لتحميل إعلان من خلال حزمة تطوير البرامج (SDK) لعرض الإعلانات.
  4. تطلب حزمة تطوير البرامج (SDK) لعرض الإعلانات من الوسيط تحميل إعلان.
  5. يبدأ الوسيط النشاط مباشرةً. لن يتم الالتزام بعبارة التطبيق.
مسار تحميل الإعلانات بملء الشاشة عندما يكون الوسيط في عملية التطبيق
الشكل 8. سيتجاهل الوسيط داخل التطبيق العبارة.

التفاعل مع الملاحظات ومشاركتها

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