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

1. نظرة عامة

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

ما المقصود بتكنولوجيا Google Cast؟

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

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

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

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

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

المُعطيات

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

المتطلبات

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

تجربة الاستخدام

تأكَّد من توفّر الخبرة التالية لديك قبل المتابعة في هذا الدليل التعليمي حول البرمجة.

• المعرفة العامة لتطوير الويب
• إنشاء تطبيقات Cast Web Receiver

> هل تواجه مشاكل في الشبكة؟ > إذا كنت في موقع جغرافي لا تتوفّر فيه شبكة Wi-Fi موثوقة، يمكن توصيل جهاز Chromecast باستخدام محوِّل إيثرنت من أجل

Chromecast أو Chromecast مع Google TV

كيف ستستخدم هذا الدليل التعليمي؟

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

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

مبتدئ متوسط متقدّم

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

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

تنزيل رمز المصدر

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

> يحتوي مستودع codelab على مشروعَين نموذجيَّين: > * app-start: الرمز البرمجي الأوّلي الذي ستستند إليه في هذا الدليل التعليمي. * app-done: الرمز الكامل لنموذج تطبيق الفيديو المكتمل.

3- نشر جهاز الاستقبال محليًا

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

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

تشغيل الخادم

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

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

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

> أليس لديك حساب مطوِّر على Cast؟ > اشترِك في حساب على Google Cast SDK Developer Console وادفع رسوم التسجيل.

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

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

اختَر "مستلِم مخصّص"، وهو ما سننشئه.

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

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

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

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

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

5- إعداد مشروع "البدء"

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

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

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

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

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

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

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

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

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

ملاحظة: إذا تبيّن لك أنّ رمز البث لا يظهر، تأكَّد من تسجيل Web Receiver وأجهزة البث بشكلٍ صحيح في Cast Developer Console. إذا لم يسبق لك ذلك، يُرجى فصل أي أجهزة بث تم تسجيلها للتو وإعادة توصيلها بالطاقة.

يركّز هذا الدرس التطبيقي حول الترميز بشكل أساسي على تطبيق المستلِم، ويتألف من طريقة عرض رئيسية واحدة تم تحديدها في index.html وملف JavaScript واحد باسم js/receiver.js. ويمكنك الاطّلاع على مزيد من التفاصيل أدناه.

index.html

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

receiver.js

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

> هل تتوفّر مستندات حول البث؟ > لدينا مستندات شاملة للمرسلين ومُرسِلي أجهزة iOS وAndroid وChrome.

6- إضافة VMAP إلى المحتوى

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

في ملف js/receiver.js، أنشئ عنصر VastAdsRequest. حدِّد مكان الدالة LOAD request interceptor واستبدِلها بالرمز البرمجي التالي أدناه. يحتوي على نموذج لعنوان URL لعلامة VMAP من DoubleClick ويقدّم قيمة مرتبطة عشوائية لضمان أنّ الطلبات اللاحقة لعنوان 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) لبرنامج Web Receiver. يسلّط هذا القسم الضوء على واجهات برمجة التطبيقات المتاحة لدمج إعلانات نموذج عرض إعلانات الفيديو الرقمية، المعروفة أيضًا باسم 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). يعمل معرّف المقاطع هذا مثل معرّف المقاطع LOAD في 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) لأجهزة استقبال البث.

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

> هل تريد المزيد من المحتوى المعروض على الشاشة؟ > يمكنك الاطّلاع على المشاريع البرمجية الأخرى لتطبيقات البث ونماذج التطبيقات على GitHub.