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

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

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

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

تتوفّر إمكانية استخدام "الإعلانات المستندة إلى التوسّط" في "وقت تشغيل حزمة تطوير البرامج" (SDK Runtime) بدءًا من الإصدار 8.5 من "مكوّن Android الإضافي في Gradle" ومن إصدارات مكتبات 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 Runtime:

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

مسارات التوسّط النموذجية

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

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

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

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

الإعداد

في ما يلي تمثيل لعملية تهيئة عادية واكتشاف شبكة إعلانية وتدفّق الاتصال:

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

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

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

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

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

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

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

RE Mediatee

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

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

الإعداد

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

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

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

يتناول القسم التالي كيفية تحميل إعلانات البانر والإعلانات بملء الشاشة من وسيط RE mediatee.

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

عندما يطلب التطبيق تحميل "إعلان بانر"، تكون خطوات إكمال العرض كما يلي:

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

مزيد من المعلومات حول استخدام SandboxedUiAdapter ومكتبة واجهة مستخدم SDK Runtime

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

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

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

RE Mediatee full-screen ads

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

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

مزيد من المعلومات عن إتاحة الأنشطة للإعلانات بملء الشاشة في بيئة SDK Runtime

In-app Mediatee

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

الإعداد

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

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

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

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

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

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

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

إعلانات البانر على منصة mediatee داخل التطبيق

عندما يطلب التطبيق تحميل "إعلان بانر"، تكون خطوات إكمال العرض كما يلي:

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

إعلانات ملء الشاشة على منصة Mediatee داخل التطبيق

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

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

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

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