إضافة دعم واجهة برمجة التطبيقات الخاصة بفواصل الإعلانات إلى مستقبِل الويب

1- نظرة عامة

شعار Google Cast

يوضّح هذا الدرس التطبيقي حول الترميز كيفية إنشاء تطبيق ويب مخصَّص لاستقبال البيانات باستخدام واجهة برمجة التطبيقات Cast Ad Breaks API.

ما المقصود بـ Google Cast؟

تتيح تكنولوجيا Google Cast للمستخدمين بث المحتوى من جهاز جوّال إلى تلفزيون. يمكن للمستخدمين بعد ذلك استخدام أجهزتهم الجوّالة كوحدة تحكّم عن بُعد لتشغيل الوسائط على التلفزيون.

تتيح لك حزمة تطوير البرامج (SDK) لتقنية Google Cast توسيع نطاق تطبيقك للتحكّم في التلفزيون أو نظام الصوت. تتيح لك حزمة تطوير البرامج (SDK) لجهاز Google Cast إضافة مكونات واجهة المستخدم الضرورية بناءً على قائمة التحقق من تصميم Google Cast.

يتم توفير قائمة التحقق من تصميم Google Cast لتوحيد طريقة تنفيذ تكنولوجيا Google Cast لتسهيل تجربة المستخدم على جميع الأنظمة الأساسية المتوافقة.

ما الذي سنبنيه؟

بعد الانتهاء من هذا الدرس التطبيقي حول الترميز، ستكون قد أنشأت جهاز استقبال البث يستفيد من واجهة برمجة التطبيقات Break API.

ما ستتعرَّف عليه

  • كيفية تضمين فواصل VMAP وVAST في محتوى البث
  • كيفية تخطّي مقاطع الفواصل
  • كيفية تخصيص سلوك الفاصل التلقائي عند التقديم/الترجيع

المتطلبات

  • أحدث إصدار من متصفِّح Google Chrome.
  • خدمة استضافة HTTPS، مثل استضافة Firebase أو ngrok.
  • جهاز Google Cast، مثل Chromecast أو Android TV تم ضبطه على الاتصال بالإنترنت
  • تلفزيون أو شاشة بها منفذ إدخال HDMI أو شاشة Google Home Hub

التجربة

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

  • معرفة عامة بتطوير الويب.
  • جارٍ إنشاء تطبيقات جهاز استقبال الويب Cast.

كيف ستستخدم هذا البرنامج التعليمي؟

القراءة فقط اقرأه وإكمال التمارين

ما هو تقييمك لتجربتك في إنشاء تطبيقات الويب؟

مبتدئ متوسط مختص

2. الحصول على الرمز النموذجي

نزِّل الرمز النموذجي بالكامل على جهاز الكمبيوتر...

وفك ضغط الملف الذي تم تنزيله.

3. نشر جهاز الاستقبال على الجهاز

لتتمكن من استخدام جهاز استقبال الويب مع جهاز بث، يجب استضافته في مكان يمكن لجهاز البث من خلاله الوصول إليه. إذا كان لديك خادم يتيح لك استخدام https، يمكنك تخطّي التعليمات التالية وتدوين عنوان URL، لأنّه ستحتاج إليه في القسم التالي.

إذا لم يكن لديك خادم متاح للاستخدام، يمكنك استخدام استضافة Firebase أو ngrok.

تشغيل الخادم

بعد إعداد الخدمة التي تختارها، انتقِل إلى app-start ثم شغِّل الخادم.

دوِّن عنوان URL للمستلِم المستضاف. ستستخدمها في القسم التالي.

4. تسجيل تطبيق في Google Cast Console

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

صورة لوحدة تحكّم المطوّرين في حزمة Google Cast SDK يظهر فيها الزر "إضافة تطبيق جديد" مميّزًا

انقر على "إضافة تطبيق جديد".

