1. סקירה כללית
ב-Codelab הזה מוסבר איך ליצור אפליקציה מותאמת אישית של Web Receiver שמשתמשת ב-Cast Ad Breaks API.
מה זה Google Cast?
Google Cast מאפשר למשתמשים להעביר (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 Web Receiver.
איך ייעשה שימוש במדריך הזה?
איזה דירוג מגיע לדעתך לחוויה שלך בבניית אפליקציות אינטרנט?
2. לקבלת הקוד לדוגמה
הורד את כל הקוד לדוגמה למחשב...
ופורקים את קובץ ה-ZIP שהורד.
3. פריסה מקומית של הנמען
כדי להשתמש במקלט האינטרנט עם מכשיר CAST, הוא צריך להתארח במקום שבו מכשיר ה-CAST יכול להגיע אליו. אם כבר יש לכם שרת זמין שתומך ב-https, דלגו על ההוראות הבאות ושימו לב לכתובת ה-URL, מכיוון שתזדקקו לה בקטע הבא.
אם אין לכם אף שרת שאפשר להשתמש בו, אפשר להשתמש באירוח ב-Firebase או ב-ngrok.
הפעלת השרת
אחרי שמגדירים את השירות הרצוי, עוברים אל app-start ומפעילים את השרת.
לרשום לפניכם את כתובת ה-URL של המקבל המתארח. אתם תשתמשו בה בקטע הבא.
4. רישום אפליקציה ב-Cast Developer Console
עליך לרשום את האפליקציה כדי שתוכל להפעיל מקלט בהתאמה אישית, כמו ה-Codelab המובנה הזה, במכשירי Chromecast. לאחר רישום האפליקציה, יווצר מזהה אפליקציה שצריך להגדיר את אפליקציית השולח כדי להפעיל את האפליקציה Web Receiver.
לחץ על 'הוסף אפליקציה חדשה'
בוחרים באפשרות 'Custom Receiver', זה מה שאנחנו יוצרים.
מזינים את הפרטים של הנמען החדש. יש להקפיד להשתמש בכתובת ה-URL שמפנה אל המקום שבו אתם מתכננים לארח את אפליקציית Web Receiver. צריך לרשום את מזהה האפליקציה שנוצר על ידי המסוף אחרי שרשמת את האפליקציה. אפליקציית השולח תוגדר להשתמש במזהה הזה בקטע מאוחר יותר.
עליך גם לרשום מכשיר Google 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 הזה:
- אפליקציית שולח פועלת במכשיר נייד או במחשב נייד,
- אפליקציית מקלט פועלת במכשיר Google Cast.
עכשיו תוכלו להתחיל לעבוד על הפרויקט למתחילים באמצעות עורך הטקסט המועדף עליכם:
- בוחרים את הספרייה
app-startמהורדת הקוד לדוגמה. - פתיחת
js/receiver.jsו-index.html
לתשומת ליבך, בזמן העבודה על ה-Codelab הזה, פתרון האירוח באינטרנט שבחרת אמור להתעדכן בשינויים שיבוצעו. כשממשיכים לאמת ולבדוק אותם, חשוב לוודא שיש לבצע את השינויים באתר המארח.
עיצוב אפליקציות
כפי שצוין, ב-Codelab נעשה שימוש באפליקציית שולח כדי להתחיל סשן העברה ובאפליקציית המקבל, שתשתנה כך שתשתמש בממשקי ה-API של ההפסקות למודעות.
ב-Codelab הזה, כלי ההעברה והפקודות ישמשו כשולח האינטרנט כדי להפעיל את האפליקציה המקבלת. כדי להתחיל, צריך לפתוח את הכלי בדפדפן Chrome. עליך להזין את מזהה האפליקציה של המקבל שקיבלת ב-Cast SDK Developer Console וללחוץ על Set כדי להגדיר את אפליקציית השולח לבדיקה.
הערה: אם סמל ההעברה(cast) לא מופיע, יש לוודא שמקלט האינטרנט ומכשירי ה-CAST רשומים כראוי ב-Cast Developer Console. אם עדיין לא עשית זאת, עליך להפעיל מחדש את כל מכשירי ה-CAST שנרשמו לאחרונה.
אפליקציית המקבל היא המטרה העיקרית של ה-Codelab הזה, והיא כוללת תצוגה ראשית אחת שהוגדרה ב-index.html וקובץ JavaScript אחד שנקרא js/receiver.js. בהמשך מפורט בהרחבה.
index.html
קובץ ה-HTML הזה מכיל את ממשק המשתמש של אפליקציית המקבל, שסופק על ידי הרכיב cast-media-player. היא גם טוענת את הספריות CAF SDK ו-Cast Debug Logger.
receiver.js
הסקריפט הזה מנהל את כל הלוגיקה של אפליקציית המקבל. בשלב זה, הוא מכיל מקלט CAF בסיסי לאתחול ההקשר של ההעברה וטעינת נכס וידאו במהלך האתחול. הוספנו גם יכולות מסוימות של יומן ניפוי באגים כדי לאפשר התחברות מחדש לכלי ההעברה והפקודות.
6. הוספת VMAP לתוכן
ה-SDK של Cast Web Receiver תומך במודעות שצוינו באמצעות פלייליסטים של מודעות וידאו מרובות בסרטונים, שנקראים גם 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) באמצעות כלי ההעברה והפקודות על ידי לחיצה על סמל ההעברה. צריך להציג את מודעות ה-VMAP, ולאחר מכן את התוכן העיקרי.
7. הוספת VAST לתוכן שלך
כפי שצוין קודם, יש תמיכה בסוגים רבים של מודעות ב-Web Receiver 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) באמצעות כלי ההעברה והפקודות על ידי לחיצה על סמל ההעברה. יש להפעיל את מודעות ה-VAST ואז את התוכן הראשי.
8. דילוג על הפסקות למודעה
ב-CAF יש שיעור בשם BreakManager שעוזר לך להטמיע כללים עסקיים מותאמים אישית עבור התנהגות של מודעות. אחת התכונות האלה מאפשרת לאפליקציות לדלג באופן פרוגרמטי על הפסקות ולשבור קליפים בהתאם לתנאי מסוים. בדוגמה הזו מוסבר איך לדלג על הפסקה למודעה שהמיקום שלה הוא ב-30 השניות הראשונות של התוכן, אך לא על ההפסקות למודעות בסוף הסרטון (post-roll). כשמשתמשים במודעות VAST שהוגדרו בקטע הקודם, מוגדרות 5 הפסקות: הפסקה אחת למודעה לפני הסרטון (pre-roll), 3 הפסקות באמצע הסרטון (במשך 15, 60 ו-100 שניות) ולבסוף, הפסקה אחת למודעה בסוף הסרטון. אחרי שמשלימים את השלבים, המערכת מדלגת רק על מודעות לפני סרטון ומודעה באמצע סרטון, שהמיקום שלהן הוא 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) באמצעות כלי ההעברה והפקודות על ידי לחיצה על סמל ההעברה. יש לעבד את מודעות ה-VAST. לידיעתכם, המודעות לפני הסרטון ומודעות באמצע הסרטון (mid-roll) הראשונות (שאורכו position הן 15 שניות) לא מופעלות.
9. התאמה אישית של התנהגות חיפוש ההפסקות
כשמחפשים הפסקות קודמות, הטמעת ברירת המחדל משיגה את כל הפריטים של Break שהמיקום שלהם נמצא בין הערכים seekFrom ו-seekTo של הפעולה המבוקשת. מתוך רשימת ההפסקות הזו, ערכת ה-SDK מפעילה את Break שהposition הכי קרוב לערך seekTo ושנכס isWatched שלו מוגדר ל-false. לאחר מכן המאפיין isWatched של ההפסקה הזו מוגדר ל-true והנגן מתחיל את קטעי ההפסקה. לאחר צפייה בהפסקה, ההפעלה של התוכן הראשי תתחדש מהמיקום seekTo. אם לא קיימת הפסקה כזו, לא תופעל הפסקה והתוכן הראשי ימשיך לפעול במיקום seekTo.
כדי להתאים אישית את ההפסקות שניתן להפעיל במהלך דילוג, Cast SDK מספק את setBreakSeekInterceptor API ב-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) באמצעות כלי ההעברה והפקודות על ידי לחיצה על סמל ההעברה. יש לעבד את מודעות ה-VAST. לידיעתכם, המודעות לפני הסרטון ומודעות באמצע הסרטון (mid-roll) הראשונות (שאורכו position הן 15 שניות) לא מופעלות.
ממתינים עד שזמן ההפעלה יגיע ל-30 שניות כדי לעבור את כל ההפסקות שהמערכת מדלגת עליהן על ידי מיירט הטעינה של קליפ ההפסקה. לאחר שתגיע אל הכרטיסייה, שלח פקודת חיפוש על ידי ניווט אל הכרטיסייה בקרת מדיה. מאכלסים את הקלט Seek Into Media ב-300 שניות ולוחצים על הלחצן TO. שימו לב ליומנים שמודפסים על מפַתח העצירה. עכשיו צריך לבטל את התנהגות ברירת המחדל כדי להשמיע את ההפסקה קרוב יותר לשעה seekFrom.
10. מזל טוב
עכשיו ידוע לך איך להוסיף מודעות לאפליקציית המקבל באמצעות ה-SDK האחרון של המקבל.
פרטים נוספים זמינים במדריך למפתחים בנושא הפסקות למודעות.