הוספת תמיכה ב-Ad Breaks API למקלט אינטרנט

1. סקירה כללית

ב-Codelab הזה מוסבר איך לבנות אפליקציה של מקלט אינטרנט בהתאמה אישית שמשתמשת ב-Cast Ad Breaks API.

מה זה Google Cast?

Google Cast מאפשר למשתמשים להעביר תוכן מהנייד לטלוויזיה. לאחר מכן, המשתמשים יכולים להשתמש בנייד שלהם כשלט רחוק להפעלת מדיה בטלוויזיה.

Google Cast SDK מאפשר לכם להרחיב את האפליקציה כדי לשלוט בטלוויזיה או במערכת סאונד. ה-SDK של Cast מאפשר לך להוסיף את רכיבי ממשק המשתמש הנחוצים על סמך רשימת המשימות לעיצוב של Google Cast.

רשימת המשימות לעיצוב של Google Cast מסופקת כדי לקבוע סטנדרטיזציה של הטמעות של Cast כדי שחוויית המשתמש תהיה אינטואיטיבית בכל הפלטפורמות הנתמכות.

מה אנחנו הולכים ליצור?

בסיום הקודלאב הזה, תיצרו מקלט Cast שמשתמש ב-Break API.

מה תלמדו

• איך לכלול הפסקות VMAP ו-VAST בתוכן להעברה (cast)
• איך מדלגים על קליפים קצרים
• איך להתאים אישית את התנהגות ברירת המחדל של ההפסקות בזמן דילוג

מה נדרש

• דפדפן Google Chrome בגרסה העדכנית ביותר.
• שירות אירוח HTTPS, כמו Firebase Hosting או ngrok.
• מכשיר Google Cast, כמו Chromecast או Android TV, עם הגדרת גישה לאינטרנט.
• טלוויזיה או צג עם יציאת HDMI, או Google Home Hub

ניסיון

לפני שממשיכים בקודלאב הזה, חשוב לוודא שיש לכם את הניסיון הבא:

• ידע כללי בפיתוח אתרים.
• פיתוח אפליקציות Cast Web Receiver.

2. קבלת קוד לדוגמה

מורידים את כל דוגמאות הקוד למחשב…

file_downloadהורדת קוד המקור

ופותחים את קובץ ה-ZIP שהורדתם.

3. פריסה מקומית של המקבל

כדי שתוכלו להשתמש במקלט האינטרנט עם מכשיר Cast, הוא צריך להיות מתארח במקום שבו מכשיר ה-Cast יכול להגיע אליו. אם כבר יש לכם שרת זמין שתומך ב-https, דלגו על ההוראות הבאות ושימו לב לכתובת ה-URL, כי תצטרכו אותה בקטע הבא.

אם אין לכם שרת זמין לשימוש, תוכלו להשתמש ב-אירוח ב-Firebase או ב-ngrok.

הפעלת השרת

אחרי שמגדירים את השירות שבחרתם, עוברים אל app-start ומפעילים את השרת.

כותבים לעצמכם את כתובת ה-URL של המקלט המתארח. תשתמשו בו בקטע הבא.

4. רישום אפליקציה ב-Cast Developer Console

עליך לרשום את האפליקציה כדי שתוכל להפעיל מקלט מותאם אישית, כפי שהוא מובנה ב-Codelab הזה, במכשירי Chromecast. אחרי שתירשמו את האפליקציה, ייווצר מזהה אפליקציה שצריך להגדיר באפליקציית השולח כדי להפעיל את אפליקציית מקלט האינטרנט.

לוחצים על 'הוספת אפליקציה חדשה'.

צריך לבחור באפשרות 'מקלט מותאם אישית', זה מה שאנחנו מפתחים.

מזינים את הפרטים של המקבל החדש. חשוב להשתמש בכתובת ה-URL שמפנה לאתר שבו אתם מתכננים לארח את אפליקציית Web Receiver. צריך לרשום לפניכם את מזהה האפליקציה שנוצר על ידי המסוף אחרי רישום האפליקציה. אפליקציית השולח תוגדר לשימוש במזהה הזה בקטע מאוחר יותר.

לפני הפרסום, צריך גם לרשום מכשיר Google Cast כדי שיהיה לו גישה לאפליקציית המקלט. לאחר פרסום אפליקציית המקבל, היא תהיה זמינה לכל מכשירי Google Cast. למטרות ה-Codelab הזה, מומלץ לעבוד עם אפליקציית מקלט שלא פורסמה.