صورة لشاشة "تطبيق جهاز الاستقبال الجديد" مع تمييز الخيار "جهاز استقبال مخصّص"

انقر على "مستلم مخصّص"، وهذا هو ما نطوّره.

صورة لشاشة "جهاز استقبال مخصّص جديد" تعرِض عنوان URL يكتبه أحد المستخدِمين في الحقل "عنوان URL لتطبيق جهاز الاستقبال"

أدخِل تفاصيل المستلِم الجديد. احرِص على استخدام عنوان URL الذي يشير إلى المكان الذي تخطط لاستضافة تطبيق Webتعرَّف عليه في الوقت الحالي. دوِّن معرّف التطبيق الذي تنشئه وحدة التحكّم بعد تسجيل التطبيق. سيتم إعداد تطبيق المرسِل لاستخدام هذا المعرّف في قسم لاحق.

يجب أيضًا تسجيل جهاز Google Cast حتى يتسنى له الوصول إلى تطبيق المُستلِم قبل نشره. بعد نشر تطبيق جهاز الاستقبال، سيصبح متاحًا لجميع أجهزة Google Cast. لأغراض هذا الدرس التطبيقي حول الترميز، يُنصح باستخدام تطبيق مستلِم غير منشور.

صورة لوحدة تحكّم المطوّرين في حزمة تطوير البرامج (SDK) لتكنولوجيا Google Cast مع تمييز الزر "إضافة جهاز جديد"

انقر على "إضافة جهاز جديد"

صورة لمربّع الحوار "إضافة جهاز استقبال بث"

أدخِل الرقم التسلسلي المطبوع على الجزء الخلفي من جهاز البث وأدخِل اسمًا وصفيًا له. يمكنك أيضًا العثور على الرقم التسلسلي من خلال بث محتوى شاشتك في Chrome عند الدخول إلى Google Cast SDK Developer Console.

يستغرق الأمر من 5 إلى 15 دقيقة لتجهيز جهاز الاستقبال والجهاز للاختبار. بعد الانتظار من 5 إلى 15 دقيقة، يجب إعادة تشغيل جهاز البث.

5. تجهيز المشروع

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

يجب إضافة التوافق مع Google Cast إلى تطبيق البدء الذي نزّلته. في ما يلي بعض مصطلحات Google Cast المستخدَمة في هذا الدرس التطبيقي حول الترميز:

  • يعمل تطبيق المرسِل على جهاز جوّال أو كمبيوتر محمول
  • يتم تشغيل تطبيق جهاز الاستقبال على جهاز Google Cast.

أنت الآن جاهز للبناء على مشروع المبتدئين باستخدام محرر النصوص المفضل لديك:

  1. اختَر الدليل رمز المجلدapp-start من نموذج الرمز الذي تم تنزيله.
  2. افتح js/receiver.js وindex.html.

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

تصميم التطبيق

كما أسلفنا، يستخدم الدرس التطبيقي حول الترميز تطبيق المُرسِل لبدء جلسة البثّ وتطبيق مستلِم سيتم تعديله لاستخدام واجهات برمجة تطبيقات الفواصل الإعلانية.

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

ملاحظة: إذا لم يظهر رمز البث، تأكّد من تسجيل أجهزة استقبال الويب وأجهزة البث بشكل صحيح في وحدة تحكّم مطوّري برامج البث. إذا لم يسبق لك إجراء ذلك، عليك تشغيل أي أجهزة بث تم تسجيلها للتوّ.

إنّ تطبيق جهاز الاستقبال هو محور التركيز الرئيسي لهذا الدرس التطبيقي حول الترميز ويتكون من عرض رئيسي واحد محدّد في index.html وملف JavaScript واحد يُسمى js/receiver.js. وفي ما يلي مزيد من التوضيح.

index.html

يحتوي ملف html هذا على واجهة مستخدم لتطبيق الاستقبال الذي يوفره العنصر cast-media-player. كما تحمِّل مكتبات CAF SDK ومسجّل تصحيح أخطاء Cast.

