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

1. نظرة عامة

شعار Google Cast

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

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

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

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

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

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

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

المُعطيات

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

المتطلبات

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

التجربة

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

  • معرفة عامة بتطوير الويب.
  • إنشاء تطبيقات مستقبل الويب للبث.

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

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

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

حديث متوسط بارع

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

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

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

3- نشر المستلِم على الجهاز

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

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

تشغيل الخادم

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

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

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

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

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

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

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

حدد "جهاز استقبال مخصص"، هذا هو ما ننشئه.

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

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

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

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

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

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

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

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

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

index.html

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

receiver.js

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

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

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

في ملف js/receiver.js، أنشئ كائن VastAdsRequest. حدِّد موقع دالة اعتراض طلبات التحميل واستبدلها بالرمز التالي أدناه. ويحتوي على نموذج لعنوان 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 ثانية لتجاوز كل الفواصل التي يتم تخطّيها بواسطة أداة اعتراض تحميل مقطع الفاصل. بعد الوصول إلى هذا العنصر، أرسِل أمر التقديم/الترجيع من خلال الانتقال إلى علامة التبويب التحكّم في الوسائط. املأ حقل الإدخال Seek Into Media بمدة 300 ثانية، ثم انقر على الزر TO. دوِّن السجلات المطبوعة في Break Seek Interceptor. من المفترض أن يتم إلغاء السلوك التلقائي الآن لتشغيل الفاصل عندما يكون أقرب إلى وقت seekFrom.

10. تهانينا

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

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