تتيح حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" الآن استخدام الإصدار التجريبي من MRAID v3، استنادًا إلى الدعم الحالي للإصدار MRAID v2، ما يتيح للمعلِنين عرض تصاميم إعلانات MRAID v3 للناشرين في "مدير إعلانات Google". يوضّح هذا الدليل تفاصيل تنفيذ MRAID التي كانت غير واضحة وقابلة للتفسير في مواصفات الإصدار الثالث من MRAID. والجمهور المستهدف هو مؤلفو تصميمات الإعلانات للإصدار الثالث من MRAID.
المتطلبات الأساسية
يجب أن يستخدم الناشرون:
- الإصدار 15.0.0 من "خدمات Google Play" أو إصدار أحدث للإصدار 3 من MRAID
- الإصدار 7.8 من "خدمات Google Play" أو إصدار أحدث للإصدار 2 من MRAID
أدلة تمهيدية مفيدة
إذا لم تكن على دراية بواجهة MRAID، يمكنك الاطّلاع على مزيد من المعلومات في صفحة IAB MRAID. يمكنك أيضًا تنزيل مستند تعريفات الإصدار 3 من MRAID الذي يقدّم تفاصيل عن جميع المَعلمات التي تمت مناقشتها أدناه، بالإضافة إلى منشور مدوّنة IAB حول الإصدار 3 من MRAID.
تفاصيل تنفيذ الإصدار 3 من MRAID (تجريبي)
إمكانية العرض - حدث exposureChange
هذا الحدث متاح وننصح باستخدام أداة معالجة للحدث الجديد exposureChange بدلاً من الحدث viewableChange الذي تم إيقافه نهائيًا.
تم أيضًا إيقاف الطريقة mraid.isViewable() نهائيًا. ومع ذلك، يستمر توفير هذه الطرق المتوقفة نهائيًا للحفاظ على التوافق مع الأنظمة القديمة.
يتم إرسال تعريف الحدث exposureChange كلما تغيّر عرض الإعلان. تتضمّن حزمة تطوير البرامج (SDK) آلية استطلاع لتجنُّب إنشاء عدد كبير جدًا من الأحداث.
يتم إرسال الحالة الأولية بشكل غير متزامن بعد أن يسجّل الإعلان مستمعًا.
تتضمّن دالة ردّ الاتصال المَعلمة exposed_percentage، وهي رقم نقطة عائمة
بين 0.0 و100.0.
يمكنك الرجوع إلى مواصفات الإصدار 3 من MRAID للاطّلاع على نموذج الاستخدام.
رصد MRAID وإعداده وسمات MRAID_ENV
تتوافق حزمة تطوير البرامج (SDK) مع بروتوكول الإعداد كما هو محدّد في مواصفات الإصدار الثالث من MRAID.
في عنصر MRAID_ENV، لا ترسل حزمة SDK كلاً من IDFA وlimitAdTracking ومعرّف التطبيق وقانون حماية خصوصية الأطفال على الإنترنت (COPPA) (وهي اختيارية). وتوفّر جميع المتغيّرات المطلوبة في عنصر MRAID_ENV، بما في ذلك إصدار MRAID واسم حزمة تطوير البرامج (SDK) وإصدارها.
قياس قابلية السماع
تم تقديم حدث جديد (audioVolumeChange) لتحديد ما إذا كان الصوت
مسموعًا ومتى يتغيّر مستوى الصوت.
يحتوي الحدث audioVolumeChange على مَعلمة واحدة: volume_percentage.
القيمة هي النسبة المئوية للحد الأقصى لمستوى صوت تشغيل الصوت. وهو رقم نقطة عائمة يتراوح بين 0.0 و100.0 (0.0 عندما لا يُسمح بالتشغيل) أو null إذا تعذّر تحديد مستوى الصوت.
يمكنك الرجوع إلى مواصفات الإصدار 3 من MRAID للاطّلاع على نموذج الاستخدام.
mraid.getLocation()
بما أنّ السمة mraid.getLocation() غير متاحة، يتم عرض القيمة -1 دائمًا.
mraid.unload()
يمكن استدعاء هذه الطريقة في أي وقت، وتتفاعل حزمة SDK من خلال إغلاق الإعلان وإلغاء تخصيص الموارد، ثم إزالة WebView أو استبداله بمستند آخر أو إعلان جديد.
عندما يستدعي تصميم الإعلان unload()، تستجيب الطبقة المدمجة مع المحتوى على النحو التالي
لأنواع تصميمات الإعلانات المختلفة:
| النوع | سلوك unload() |
|---|---|
| إعلان البانر | أرسِل طلبًا جديدًا لعرض الإعلان باستخدام مَعلمات الطلب نفسها المستخدَمة في الإعلان الحالي. |
| الإعلانات البينية | أغلِق الإعلان البيني. |
معيار دقّة واجهة عرض الإعلانات على مشغّل الفيديو (VPAID)
لا تتوافق حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" مع معيار VPAID. mraid.supports('vpaid')
تُظهر القيمة "خطأ".
mraid.useCustomClose()
قد لا يكون mraid.useCustomClose() متاحًا، وذلك حسب الشكل ونوع تصميم الإعلان.
تفاصيل تنفيذ الإصدار 2 من MRAID
mraid.getVersion()
لا تعرض الدالة mraid.getVersion() القيمة 2.0 إلا بعد تحميل تصميم الإعلان. لا تتحقّق من إصدار MRAID عندما تعرض الدالة mraid.getState() القيمة loading.
mraid.resize()
عند استدعاء mraid.resize()، يتم استبدال البانر الأصلي بصورة لقطة الشاشة للبانر. ويكون ذلك ملحوظًا إذا لم يغطِّ الإعلان
الذي تم تغيير حجمه المساحة الإعلانية الأصلية.
ولا تتبع الإعلانات التي تم تغيير حجمها إطار البانر الأصلي أيضًا. إذا تم وضع إعلان بانر في عرض قابل للتمرير، لا يتم تمرير الإعلان الذي تم تغيير حجمه مع إعلان البانر.
mraid.setResizeProperties()
يجب أن تحتوي جميع الطلبات إلى mraid.setResizeProperties() على قائمة كاملة بالسمات المطلوبة. إذا كانت خصائص تغيير الحجم غير صالحة، ستتم إعادة ضبطها
على الإعدادات التلقائية، وستتعذّر جميع الطلبات اللاحقة إلى mraid.resize() إلى أن
يتم طلب mraid.setResizeProperties() مرة أخرى باستخدام مَعلمات صالحة.
mraid.getMaxSize()
يجب استخدام mraid.getMaxSize() فقط لتحديد الحد الأقصى لحجم الإعلانات التي تم تغيير حجمها. لتحديد حجم إعلان قابل للتوسيع، استخدِم mraid.getScreenSize().
mraid.setOrientationProperties()
عند استدعاء mraid.setOrientationProperties() مع ضبط السمة allowOrientationChange على القيمة true، لن يؤدي ضبط السمة forceOrientation إلى أي إجراء.
يجب أن تضبط تصاميم الإعلانات التي تريد فرض الاتجاه allowOrientationChange على
false.
mraid.isViewable()
إذا كان العرض يغطي إعلانًا مرئيًا، سيظل mraid.isViewable() يعرض
true. يجب ألا يغطي محتوى التطبيق الإعلانات المرئية.
mraid.getCurrentPosition()
عندما يكون الإعلان القابل للتوسيع المكوّن من قطعتين في الحالة الموسّعة، سيؤدي استدعاء
mraid.getCurrentPosition() في القطعة الأولى إلى عرض حجم
الشاشة.
mraid.storePicture()
لكي يتيح التطبيق استخدام ميزة "mraid.storePicture()"، يجب أن يتضمّن إذن
android.permission.WRITE_EXTERNAL_STORAGE.