receiver.js

يدير هذا النص البرمجي كل المنطق في تطبيق جهاز الاستقبال. ويحتوي الآن على جهاز استقبال CAF أساسي لإعداد سياق البث وتحميل مادة عرض الفيديو عند التهيئة. تمت أيضًا إضافة بعض إمكانات مسجّل تصحيح الأخطاء لإتاحة تسجيل الدخول مرة أخرى إلى أداة Cast وCommand.

6. إضافة VMAP إلى المحتوى الخاص بك

توفر حزمة تطوير البرامج (SDK) لجهاز استقبال الويب Cast دعمًا للإعلانات المحدّدة من خلال قوائم تشغيل إعلانات متعددة للفيديوهات الرقمية، والمعروفة أيضًا باسم VMAP. تحدّد بنية XML الفواصل الإعلانية في الوسائط والبيانات الوصفية لمقاطع الفواصل المرتبطة بها. لإدراج هذه الإعلانات، توفِّر حزمة تطوير البرامج (SDK) السمة vmapAdsRequest في العنصر MediaInformation.

في الملف js/receiver.js، أنشِئ كائن VastAdsRequest. حدِّد موقع دالة اعتراض الطلب LOAD واستبدلها بالرمز التالي أدناه. ويتضمّن هذا التقرير نموذج عنوان URL لعلامة VMAP من DoubleClick، كما يوفر قيمة correlator عشوائية لضمان أن تنشئ الطلبات اللاحقة لعنوان URL نفسه نموذج XML يحتوي على فواصل إعلانية لم تتم مشاهدتها بعد.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      const vmapUrl =
          'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
          Math.floor(Math.random() * Math.pow(10, 10));
      let vmapRequest = new cast.framework.messages.VastAdsRequest();
      vmapRequest.adTagUrl = vmapUrl;
      loadRequestData.media.vmapAdsRequest = vmapRequest;

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

احفظ التغييرات التي أجريتها على js/receiver.js وحمّل الملف إلى خادم الويب الخاص بك. يمكنك بدء جلسة البث على أداة البثّ والطلب من خلال النقر على رمز البث. من المفترض أن يتم تشغيل إعلانات VMAP، متبوعًا بالمحتوى الرئيسي.

7. إضافة نموذج عرض إعلانات فيديو (VAST) إلى المحتوى الخاص بك

كما ذكرنا سابقًا، هناك دعم للعديد من أنواع الإعلانات في حزمة تطوير البرامج (SDK) لأداة استقبال الويب. يوضّح هذا القسم واجهات برمجة التطبيقات المتاحة لدمج إعلانات نموذج عرض إعلانات الفيديو الرقمية والمعروفة أيضًا باسم نموذج عرض إعلانات الفيديو (VAST). إذا كنت قد نفذت شفرة VMAP من القسم السابق، فقم بالتعليق عليها.

انسخ ما يلي إلى ملف js/receiver.js بعد اعتراض طلب التحميل. ويتضمّن ستة مقاطع فاصلة بتنسيق VAST من DoubleClick وقيمة correlator عشوائية. يتم تخصيص 5 فواصل للاستراحة. يتم ضبط position لكل فاصل على وقت بالثواني بالنسبة إلى المحتوى الرئيسي، بما في ذلك فواصل ما قبل التشغيل (تم ضبط position على 0) وفواصل ما بعد التشغيل (تم ضبط position على -1).