לוחצים על 'הוספת מכשיר חדש'.

מזינים את המספר הסידורי שמודפס על גב מכשיר ההעברה (cast) ומעניקים לו שם תיאורי. אפשר גם למצוא את המספר הסידורי על ידי העברה (cast) של המסך ב-Chrome כשנכנסים אל Google Cast SDK Developer Console.

תוך 5 עד 15 דקות, המקלט והמכשיר יהיו מוכנים לבדיקה. אחרי שממתינים 5 עד 15 דקות, צריך להפעיל מחדש את מכשיר ה-Cast.

5. מכינים את הפרויקט לתחילת הפרויקט

לפני שמתחילים את סדנת הקוד הזו, מומלץ לעיין במדריך למפתחי מודעות, שמספק סקירה כללית על ממשקי ה-API של הפסקות למודעות.

צריך להוסיף תמיכה ב-Google Cast לאפליקציית ההתחלה שהורדתם. ריכזנו כאן כמה מונחים של Google Cast שמופיעים בקודלאב הזה:

• אפליקציית שליחת הודעות שפועלת במכשיר נייד או במחשב נייד,
• אפליקציית מקלט פועלת במכשיר Google Cast.

עכשיו אתם מוכנים להתחיל להשתמש בפרויקט לתחילת העבודה באמצעות עורך הטקסט המועדף עליכם:

1. בוחרים את הספרייה app-start מההורדה של קוד לדוגמה.
2. פותחים את js/receiver.js ואת index.html

חשוב לזכור: במהלך העבודה ב-codelab הזה, עליכם לעדכן את פתרון אירוח האינטרנט שבחרתם עם השינויים שביצעתם. חשוב לוודא שאתם מעבירים את השינויים לאתר המארח כשאתם ממשיכים לאמת ולבדוק אותם.

עיצוב אפליקציות

כפי שצוין, ב-codelab נעשה שימוש באפליקציית שולחת כדי להתחיל סשן העברה (cast), ובאפליקציית מקלט שתשתנה כדי להשתמש בממשקי ה-API של ההפסקות למודעות.

בסדנת הקוד הזו, כלי ההעברה והפקודה ישמש ככלי לשליחת נתונים לאינטרנט כדי להפעיל את אפליקציית המכשיר המקבל. כדי להתחיל, פותחים את הכלי בדפדפן Chrome. מזינים את מזהה האפליקציה של המקבל שקיבלתם ב-Cast SDK Console ולוחצים על Set כדי להגדיר את אפליקציית השולח לבדיקה.

הערה: אם הסמל להפעלת Cast לא מופיע, צריך לוודא שמקלט האינטרנט ומכשירי ה-Cast רשומים כראוי ב-Cast Console. אם עדיין לא עשיתם זאת, צריך להפעיל מחדש את כל מכשירי ההעברה (cast) שרשומים עכשיו.

אפליקציית המקבל היא המוקד העיקרי ב-Codelab הזה, ומורכבת מתצוגה ראשית אחת שמוגדרת ב-index.html ומקובץ JavaScript אחד בשם js/receiver.js. בהמשך מוסבר בהרחבה על האפשרויות האלה.

index.html

קובץ ה-HTML הזה מכיל את ממשק המשתמש של אפליקציית המקלט שלנו, שמסופק על ידי הרכיב cast-media-player. הוא גם טוען את ספריות CAF SDK ו-Cast Debug Logger.

receiver.js

הסקריפט הזה מנהל את כל הלוגיקה של אפליקציית המקבל. בשלב הזה, הוא מכיל מקלט CAF בסיסי לאתחול ההקשר של הפעלת Cast וטעינת נכס וידאו בזמן האתחול. הוספנו גם כמה יכולות של יומן ניפוי באגים כדי לספק רישום ביומן בחזרה לכלי ההעברה והפקודה.

6. הוספת VMAP לתוכן

ה-SDK של מקלט האינטרנט של Cast מספק תמיכה במודעות שצוינו באמצעות פלייליסטים של מספר מודעות בווידאו דיגיטלי, שנקראים גם VMAP. המבנה של קובץ ה-XML מציין את ההפסקות למודעות של המדיה ואת המטא-נתונים של קטע ההפסקה המשויך. כדי להוסיף את המודעות האלה, ערכת ה-SDK מספקת את המאפיין vmapAdsRequest באובייקט MediaInformation.

