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

‫1. نظرة عامة

شعار Google Cast

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

ما هي تكنولوجيا Google Cast؟

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

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

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

ما الذي سنقوم بإنشائه؟

عند الانتهاء من هذا الدرس العملي، ستكون قد أنشأت تطبيق Cast Receiver يستفيد من Break API.

أهداف الدورة التعليمية

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

المتطلبات

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

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

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

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

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

قراءة المحتوى فقط قراءة المحتوى وإكمال التمارين

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

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

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

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

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

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

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

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

تشغيل الخادم

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

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

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

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

صورة لـ Google Cast SDK Developer Console مع تمييز الزر "إضافة تطبيق جديد"

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

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

اختَر "جهاز استقبال مخصّص"، وهو ما سننشئه.

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

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

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

صورة لواجهة Google Cast SDK Play Console مع تمييز الزر "إضافة جهاز جديد"

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

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

أدخِل الرقم التسلسلي المطبوع على الجزء الخلفي من جهاز 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

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

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

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

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

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

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

index.html

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

receiver.js

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

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

تتيح حزمة تطوير البرامج (SDK) الخاصة بـ "أداة استقبال الويب" في Cast عرض الإعلانات المحدّدة من خلال قوائم تشغيل إعلانات الفيديو الرقمية المتعددة، المعروفة أيضًا باسم 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) الخاصة بأداة استقبال الويب مع العديد من أنواع الإعلانات. يسلّط هذا القسم الضوء على واجهات برمجة التطبيقات المتاحة لدمج إعلانات نموذج عرض إعلانات الفيديو الرقمية المعروفة أيضًا باسم VAST. إذا كنت قد نفّذت رمز VMAP من القسم السابق، علِّق عليه.

انسخ ما يلي في ملف js/receiver.js بعد أداة اعتراض طلب التحميل. يحتوي على ستة مقاطع فاصلة بتنسيق VAST من DoubleClick وقيمة معرّف ارتباط عشوائية. يتم تعيين هذه المقاطع إلى 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 ثانية).

9- تخصيص سلوك البحث عن فواصل إعلانية

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

لتخصيص الفواصل الإعلانية التي يتم تشغيلها عند البحث، توفّر حزمة تطوير البرامج (SDK) الخاصة بـ Cast واجهة برمجة التطبيقات 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 ثانية).

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

10. تهانينا

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

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