איך מתחילים לעבוד עם IMA SDK ל-DAI

בחירת פלטפורמה: HTML5 Android iOS tvOS Cast Roku

ערכות IMA SDK מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות. ערכות IMA SDK יכולות לבקש מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות שלכם. בעזרת ערכות ה-SDK של IMA DAI, אפליקציות שולחות בקשה לשידור של מודעות ותוכן וידאו – תוכן VOD או תוכן בשידור חי. לאחר מכן, ה-SDK מחזיר שידור וידאו משולב, כך שלא צריך לנהל את המעבר בין מודעת הווידאו לבין תוכן הווידאו באפליקציה.

בוחרים את פתרון ה-DAI המועדף:

• הגדרה עם DAI בשירות מלא: מערכת Google Ad Manager בוחרת מודעות ומוסיפה אותן ישירות לסטרימינג של התוכן שלכם.
• הגדרה עם DAI להצגת רצפי מודעות: מערכת Google Ad Manager מספקת רצפי מודעות שאפשר להוסיף או לטעון לנגן וידאו.

Cloud stitching API Live Cloud stitching API VOD

הפעלת שידורי וידאו על פי דרישה (VOD) שרשומים ב-Google Cloud Video Stitcher API

במדריך הזה מוסבר איך להשתמש ב-IMA DAI SDK ל-HTML5 כדי לבקש ולהפעיל סשן של שידור וידאו על פי דרישה (VOD) ב-Google Cloud.

המדריך הזה מרחיב את הדוגמה הבסיסית מהמדריך למתחילים של IMA DAI.

כדי לקבל מידע על שילוב עם פלטפורמות אחרות או על שימוש בערכות IMA SDK בצד הלקוח, עיינו במאמר Interactive Media Ads SDKs.

כדי לראות או לעקוב אחרי שילוב לדוגמה שהושלם, הורידו את הדוגמה של Cloud Video Stitcher ל-HLS או ל-DASH.

הערה: ‫IMA DAI SDK ל-HTML5 תומך גם בסטרימינג ב-HLS וגם ב-DASH, אבל כדי להפעיל כל אחד מהם צריך נגן מדיה או תוסף שונים, כמו HLS.js או DASH.js, עם הטמעות שונות.

במדריך הזה מוסבר איך להגדיר את HLS.js ואת IMA DAI SDK כדי להפעיל שידור HLS, עם הערות חשובות לגבי הבדלים בהטמעה של DASH.

באפליקציה לדוגמה IMA DASH.js מוסבר איך להתחיל להטמיע שידורי DASH DAI באמצעות IMA.

הגדרת פרויקט ב-Google Cloud

הגדרת פרויקט בענן ב-Google Cloud והגדרת חשבונות שירות כדי לגשת לפרויקט.

מזינים את המשתנים הבאים לשימוש ב-IMA SDK:

מיקום

האזור ב-Google Cloud שבו נוצרה הגדרת ה-VOD: LOCATION

מספר הפרויקט

מספר הפרויקט בענן של Google שבו משתמשים ב-Video Stitcher API:PROJECT_NUMBER

טוקן OAuth

אסימון OAuth לטווח קצר של חשבון שירות עם תפקיד המשתמש Video Stitcher:

OAUTH_TOKEN

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

קוד רשת

קוד הרשת של Ad Manager לבקשת מודעות: NETWORK_CODE

מזהה ההגדרה של VOD

מזהה ההגדרה של שידור ה-VOD: VOD_CONFIG_ID

מידע נוסף על יצירת מזהה הגדרות אישיות של VOD זמין במדריך ליצירת הגדרות אישיות של VOD באמצעות Cloud Stitching.

הגדרת סביבת פיתוח

נקודה חשובה: המחלקה VideoStitcherVodStreamRequest של IMA DAI תומכת גם בסטרימינג ב-HLS וגם בסטרימינג ב-DASH עם כמה תקופות. ההפסקות למודעות מוכנסות רק בין מקטעי DASH.

האפליקציות לדוגמה של IMA מדגימות רק בקשות לשידור HLS. עדיין אפשר להשתמש בסטרימינג ב-DASH כשיוצרים את המחלקה VideoStitcherVodStreamRequest. כשמגדירים נגן שתואם ל-DASH, צריך להגדיר מאזין לאירועי ההתקדמות של נגן הווידאו, שיכול לספק את המטא-נתונים של הסרטון ל-StreamManager.processMetadata(). הפונקציה הזו מקבלת שלושה פרמטרים:

1. ‫type: מחרוזת שצריך להגדיר לערך 'ID3' בשידורי HLS ולערך 'urn:google:dai:2018' בשידורי DASH.

2. ‫data: בהודעות אירוע של DASH, זוהי מחרוזת הנתונים של ההודעה.

