تفعيل تصميمات الإعلانات المستندة إلى JavaScript في VPAID 2
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتوافق حزمة تطوير البرامج لإعلانات الوسائط التفاعلية بتنسيق HTML5 مع تصاميم JavaScript الإبداعية المتوافقة مع VPAID 2. عند تفعيل التوافق، يجب الانتباه إلى اختلافَين رئيسيَّين بين مواصفات VPAID 2 والطريقة التي تتيح بها "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" استخدام VPAID 2. لا تؤثّر هذه الاختلافات في الرمز البرمجي لتنفيذ المشغّل أو حزمة تطوير البرامج (SDK)، ولكنّها مهمة لمؤلفي مواد عرض JavaScript المتوافقة مع معيار VPAID 2، لأنّ مواد العرض قد تعرض أخطاء أو لا تعمل على النحو المتوقّع عند عرضها باستخدام حزمة تطوير البرامج HTML5 لإعلانات الوسائط التفاعلية.
المتطلبات الأساسية
لمتابعة هذا الدليل، ابدأ بتطبيق يتضمّن ما يلي:
مقدمات مفيدة
- إذا لم تكن على دراية بإصدار VPAID 2، يمكنك الاطّلاع على مزيد من المعلومات في صفحة IAB VPAID.
تفعيل التوافق مع الإصدار 2 من VPAID
لتفعيل توافق VPAID 2 JavaScript، استدعِ الطريقة التالية قبل تهيئة AdDisplayContainer:
google.ima.settings.setVpaidMode(google.ima.ImaSdkSettings.VpaidMode.ENABLED);
...
var adDisplayContainer = new google.ima.AdDisplayContainer(adContainerElement);
var adsLoader = new google.ima.AdsLoader(adDisplayContainer);
...
في ما يلي أوضاع VPAID المتاحة:
ENABLED: يسمح بعرض إعلانات VPAID باستخدام الإعدادات التلقائية.-
INSECURE: يسمح بعرض إعلانات VPAID في الوضع غير الآمن. لمزيد من المعلومات، يُرجى الاطّلاع على أمان إطارات iframe وعنصر وكيل مشغّل الفيديو.
DISABLED - لا يتم تشغيل إعلانات VPAID. إذا عرض إعلان مطلوب تصميم إعلان VPAID، سيظهر خطأ.
لمزيد من المعلومات حول أوضاع VPAID، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات الخاصة بـ
ImaSdkSettings.VpaidMode.
ملاحظات حول توافق الإصدار 2 من VPAID
أمان إطار IFrame
تستخدم حزمة تطوير البرامج للإعلانات التفاعلية من Google تلقائيًا إطار iframe آمنًا بدلاً من إطار iframe سهل الاستخدام (النطاق نفسه) أو نص برمجي داخل الصفحة لعرض مواد عرض JavaScript بتنسيق VPAID 2.
وهذا يعني أنّه إذا كان تصميم الإعلان يتوقّع الوصول إلى نموذج المستند الخاص بالصفحة الرئيسية، قد يؤدي ذلك إلى حدوث خطأ. لعرض إعلانك في إطار iframe صديق بدلاً من ذلك، يمكنك استخدام ImaSdkSettings.setVpaidMode(...) على النحو التالي:
adsLoader.getSettings().setVpaidMode(google.ima.ImaSdkSettings.VpaidMode.INSECURE);
عنصر وكيل مشغّل الفيديو
لضمان الأمان والوظائف السليمة على الأجهزة الجوّالة، لا توفّر حزمة تطوير البرامج لإعلانات الوسائط التفاعلية بتنسيق HTML5 في وضع ENABLED عنصر الفيديو الفعلي للإعلان، بل توفّر عنصرًا وكيلاً يحاكي معظم وظائف عنصر الفيديو العادي.
بالنسبة إلى تصاميم الإعلانات التي تستدعي طرق واجهة برمجة التطبيقات المتوافقة فقط، لن تحدث أي تغييرات في سلوك عرض تصاميم الإعلانات. في وضع VpaidMode.INSECURE، توفّر حزمة SDK عنصر مشغّل الفيديو بدلاً من الخادم الوكيل.
في ما يلي الطرق والمعالجات والسمات المتاحة في عنصر وكيل الفيديو:
الطُرق
addEventListenercanPlayTypeloadplaypausesetattribute
أنواع الأحداث في addEventListener
abortcanplaycanplaythroughclickdurationchangeemptiedendederrorloadeddataloadedmetadataloadstartpauseplayplayingprogressratechangesuspendseekedseekingtimeupdatewaiting
السمات
currentTimedurationendedpausedplaybackRatesrctype
الأسئلة الشائعة
- هل تتوافق مواد عرض JavaScript الإبداعية VPAID 2 مع حِزم تطوير البرامج (SDK) لنظام التشغيل iOS أو Android؟
-
أداة تطوير البرامج لإعلانات الوسائط التفاعلية بتنسيق HTML5 هي منصة أداة تطوير البرامج الوحيدة لإعلانات الوسائط التفاعلية التي تتوافق مع مواد عرض JavaScript الإبداعية المتوافقة مع معيار دقّة واجهة عرض الإعلانات على مشغّل الفيديو 2 (VPAID 2).
- هل يؤدي ذلك إلى تفعيل تصاميم إعلانات VPAID في حزمة IMA HTML5 SDK؟
- نعم، تتوافق حزمة تطوير البرامج HTML5 لإعلانات الوسائط التفاعلية مع تصميمات JavaScript الإبداعية المتوافقة مع معيار دقّة واجهة عرض الإعلانات على مشغّل الفيديو 2.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe IMA HTML5 SDK supports VPAID 2 JavaScript creatives, requiring a simple setup process outlined in the guide.\u003c/p\u003e\n"],["\u003cp\u003eKey differences exist between the VPAID 2 spec and the IMA SDK's implementation, primarily impacting creative authors.\u003c/p\u003e\n"],["\u003cp\u003eBy default, the SDK uses a secure iframe for rendering VPAID 2 creatives, but you can switch to a friendly iframe for DOM access.\u003c/p\u003e\n"],["\u003cp\u003eA video proxy element is used for security and mobile functionality, providing a subset of video element functionalities to the ad.\u003c/p\u003e\n"],["\u003cp\u003eVPAID 2 JavaScript creative support is currently exclusive to the IMA HTML5 SDK, not available in the iOS or Android SDKs.\u003c/p\u003e\n"]]],[],null,["# Enable VPAID 2 JavaScript creatives\n\nThe IMA HTML5 SDK supports VPAID 2 JavaScript creatives. Enabling support is easy, but there are two differences to be aware of between the [VPAID 2 spec](//iabtechlab.com/standards/video-player-ad-interface-definition-vpaid/) and the way the IMA SDK supports VPAID 2. These differences do not impact player or SDK implementation code, but they are important for VPAID 2 JavaScript creative authors, as creatives may throw errors or not work as expected when rendered by the IMA HTML5 SDK.\n\nPrerequisites\n-------------\n\n- HTML5 video player with the IMA HTML5 SDK integrated. If you don't have one, check out [Set up the IMA SDK](/interactive-media-ads/docs/sdks/html5/client-side).\n- A VAST ad tag URL that points to a VPAID 2 JavaScript creative.\n\nHelpful primers\n---------------\n\n- If you're not familiar with VPAID 2, you can read more at [IAB's VPAID page](//iabtechlab.com/standards/video-player-ad-interface-definition-vpaid/).\n\nEnabling VPAID 2 support\n------------------------\n\nTo enable VPAID 2 JavaScript support, call the following method before initializing your [AdDisplayContainer](/interactive-media-ads/docs/sdks/html5/client-side/reference/class/google.ima.AdDisplayContainer): \n\n```gdscript\n google.ima.settings.setVpaidMode(google.ima.ImaSdkSettings.VpaidMode.ENABLED);\n ...\n var adDisplayContainer = new google.ima.AdDisplayContainer(adContainerElement);\n var adsLoader = new google.ima.AdsLoader(adDisplayContainer);\n ...\n```\n\nThe available VPAID modes are as follows:\n\n- `ENABLED` - Allows VPAID ads with the default settings.\n- `INSECURE` - Allows VPAID ads in insecure mode. For more information, see [IFrame security](#iframe-security) and [Video player proxy element](#proxyelement).\n- `DISABLED` - VPAID ads do not play. If a requested ad returns a VPAID creative, an error is thrown.\n\nFor more information on VPAID modes, see the API documentation for [ImaSdkSettings.VpaidMode](/interactive-media-ads/docs/sdks/html5/client-side/reference/namespace/google.ima.ImaSdkSettings#google.ima.ImaSdkSettings.VpaidMode).\n\nVPAID 2 support caveats\n-----------------------\n\n### IFrame security\n\nBy default, the IMA SDK uses a secure iframe instead of a friendly iframe (same domain) or an in-page script to render VPAID 2 JavaScript creatives. This means that if a creative expects to access the DOM of the parent page, it could potentially cause an error. To render your ad in a friendly iframe instead, you can use `ImaSdkSettings.setVpaidMode(...)` like so: \n\n```text\nadsLoader.getSettings().setVpaidMode(google.ima.ImaSdkSettings.VpaidMode.INSECURE);\n```\n\n\u003cbr /\u003e\n\n### Video player proxy element\n\nFor security and proper mobile functionality, in `ENABLED` mode the IMA HTML5 SDK doesn't provide the actual video element to the ad; instead it provides a proxy element that mimics much of the functionality of the normal video element. For ad creatives that call only supported API methods, there should be no behavior changes in the rendering of the creatives. With `VpaidMode.INSECURE` mode, the SDK provides the video player element instead of the proxy.\n\nHere are the methods, listeners and attributes available on the video proxy element:\n\n#### Methods\n\n- `addEventListener`\n- `canPlayType`\n- `load`\n- `play`\n- `pause`\n- `setattribute`\n\n#### Event types for addEventListener\n\n- `abort`\n- `canplay`\n- `canplaythrough`\n- `click`\n- `durationchange`\n- `emptied`\n- `ended`\n- `error`\n- `loadeddata`\n- `loadedmetadata`\n- `loadstart`\n- `pause`\n- `play`\n- `playing`\n- `progress`\n- `ratechange`\n- `suspend`\n- `seeked`\n- `seeking`\n- `timeupdate`\n- `waiting`\n\n#### Attributes\n\n- `currentTime`\n- `duration`\n- `ended`\n- `paused`\n- `playbackRate`\n- `src`\n- `type`\n\nFAQ\n---\n\nAre VPAID 2 JavaScript creatives supported in the iOS or Android SDKs?\n: The IMA HTML5 SDK is the only IMA SDK platform that currently supports VPAID 2 JavaScript creatives.\n\nDoes this enable VPAID creatives in the IMA HTML5 SDK?\n: Yes, the IMA HTML5 SDK supports VPAID 2 JavaScript creatives."]]
