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

1- نظرة عامة

شعار Google Cast

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

ما هي خدمة Google Cast؟

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

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

تم توفير قائمة التحقّق من تصميم Google 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- تسجيل تطبيق في Play Console

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

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

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

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

اختَر "المستقبِل المخصَّص". هذا هو الإصدار الذي ننشئه.

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

أدخِل تفاصيل المستلِم الجديد، واحرص على استخدام عنوان URL الذي استخدمته في النهاية.

في القسم الأخير. دوِّن معرّف التطبيق الذي تم إسناده إلى المستلِم الجديد.

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

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

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

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

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

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

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

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

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

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

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

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

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

بالنسبة إلى المُرسِل، سنستخدم أداة تصحيح أخطاء مستلِم CAF أيضًا لبدء جلسة بث. تم تصميم المُستلِم لبدء تشغيل بث تلقائيًا.

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

يُعِدّ تطبيق المُستلِم جلسة البث وسيظهر في وضع الاستعداد إلى أن يصل طلب LOAD (أي أمر تشغيل جزء من الوسائط) من المُرسِل.

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

index.html

سيتضمّن ملف html هذا كل واجهة المستخدم لتطبيق المُستلِم، وهو فارغ في الوقت الحالي.

Getr.js

سيدير هذا النص البرمجي كل المنطق لتطبيق الاستقبال. ويحتوي حاليًا على مستقبِل CAF أساسي.

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

للبدء، افتح مُرسِل الويب في Chrome. أدخِل معرّف تطبيق المُستلِم الذي حصلت عليه على Play Console Developer Console وانقر على "ضبط".

في جهاز الاستقبال، علينا إضافة بعض المنطق لتضمين الإعلانات في المحتوى.

انسخ السطر التالي إلى ملف js/receiver.js. وتحتوي هذه الحملة على نموذج لرابط علامة VMAP من DoubleClick، بالإضافة إلى بعض التوزيع العشوائي.

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));

في js/receiver.js file، حدِّد الدالة playerManager.setMessageInterceptor وأضِف ما يلي قبل سطر return request; الأخير في الدالة.

request.media.vmapAdsRequest = {
    adTagUrl: vmapUrl,
};

ملاحظة: العنصر المخصّص للسمة vmapAdsRequest أعلاه هو نسخة مختصرة من عنصر VastAdsRequest.

احفظ التغييرات التي أجريتها على js/receiver.js وابدأ جلسة بث على مُرسِل الويب بالنقر بزر الماوس الأيمن على أي مكان في الصفحة واختيار "البث". من المفترض أن يبدأ بث مصدر الإعلانات على الفور.

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

في حال تنفيذ رمز VMAP من قبل، يُرجى التعليق عليه. في ما يلي سنستعرض كيفية تنفيذ إعلانات نموذج عرض إعلانات الفيديو (VAST) في المحتوى.

انسخ ما يلي في ملف js/receiver.js. وتحتوي هذه القناة على ستة مقاطع فواصل من DoubleClick، بالإضافة إلى بعض التوزيع العشوائي. نخصّص 5 مقاطع فاصلة هذه. يتم أيضًا تحديد موضع كل فاصل.