3. ‫timestamp: מספר שמייצג את שעת ההתחלה של הודעת האירוע בשידורי DASH.

שלחו את המטא-נתונים בתדירות גבוהה ככל האפשר, בהתאם לנתונים שמתקבלים מהפעולות במשחק. אם המטא-נתונים חסרים או שגויים, יכול להיות שערכת IMA DAI SDK לא תפעיל אירועי מודעות, וכתוצאה מכך הדיווח על אירועי המודעות יהיה שגוי.

מורידים את הדוגמאות של IMA DAI ל-HTML5 ומחלצים את קובץ ה-ZIP לדוגמה hls_js/simple לתיקייה חדשה. הדוגמה הזו היא אפליקציית אינטרנט שאפשר לארח באופן מקומי למטרות בדיקה.

כדי לארח את הדוגמה באופן מקומי, עוברים לתיקייה החדשה ומריצים את פקודת Python הבאה כדי להפעיל שרת אינטרנט:

python3 -m http.server 8000

‫http.server זמין רק ב-Python 3.x. אפשר להשתמש בכל שרת אינטרנט אחר, כמו Apache HTTP Server או Node JS.

פותחים דפדפן אינטרנט ועוברים אל localhost:8000 כדי לראות נגן וידאו. הדפדפן צריך לתמוך בספרייה HLS.js.

אם הכול פועל כמו שצריך, לחיצה על הלחצן הפעלה בנגן הווידאו תפעיל את הסרט הקצר Tears of Steel, עם הפסקות למודעות כל 30 שניות.

בקשה לשידור וידאו על פי דרישה (VOD)

כדי להחליף את הסטרימינג לדוגמה בסטרימינג של VOD עם מודעות, משתמשים בכיתה VideoStitcherVodStreamRequest כדי ליצור באופן אוטומטי ביקור עם חשיפה למודעות באמצעות Google Ad Manager. אתם יכולים להשתמש בממשק המשתמש של Google Ad Manager כדי לאתר את הסשנים שנוצרו ב-DAI לצורך מעקב וניפוי באגים.

בדוגמה הקיימת יש פונקציות לבקשת שידור VOD או שידור חי. כדי שהיא תעבוד עם Google Cloud Video Stitcher API, צריך להוסיף פונקציה חדשה שתחזיר אובייקט VideoStitcherVodStreamRequest.

לדוגמה:

// StreamManager which will be used to request DAI streams.
let streamManager;
...

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(
    videoElement,
    adUiElement
  );
  streamManager.addEventListener(
    [
      google.ima.dai.api.StreamEvent.Type.LOADED,
      google.ima.dai.api.StreamEvent.Type.ERROR,
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED
    ],
    onStreamEvent, false);

  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });

  videoElement.addEventListener('pause', () => {
    playButton.style.display = "block";
  });

  playButton.addEventListener('click', initiatePlayback);
}

function initiatePlayback() {
  requestVodVideoStitcherStream();

  playButton.style.display = "none";
  playButton.removeEventListener('click', initiatePlayback);
  playButton.addEventListener('click', resumePlayback);
}
...
function requestVodVideoStitcherStream() {
  const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest();
  streamRequest.vodConfigId = 'VOD_CONFIG_ID';
  streamRequest.region = 'LOCATION';
  streamRequest.projectNumber = 'PROJECT_NUMBER';
  streamRequest.oAuthToken = 'OAUTH_TOKEN';
  streamRequest.networkCode = 'NETWORK_CODE';

  streamManager.requestStream(streamRequest);
}

טוענים מחדש את הדף. לאחר מכן, אתם יכולים לבקש ולהפעיל את שידור ה-VOD בהתאמה אישית.

(אופציונלי) הוספת אפשרויות לסשן הסטרימינג

כדי להתאים אישית את בקשת הסטרימינג, אפשר להוסיף אפשרויות סשן שיחליפו את הגדרת ברירת המחדל של Cloud Video Stitcher API באמצעות VideoStitcherVodStreamRequest.videoStitcherSessionOptions. אם תציינו אפשרות לא מזוהה, Cloud Video Stitcher API יחזיר שגיאת HTTP 400. אפשר להיעזר במדריך לפתרון בעיות.

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

...

// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
  "manifestOptions": {
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);

הסרת המשאבים

אחרי שאירחתם בהצלחה שידור VOD באמצעות Google Cloud Video Stitcher API וביקשתם אותו באמצעות IMA DAI SDK ל-HTML5, חשוב לנקות את כל משאבי ההצגה.

כדי להסיר משאבים ונכסים מיותרים, פועלים לפי ההוראות במדריך ניקוי VOD.

לסיום, בחלון הטרמינל שבו הפעלתם את שרת האינטרנט של Python 3, משתמשים בפקודה ctrl+C כדי לסיים את השרת המקומי.