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

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

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

מה זה Google Cast?

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

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

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

מה אנחנו מתכוונים לבנות?

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

מה תלמדו

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

מה נדרש

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

ניסיון

לפני שתמשיכו באמצעות ה-Codelab הזה, ודאו שיש לכם את החוויה הבאה.

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

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

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

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

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

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

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

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

הפעלת השרת

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כפי שצוין, ב-Codelab נעשה שימוש באפליקציית שולח כדי להתחיל סשן של Cast, ובאפליקציית מקלט שתשתנה לשימוש בממשקי ה-API של ההפסקות למודעות.

ב-Codelab הזה, כלי ההעברה והפקודות ישמשו כשולח האינטרנטי כדי להפעיל את אפליקציית המקבל. כדי להתחיל, פותחים את הכלי בדפדפן 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 וטעינת נכס וידאו בזמן האתחול. נוספו גם כמה יכולות של יומן ניפוי באגים כדי לספק רישום מחדש לכלי Cast והפקודה.

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

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

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

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

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

מעתיקים את המידע הבא לקובץ js/receiver.js אחרי מיירט בקשות הטעינה. הוא מכיל שישה קטעי VAST של 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 ומעלים את הקובץ לשרת האינטרנט. מתחילים סשן של הפעלת Cast בכלי ההעברה והפקודות על ידי לחיצה על הסמל של הפעלת Cast. מודעות 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 ומעלים את הקובץ לשרת האינטרנט. מתחילים סשן של הפעלת Cast בכלי ההעברה והפקודות על ידי לחיצה על הסמל של הפעלת Cast. יש לעבד את המודעות מסוג VAST. לתשומת ליבכם, מודעות לפני הסרטון (pre-roll) ואמצע הסרטון (mid-roll) הראשונות (שהאורך של position שלהן הוא 15 שניות) לא מופעלות.

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

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

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

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

10. מזל טוב

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

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