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

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

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

تقديم طلب لعرض إعلانات قابلة للتخطّي

لطلب بث فيديو عند الطلب يتضمّن إعلانات قابلة للتخطّي، يجب ضبط المَعلمة 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)

بالنسبة إلى طلبات البث المباشر وفق بروتوكول HTTP ‏(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 (عدد) مدة الفاصل الإعلاني بالثواني
ads (object(Ad)) قائمة بالإعلانات في البث
start (رقم) موضع بدء الإعلان في البث بالثواني
duration (عدد) مدة الإعلان بالثواني
skip_metadata ‫(object(SkipMetadata)) بيانات وصفية اختيارية للإعلانات القابلة للتخطي في حال ضبط هذا الخيار، يعني ذلك أنّ الإعلان قابل للتخطّي ويتضمن تعليمات حول كيفية التعامل مع واجهة مستخدِم التخطّي وحدث التتبّع.
offset (عدد) يشير المُحوِّل إلى المدة بالثواني التي يجب أن ينتظرها المشغِّل لعرض زر التخطّي بعد بدء عرض الإعلان. يتم حذفه إذا لم يتم تقديمه في ملف VAST.
tracking_url (سلسلة) عنوان 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 لترجمة نص "تخطّي الإعلان" استنادًا إلى لغة المستخدم.