const addVASTBreaksToMedia = (mediaInformation) => {
  mediaInformation.breakClips = [
    {
      id: 'bc1',
      title: 'bc1 (Pre-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('preroll')
      }
    },
    {
      id: 'bc2',
      title: 'bc2 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc3',
      title: 'bc3 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc4',
      title: 'bc4 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc5',
      title: 'bc5 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc6',
      title: 'bc6 (Post-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('postroll')
      }
    }
  ];

  mediaInformation.breaks = [
    {id: 'b1', breakClipIds: ['bc1'], position: 0},
    {id: 'b2', breakClipIds: ['bc2'], position: 15},
    {id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
    {id: 'b4', breakClipIds: ['bc5'], position: 100},
    {id: 'b5', breakClipIds: ['bc6'], position: -1}
  ];
};

ملاحظة: إنّ السمة breakClipIds للفاصل الإعلاني هي مصفوفة، ما يعني أنّه يمكن تخصيص مقاطع فواصل متعددة لكل فاصل.

في js/receiver.js file، حدّد موقع اعتراض الرسائل LOAD واستبدله بالرمز التالي. تجدر الإشارة إلى أنّه يتم التعليق على عمل VMAP لعرض الإعلانات من نوع VAST.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      // const vmapUrl =
      //     'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
      //     Math.floor(Math.random() * Math.pow(10, 10));
      // let vmapRequest = new cast.framework.messages.VastAdsRequest();
      // vmapRequest.adTagUrl = vmapUrl;
      // loadRequestData.media.vmapAdsRequest = vmapRequest;

      // Append VAST ad breaks to the MediaInformation.
      addVASTBreaksToMedia(loadRequestData.media);

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

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

8. تخطّي الفواصل الإعلانية

يتوفر في CAF فئة باسم BreakManager تساعدك في تطبيق قواعد النشاط التجاري المخصّصة لسلوكيات الإعلانات. تتيح إحدى هذه الميزات للتطبيقات تخطي الفواصل وتقسيم المقاطع بشكل آلي استنادًا إلى بعض الحالات. يعرض هذا المثال كيفية تخطي فاصل إعلاني يقع موضعه ضمن أول 30 ثانية من المحتوى، ولكن لا يتم تخطّي فواصل إعلان ما بعد التشغيل. عند استخدام إعلانات نموذج عرض إعلانات الفيديو (VAST) التي تم ضبطها في القسم السابق، يتم تحديد 5 فواصل: فاصل واحد لإعلان ما قبل التشغيل، و3 فواصل إعلانية أثناء التشغيل (عند 15، و60، و100 ثانية)، وأخيرًا، فاصل واحد لإعلان ما بعد التشغيل. بعد إكمال هذه الخطوات، يتم فقط تخطّي إعلانَي ما قبل التشغيل وإعلان أثناء التشغيل اللذَين يتم ضبط موضعهما عند 15 ثانية.

لإجراء ذلك، يجب أن يطلب التطبيق واجهات برمجة التطبيقات المتوفّرة من خلال BreakManager لضبط أداة اعتراض لتحميل الفاصل. انسخ السطر التالي في ملف js/receiver.js، بعد الأسطر التي تحتوي على المتغيّرَين context وplayerManager للحصول على مرجع إلى المثيل.

const breakManager = playerManager.getBreakManager();

يجب أن يضبط التطبيق أداة اعتراض باستخدام قاعدة لتجاهل أي فواصل إعلانية تظهر قبل مرور 30 ثانية مع مراعاة أي فواصل إعلانية بعد التشغيل (حيث إنّ قيم position لها هي -1). تعمل أداة الاعتراض هذه مثل اعتراض التحميل على PlayerManager، غير أنّ هذه الميزة مخصّصة لتحميل مقاطع الفواصل. يتم ضبط ذلك بعد اعتراض طلب LOAD وقبل إعلان الدالة addVASTBreaksToMedia.

انسخ ما يلي في ملف js/receiver.js.

breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
  /**
   * The code will skip playback of break clips if the break position is within
   * the first 30 seconds.
   */
  let breakObj = breakContext.break;
  if (breakObj.position >= 0 && breakObj.position < 30) {
    castDebugLogger.debug(
        'MyAPP.LOG',
        'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
    return null;
  } else {
    return breakClip;
  }
});

