إنّ واجهة برمجة تطبيقات DAI في مرحلة تجريبية وقد لا تكون متاحة في شبكتك. اتصل بمدير حسابك للحصول على مزيد من المعلومات. ويُنصَح باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية للأنظمة الأساسية التي تتوفّر فيها.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إعلانات قابلة للتخطي أثناء البث عند الطلب

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

المتطلّبات الأساسية

تطبيق ينفّذ طلبات البيانات من واجهة برمجة التطبيقات DAI لبثّ الفيديوهات عند الطلب يُرجى الاطّلاع على دليل بث الفيديوهات عند الطلب في DAI API للحصول على المزيد من المعلومات.

تقديم طلب بشأن الإعلانات القابلة للتخطّي

لطلب بث "فيديو عند الطلب" يتضمّن إعلانات قابلة للتخطّي، يجب ضبط مَعلمة dai-sas في طلب البث.

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

POST: /ondemand/v1/hls/content/{CMS_ID}/vid/{VIDEO_ID}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

مَعلمات المسار

`{CMS_ID}`	رقم تعريف نظام إدارة المحتوى الخاص بالبث.
`{VIDEO_ID}`	معرّف الفيديو للبث.

معلمات النص الأساسي

dai-sas يجب ضبط dai-sas=1 لتفعيل الإعلانات القابلة للتخطّي.

مثال على الطلب (cURL)

لطلبات البث عبر بروتوكول HLS:

curl -X POST \
     -d 'dai-sas=1' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
https://dai.google.com/ondemand/v1/hls/content/{CMS_ID}/vid/{VIDEO_ID}/stream

استبدال 'dash' في عنوان URL لمصادر بيانات DASH:

https://dai.google.com/ondemand/v1/dash/content/{CMS_ID}/vid/{VIDEO_ID}/stream

استخدِم التنسيق التالي لتضمين عدّة معلَمات بث في نص طلبك:

-d 'dai-sas=1&cust_params=key1%3dvalue1%26key2%3dvalue2' \

التعامل مع تخطّي الإعلانات

للتعامل مع تخطّي الإعلانات، استخدِم المعلومات في البنية Ad أو البنية AdBreak استنادًا إلى ما إذا كنت تتخطّى الإعلان الحالي أو الفاصل الإعلاني بالكامل. استخدِم القيمة start وأضِف القيمة duration، ثم انتقِل إلى تلك النقطة في ساحة المشاركات. تتضمّن الرسالة الفرعية SkipMetadata أيضًا القيمة offset، وهي قيمة بالثواني من الوقت قبل أن يكون بالإمكان تخطّي الإعلان. لن يتم تضمين الرسالة الفرعية "SkipMetadata" إلا في الإعلانات القابلة للتخطّي.

ad_breaks

قائمة الفواصل الإعلانية.

start (الرقم) الموضع بالثواني في ساحة المشاركات الذي يبدأ فيه الفاصل.

duration (number) مدة الفاصل الإعلاني بالثواني.

ads

(object(Ad)) هي قائمة بالإعلانات في ساحة المشاركات

start (عدد) الموضع في ساحة المشاركات التي يبدأ فيها الإعلان، بالثواني.

duration (number) مدة الإعلان بالثواني.

skip_metadata

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

`offset`	(عدد) تشير قيمة الإزاحة إلى المدة الزمنية بالثواني التي يجب أن ينتظرها المشغّل لعرض زر التخطّي. ويتم حذفها إذا لم يتم توفيرها في نموذج عرض إعلانات فيديو (VAST).
`tracking_url`	(string) عنوان URL الذي يجب إرسال إشارة إليه عند حدث التخطّي.

مثال على إجابة

{
  ...
  "ad_breaks":[
    {
      ...
      "start":0,
      "duration":10,
      "ads":[
        {
          ...
          "start":0,
          "duration":10,
          "skip_metadata":{
            "offset": 5,
            "tracking_url": "https://example_skip_url.com"
          }
        }
    }
}

بعد تخطي الإعلان، يمكنك إشعار عنوان URL لحدث التخطّي المضمّن في استجابة البث. تم تضمينها في الرسالة الفرعية "SkipMetadata".

متطلبات زر التخطّي

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

مؤقت العد التنازلي

يجب ألا يكون الإعلان قابلاً للتخطي حتى وقت skipoffset المحدد في نموذج عرض إعلانات الفيديو (VAST). وخلال هذه الفترة غير القابلة للتخطّي، عليك عرض إشعار للمستخدم لإعلامه بأنّه يمكن تخطّي الإعلان خلال X ثانية. يجب ترجمة الإشعار إلى لغة المستخدم.

تخطي موضع الزر

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

حجم زر التخطي

يجب أن يكون الزر والنص كبيرَين بما يكفي ليكونا مقروءَين بوضوح في تجربة مريحة.

النص والرمز

يجب أن يحتوي زر التخطي على كل من النص والأيقنة. يمكنك استخدام رمز تخطّي المادة التالية كرمز للرمز.

تسهيل الاستخدام

يجب أن يتمكن المستخدم من الانتقال إلى زر التخطي باستخدام لوحة مفاتيح أو وحدة تحكم عن بُعد. ينبغي أن يركز التطبيق على زر التخطي بعد انتهاء العد التنازلي.

التوافق مع أسواق عالمية

ننصح بترجمة نص التخطّي إلى لغة المستخدم.

مجموعات الإعلانات المتسلسلة

يمكن استخدام زر التخطّي لتخطّي الإعلان الحالي في مجموعة الإعلانات المتسلسلة أو لتخطّي المجموعة بأكملها.

ترجمات "تخطي الإعلان"

استخدِم ملف skipAdTranslations.json لترجمة نص "تخطّي الإعلان" استنادًا إلى لغة المستخدم.