בקובץ js/receiver.js, יוצרים אובייקט VastAdsRequest. מאתרים את הפונקציה LOAD ליירוט בקשות ומחליפים אותה בקוד הבא. היא מכילה כתובת 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 ומעלים את הקובץ לשרת האינטרנט. מתחילים סשן של הפעלת Cast בכלי ההעברה והפקודות על ידי לחיצה על הסמל של הפעלת Cast. המודעות ב-VMAP אמורות לפעול, ולאחר מכן התוכן הראשי.

7. הוספת VAST לתוכן שלך

כפי שצוין קודם, יש תמיכה בסוגים רבים של מודעות ב-Web Receiver SDK. בקטע הזה נסקור את ממשקי ה-API שזמינים לשילוב מודעות מסוג תבנית לפרסום מודעות וידאו דיגיטליות, שנקראות גם VAST. אם הטמעתם את קוד ה-VMAP מהקטע הקודם, צריך להוסיף לו הערה.

מעתיקים את הקוד הבא לקובץ js/receiver.js אחרי מנטרה החסימה של בקשת הטעינה. הוא מכיל שישה קטעי הפסקות VAST מ-DoubleClick וערך מתאם אקראי. קטעי הווידאו האלה מוקצים ל-5 הפסקות. השדה position של כל הפסקה מוגדר כזמן בשניות ביחס לתוכן הראשי, כולל הפסקות של מודעות Pre-roll (position מוגדר כ-0) והפסקות של מודעות Post-roll (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 הפסקות: עצירה אחת לפני הסרטון (pre-roll), 3 הפסקות למודעות באמצע הסרטון (15, 60 ו-100 שניות), ולבסוף, הפסקה אחת בסוף הסרטון. לאחר השלמת השלבים, המערכת תדלג רק על מודעות לפני הסרטון (pre-roll) ומודעות באמצע הסרטון (mid-roll) שהמיקום שלהן הוא 15 שניות.

כדי לעשות זאת, האפליקציה צריכה לקרוא לממשקי API שזמינים דרך 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. הערה: המודעות מסוג pre-roll וmid-roll הראשונה (ש-position שלהן הוא 15 שניות) לא יוצגו.

9. התאמה אישית של התנהגות החיפוש בפסקה

כשמבצעים דילוג על הפסקות, הטמעת ברירת המחדל מקבלת את כל הפריטים של Break שהמיקום שלהם נמצא בין הערכים seekFrom ו-seekTo של פעולת הדילוג. מתוך רשימת ההפסקות הזו, ה-SDK מפעיל את ה-Break שהערך של position שלו קרוב ביותר לערך seekTo, ושהערך של המאפיין isWatched שלו מוגדר כ-false. לאחר מכן, המאפיין isWatched של ההפסקה הזו מוגדר ל-true והנגן מתחיל להפעיל את קליפי ההפסקה שלו. אחרי הצפייה בהפסקה, ההפעלה של התוכן הראשי תתחדש מהמיקום seekTo. אם אין הפסקה כזו, לא תופעל הפסקה והתוכן הראשי ימשיך לפעול במיקום seekTo.

כדי להתאים אישית את ההפסקות שיופיעו במהלך דילוג, ה-SDK של Cast מספק את ה-API setBreakSeekInterceptor בקטע BreakManager. כשאפליקציה מספקת את הלוגיקה המותאמת אישית שלה באמצעות ממשק ה-API הזה, ה-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. הערה: המודעות מסוג pre-roll וmid-roll הראשונה (ש-position שלהן הוא 15 שניות) לא יוצגו.

צריך להמתין עד שזמן ההפעלה יגיע ל-30 שניות כדי לעבור את כל ההפסקות שמערכת הצפנה של טעינה של קליפ ההפסקה מדלגת עליהן. כשמגיעים למקום הרצוי, מנווטים לכרטיסייה Media Control (אמצעי בקרת מדיה) ושולחים פקודה לדילוג. מאכלסים את הקלט Seek Into Media ב-300 שניות ולוחצים על הלחצן TO. שימו לב ליומנים שמודפסים ב-Break Seek Interceptor. עכשיו צריך לשנות את ברירת המחדל כדי להפעיל את ההפסקה קרוב יותר לשעה seekFrom.

10. מזל טוב

עכשיו אתם יודעים איך להוסיף מודעות לאפליקציית המקלט באמצעות ערכת ה-SDK העדכנית של Cast Receiver.

פרטים נוספים זמינים במדריך למפתחים בנושא הפסקות למודעות.