ملاحظة: يؤدي إرجاع null هنا إلى تخطّي BreakClip التي تتم معالجتها. إذا لم يتم تحديد أي مقاطع فواصل إعلانية في Break، يتم تخطّي الفاصل نفسه.

احفظ التغييرات التي أجريتها على js/receiver.js وحمّل الملف إلى خادم الويب الخاص بك. يمكنك بدء جلسة البث على أداة البثّ والطلب من خلال النقر على رمز البث. يجب معالجة إعلانات نموذج عرض إعلانات الفيديو (VAST). تجدر الإشارة إلى أنّه لا يتم تشغيل إعلانات ما قبل التشغيل وإعلان أثناء التشغيل الأول (وتبلغ مدة position منهما 15 ثانية).

9. تخصيص سلوك تقديم الفاصل

عند البحث عن الفواصل السابقة، تحصل طريقة التنفيذ التلقائية على جميع عناصر Break التي تقع موضعها بين قيمتَي seekFrom وseekTo في عملية البحث. من قائمة الفواصل الإعلانية هذه، تشغّل حزمة تطوير البرامج (SDK) Break التي يكون position الخاص بها هو الأقرب إلى قيمة seekTo والتي تم ضبط سمة isWatched الخاصة بها على false. بعد ذلك، يتم ضبط سمة isWatched الخاصة بهذا الفاصل على true ويبدأ المشغّل تشغيل مقاطع الفواصل. بعد مشاهدة الفاصل، يتم استئناف تشغيل المحتوى الرئيسي من الموضع seekTo. وفي حال عدم توفُّر فاصل إعلاني من هذا النوع، لن يتم تشغيل أي فاصل إعلاني وسيتم استئناف تشغيل المحتوى الرئيسي في الموضع seekTo.

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

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

انسخ ما يلي في ملف js/receiver.js ضمن التعريف إلى setBreakClipLoadInterceptor.

breakManager.setBreakSeekInterceptor((breakSeekData) => {
  /**
   * The code will play an unwatched break between the seekFrom and seekTo
   * position. Note: If the position of a break is less than 30 then it will be
   * skipped due to the setBreakClipLoadInterceptor code.
   */
  castDebugLogger.debug(
      'MyAPP.LOG',
      'Break Seek Interceptor processing break ids ' +
          JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));

  // Remove all other breaks except for the first one.
  breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
  return breakSeekData;
});

ملاحظة: إذا لم تعرض الدالة أي قيمة أو إذا كانت تعرض null، لن يتم تشغيل أي فواصل.

احفظ التغييرات التي أجريتها على js/receiver.js وحمّل الملف إلى خادم الويب الخاص بك. يمكنك بدء جلسة البث على أداة البثّ والطلب من خلال النقر على رمز البث. يجب معالجة إعلانات نموذج عرض إعلانات الفيديو (VAST). تجدر الإشارة إلى أنّه لا يتم تشغيل إعلانات ما قبل التشغيل وإعلان أثناء التشغيل الأول (وتبلغ مدة position منهما 15 ثانية).

انتظِر إلى أن يصل وقت التشغيل إلى 30 ثانية لتجاوز جميع الفواصل التي يتم تخطيها بواسطة أداة اعتراض تحميل مقاطع الفواصل. بعد الوصول، أرسِل أمر بحث من خلال الانتقال إلى علامة التبويب التحكم في الوسائط. املأ إدخال البحث في الوسائط بمقدار 300 ثانية، ثم انقر على الزر إلى. دوِّن السجلات المطبوعة في Break Seek Interceptor. يجب الآن إلغاء السلوك التلقائي لتشغيل الفاصل في وقت أقرب إلى وقت seekFrom.

‫10. تهانينا

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

لمزيد من التفاصيل، اطّلِع على دليل مطوّري برامج الفواصل الإعلانية.