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

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

ב-codelab הזה מוסבר איך ליצור אפליקציית Custom Web Receiver שמשתמשת ב-Cast Ad Breaks API.

מה זה Google Cast?

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

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

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

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

בסיום ה-codelab הזה, תהיה לכם אפליקציית Cast Receiver שמנצלת את Break API.

מה תלמדו

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

הדרישות

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

חוויה

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ב-codelab הזה, הכלי Cast and Command ישמש כ-Web Sender להפעלת אפליקציית המקלט. כדי להתחיל, פותחים את הכלי בדפדפן Chrome. מזינים את מזהה אפליקציית המקלט שקיבלתם ב-Cast SDK Developer Console ולוחצים על הגדרה כדי להגדיר את אפליקציית השולח לבדיקה.

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

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

index.html

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

receiver.js

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

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

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

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

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

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

8. דילוג על הפסקות למודעות

ל-CAF יש מחלקה בשם BreakManager שעוזרת לכם להטמיע כללים עסקיים מותאמים אישית להתנהגויות של מודעות. אחת מהתכונות האלה מאפשרת לאפליקציות לדלג באופן פרוגרמטי על הפסקות ועל קטעי הפסקות בהתאם לתנאי מסוים. בדוגמה הזו אפשר לראות איך לדלג על הפסקה למודעות שמוצבת ב-30 השניות הראשונות של התוכן, אבל לא על הפסקות למודעות מסוג פוסט-רול. כשמשתמשים במודעות VAST שהוגדרו בקטע הקודם, מוגדרות 5 הפסקות: הפסקה אחת לפני הסרטון, 3 הפסקות באמצע הסרטון (ב-15, ב-60 וב-100 שניות), ולבסוף, הפסקה אחת בסוף הסרטון. אחרי שמבצעים את השלבים, המערכת מדלגת רק על המודעה לפני הסרטון ועל המודעה באמצע הסרטון שהמיקום שלהן הוא 15 שניות.

לשם כך, האפליקציה צריכה לשלוח קריאות לממשקי API שזמינים דרך BreakManager כדי להגדיר interceptor לטעינת הפסקה. מעתיקים את השורה הבאה לקובץ js/receiver.js, אחרי השורות שמכילות את המשתנים context ו-playerManager, כדי לקבל הפניה למופע.

const breakManager = playerManager.getBreakManager();

באפליקציה צריך להגדיר interceptor עם כלל להתעלמות מהפסקות פרסום שמתרחשות לפני 30 שניות, תוך התחשבות בהפסקות פרסום שמוצגות אחרי הסרטון (כי הערכים שלהן הם position). ה-interceptor הזה פועל כמו ה-interceptor של LOAD ב-PlayerManager, אבל הוא ספציפי לטעינה של קליפים של הפסקות פרסום.-1 צריך להגדיר את זה אחרי מיירט בקשות 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 ופקודה על ידי לחיצה על סמל Cast. המודעות בפורמט VAST יעברו עיבוד. שימו לב שהמודעות לפני הסרטון והמודעה הראשונה באמצע הסרטון (שאורכה 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 ופקודה על ידי לחיצה על סמל Cast. המודעות בפורמט VAST יעברו עיבוד. שימו לב שהמודעות לפני הסרטון והמודעה הראשונה באמצע הסרטון (שאורכה position הוא 15 שניות) לא מוצגות.

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

10. מזל טוב

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

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