דף זה תורגם על ידי Cloud Translation API.

תחילת העבודה עם IMA DAI SDK

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

בחירת פתרון ה-DAI הרצוי

הפעלת שידורים חיים שנרשמו באמצעות Google Cloud Video Stitcher API

במדריך הזה נסביר איך להשתמש ב-IMA DAI SDK ל-HTML5 כדי לבקש ולנגן שידור חי של אירוע שרשום ב-Google Cloud Video Stitcher API, ואיך להוסיף הפסקה למודעה במהלך ההפעלה.

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

מידע על שילוב עם פלטפורמות אחרות או על שימוש ב-SDK של IMA בצד הלקוח זמין במאמר ערכות SDK של מודעות Interactive Media.

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

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

איך מגדירים פרויקט ב-Google Cloud ומגדירים חשבונות שירות כדי לגשת לפרויקט

יוצרים הגדרה לאירוע בשידור חי באמצעות שידור חי של תוכן משלכם או שידור חי לבדיקה. במדריך הזה אנחנו יוצאים מנקודת הנחה שמדובר בשידור HLS.

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

מיקום

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

מספר הפרויקט

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

טוקן OAuth

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

OAUTH_TOKEN

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

קוד רשת

קוד הרשת של Ad Manager לשליחת בקשות להצגת מודעות: NETWORK_CODE

מזהה התצורה בשידור חי: מזהה ההגדרה של השידור החי שציינתם כשיצרתם את האירוע בשידור חי: LIVE_CONFIG_ID
מפתח נכס מותאם אישית: מפתח הנכס בהתאמה אישית ב-Ad Manager שנוצר במהלך התהליך של יצירת הגדרה לאירוע של שידור חי באמצעות Video Stitcher API:‏CUSTOM_ASSET_KEY

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

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

type: מחרוזת שצריך להגדיר לערך 'ID3' בשידורי HLS ולערך 'urn:google:dai:2018' בשידורי DASH.
data: בהודעות אירוע של DASH, זוהי מחרוזת נתוני ההודעה.
timestamp: מספר שמציין את שעת ההתחלה של הודעת האירוע בסטרימינג של DASH.

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

מורידים את הדוגמאות ל-IMA DAI עבור HTML5 ומחלצים את הדוגמה הפשוטה של HLS.js לתיקייה חדשה. הדוגמה הזו היא אפליקציית אינטרנט שאפשר לארח באופן מקומי למטרות בדיקה.

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

python3 -m http.server 8000

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

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

אם הכל פועל כמו שצריך, לחיצה על הלחצן הפעלה בנגן הווידאו תפעיל את הסרט הקצר 'דמעות של פלדה' אחרי מודעה קצרה. התוכן הזה מועבר באמצעות שידור של וידאו על פי דרישה (VOD).

שליחת בקשה לשידור חי

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

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

לדוגמה:

// StreamManager which will be used to request ad-enabled 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() {
  requestVideoStitcherStream();

  playButton.style.display = "none";
  playButton.removeEventListener('click', initiatePlayback);
  playButton.addEventListener('click', resumePlayback);
}
...

function requestVideoStitcherStream() {
  const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest();
  streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID';
  streamRequest.region = 'LOCATION';
  streamRequest.projectNumber = 'PROJECT_NUMBER';
  streamRequest.oAuthToken = 'OAUTH_TOKEN';
  streamRequest.networkCode = 'NETWORK_CODE';
  streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY';

  streamManager.requestStream(streamRequest);
}

לצורך בדיקה מקומית, אם קובצי השידור החי נמצאים בקטגוריה של Cloud Storage, צריך להפעיל את CORS למקור http://localhost:8000.

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

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

כדי להתאים אישית את בקשת הסטרימינג, מוסיפים אפשרויות סשן כדי לשנות את הגדרת ברירת המחדל של Cloud Video Stitcher API באמצעות VideoStitcherLiveStreamRequest.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": {
    "includeRenditions": [
      {"bitrateBps": 3000, "codecs": "hvc1.1.4.L126.B0, mp4a.40.2"},
      {"bitrateBps": 2000, "codecs": "avc1.64001f, mp4a.40.2"},
    ],
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);

הוספת הפסקה למודעה

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

אם אתם משתמשים בשידור חי משלכם, עליכם להוסיף את סמן המודעה. למידע נוסף על סמני המודעות הנתמכים ב-HLS וב-DASH, קראו את מסמכי העזרה בנושא סמני מודעות.
אם יצרתם שידור חי באמצעות Google Cloud Livestream API, תוכלו להוסיף אירוע ערוץ של הפסקה למודעה.

המודעה מופעלת מיד אחרי שמוסיפים את ההפסקה למודעות.

הסרת המשאבים

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

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

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