const addVASTBreaksToMedia = (mediaInformation) => {
    mediaInformation.breakClips = [
        {
            id: "bc1",
            title: "bc1 (Pre-roll)",
            vastAdsRequest: {
                adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?slotname=/124319096/external/ad_rule_samples&sz=640x480&ciu_szs=300x250&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&url=&unviewed_position_start=1&output=xml_vast3&impl=s&env=vp&gdfp_req=1&ad_rule=0&vad_type=linear&vpos=preroll&pod=1&ppos=1&lip=true&min_ad_duration=0&max_ad_duration=30000&vrid=6256&correlator=' + Math.floor(Math.random() * Math.pow(10, 10)) + '&video_doc_id=short_onecue&cmsid=496&kfa=0&tfcd=0'
            }
        },
        {
            id: "bc2",
            title: "bc2 (Mid-roll)",
            vastAdsRequest: {
                adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?slotname=/124319096/external/ad_rule_samples&sz=640x480&ciu_szs=300x250&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&url=&unviewed_position_start=1&output=xml_vast3&impl=s&env=vp&gdfp_req=1&ad_rule=0&cue=15000&vad_type=linear&vpos=midroll&pod=2&mridx=1&rmridx=1&ppos=1&lip=true&min_ad_duration=0&max_ad_duration=30000&vrid=6256&correlator=' + Math.floor(Math.random() * Math.pow(10, 10)) + '&video_doc_id=short_onecue&cmsid=496&kfa=0&tfcd=0'
            }
        },
        {
            id: "bc3",
            title: "bc3 (Mid-roll)",
            vastAdsRequest: {
                adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?slotname=/124319096/external/ad_rule_samples&sz=640x480&ciu_szs=300x250&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&url=&unviewed_position_start=1&output=xml_vast3&impl=s&env=vp&gdfp_req=1&ad_rule=0&cue=15000&vad_type=linear&vpos=midroll&pod=2&mridx=1&rmridx=1&ppos=1&lip=true&min_ad_duration=0&max_ad_duration=30000&vrid=6256&correlator=' + Math.floor(Math.random() * Math.pow(10, 10)) + '&video_doc_id=short_onecue&cmsid=496&kfa=0&tfcd=0'
            }
        },
        {
            id: "bc4",
            title: "bc4 (Mid-roll)",
            vastAdsRequest: {
                adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?slotname=/124319096/external/ad_rule_samples&sz=640x480&ciu_szs=300x250&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&url=&unviewed_position_start=1&output=xml_vast3&impl=s&env=vp&gdfp_req=1&ad_rule=0&cue=15000&vad_type=linear&vpos=midroll&pod=2&mridx=1&rmridx=1&ppos=1&lip=true&min_ad_duration=0&max_ad_duration=30000&vrid=6256&correlator=' + Math.floor(Math.random() * Math.pow(10, 10)) + '&video_doc_id=short_onecue&cmsid=496&kfa=0&tfcd=0'
            }
        },
        {
            id: "bc5",
            title: "bc5 (Mid-roll)",
            vastAdsRequest: {
                adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?slotname=/124319096/external/ad_rule_samples&sz=640x480&ciu_szs=300x250&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&url=&unviewed_position_start=1&output=xml_vast3&impl=s&env=vp&gdfp_req=1&ad_rule=0&cue=15000&vad_type=linear&vpos=midroll&pod=2&mridx=1&rmridx=1&ppos=1&lip=true&min_ad_duration=0&max_ad_duration=30000&vrid=6256&correlator=' + Math.floor(Math.random() * Math.pow(10, 10)) + '&video_doc_id=short_onecue&cmsid=496&kfa=0&tfcd=0'
            }
        },
        {
            id: "bc6",
            title: "bc6 (Post-roll)",
            vastAdsRequest: {
                adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?slotname=/124319096/external/ad_rule_samples&sz=640x480&ciu_szs=300x250&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&url=&unviewed_position_start=1&output=xml_vast3&impl=s&env=vp&gdfp_req=1&ad_rule=0&vad_type=linear&vpos=postroll&pod=3&ppos=1&lip=true&min_ad_duration=0&max_ad_duration=30000&vrid=6256&correlator=' + Math.floor(Math.random() * Math.pow(10, 10)) + '&video_doc_id=short_onecue&cmsid=496&kfa=0&tfcd=0'
            }
        }
    ];
    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، أي سطر يبدأ بـ playerManager.setMessageInterceptor، وأضِف ما يلي قبل السطر الأخير من return request; في الدالة.

addVASTBreaksToMedia(request.media);

احفظ التغييرات التي أجريتها على js/receiver.js وابدأ جلسة بث على مُرسِل الويب بالنقر بزر الماوس الأيمن على أي مكان في الصفحة واختيار "البث". من المفترض أن يبدأ بث مصدر الإعلانات على الفور.

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

يشتمل CAF على فئة جديدة تُسمى BreakManager تساعدك في تنفيذ قواعد النشاط التجاري المخصّصة لسلوك الإعلانات. لنفترض أنّك تريد تفعيل فترة سماح للعملاء لتخطّي الإعلانات بعد فترة معيّنة.

لا يحتوي المُرسِل في المثال على عناصر تحكّم في الوسائط. لنضيف إزاحة بدء تبلغ 10 ثوانٍ لكي يبدأ البث بعد التشغيل، ولكن قبل بدء الفاصل الإعلاني أثناء التشغيل في العلامة 15 ثانية.

ابحث عن playerManager.setMessageInterceptor وأضِف السطر التالي قبل return request.

request.currentTime = 10;

احفظ ملف receiver.js وابدأ جلسة بث. من المفترض أن يتم تحميل المحتوى لمدة 10 ثوانٍ، ثم يتم تشغيل إعلان بعد 5 ثوانٍ.

لنبدأ الآن بإضافة قاعدة لتخطّي الإعلان أثناء التشغيل عند الطابع الزمني الذي تبلغ مدته 15 ثانية.

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

const breakManager = playerManager.getBreakManager();

لنبدأ الآن بإعداد أداة اعتراض باستخدام قاعدة لتجاهل أي فواصل إعلانية تحدث قبل 30 ثانية. يعمل هذا النوع من الاعتراض على اعتراض أداة LOAD في PlayerManager، باستثناء أنّ هذا الاعتراض خاص بتحميل مقاطع BreakClips.

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

breakManager.setBreakClipLoadInterceptor((breakClip, breakCtx) => {
  /** Below code will skip playback of break clips if the break position is less than 30 **/
  let breakObj = breakCtx.break;
  if(breakObj.position < 30)
    return null;
  else
    return breakClip;
});

ملاحظة: نحن نعرِض القيمة "فارغ" هنا لـ BreakClips التي يجب تخطّيها.

احفظ التغييرات التي أجريتها على js/receiver.js وابدأ جلسة بث على مُرسِل الويب بالنقر بزر الماوس الأيمن على أي مكان في الصفحة واختيار "البث".

من المفترض أن يبدأ تشغيل البث ولكن سيتم تخطّي حظر الإعلان الذي ظهر سابقًا بعد مرور 15 ثانية.

9. تخصيص سلوك شريط الفاصل

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

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

يتم تمرير دالة رد الاتصال إلى setBreakSeekInterceptor. يتم تمرير دالة معاودة الاتصال كائنًا يحتوي على جميع الفواصل بين الموضع "من" والموضع "إلى".

لنعمل الآن على إعداد أداة اعتراض باستخدام قاعدة لتشغيل فاصل لم تتم مشاهدته من قبل بين الموضع "من" والموضع "إلى".

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

breakManager.setBreakSeekInterceptor(function(breakSeekData) {
     /**
     *
     * Below code will play an unwatched break between 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
     */

    let breakToPlay;
    for (let i = 0; i < breakSeekData.breaks.length; i++) {
        if (!breakSeekData.breaks[i].isWatched) {
            breakToPlay = breakSeekData.breaks[i];
        }
    }
    if (breakToPlay){
        breakSeekData.breaks = [breakToPlay];
        return breakSeekData;
    }
});

ملاحظة: إذا لم نعرض أي محتوى أو كانت قيمة خالية فارغة، لن يتم تشغيل أي فاصل. إذا عرضنا BreakkData كما هو، سيتم تشغيل جميع الفواصل بين "التقديم" و"التقديم".

احفظ التغييرات التي أجريتها على js/receiver.js وابدأ جلسة بث على مُرسِل الويب بالنقر بزر الماوس الأيمن على أي مكان في الصفحة واختيار "البث". من المفترض أن يبدأ بث مصدر الإعلانات على الفور.

10. تهانينا

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

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