הגדרת IMA SDK ל-DAI

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

בחירת פתרון DAI שמעניין אתכם

DAI בשירות מלא

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

לפני שמשתמשים במדריך הזה, חשוב להכיר את פרוטוקול Web Receiver של Chromecast Application Framework. במדריך הזה אנחנו מניחים שיש לכם ידע בסיסי במושגים של CAF Receiver, כמו message interceptors ואובייקטים של mediaInformation, וגם שאתם יודעים להשתמש בכלי Cast Command and Control כדי לבצע אמולציה של CAF Sender.

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

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

סקירה כללית על CAF DAI

הטמעה של DAI באמצעות IMA CAF DAI SDK כוללת שני רכיבים עיקריים, כפי שמוצג במדריך הזה:

  • ‫StreamRequest: אובייקט שמגדיר בקשת סטרימינג לשרתי הפרסום של Google. בקשות לשידור מגיעות בשני סוגים עיקריים:

    • ‫LiveStreamRequest: מציין מפתח נכס, וגם פרמטרים אופציונליים אחרים.
    • ‫VODStreamRequest: מציין מזהה של מקור תוכן, מזהה של סרטון ופרמטרים אופציונליים אחרים.
    • שני סוגי הבקשות יכולים לכלול גם מפתח API שנדרש כדי לגשת לסטרימינג שצוין, וגם קוד רשת של Google Ad Manager כדי ש-IMA SDK יוכל לטפל במזהי מודעות כמו שצוין בהגדרות של Google Ad Manager.

  • ‫StreamManager: אובייקט שמטפל בתקשורת בין סטרימינג הווידאו לבין IMA DAI SDK, כמו הפעלת פינגים למעקב והעברת אירועים של סטרימינג אל בעל האתר.

דרישות מוקדמות

הגדרת אובייקטים של MediaInfo של השולח

קודם כול, מגדירים את אובייקט MediaInfo של אפליקציית השולח כך שיכלול את השדות הבאים:

contentId מזהה ייחודי של פריט המדיה
contentUrl כתובת ה-URL החלופית של השידור שתיטען אם בקשת השידור של DAI תיכשל מסיבה כלשהי
streamType בשידורים חיים, הערך הזה צריך להיות LIVE. בשידורי VOD, הערך הזה צריך להיות BUFFERED.
customData assetKey רק שידורים חיים מזהה את השידור החי שצריך לטעון
contentSourceId רק שידורי VOD. מזהה את פיד המדיה שמכיל את הזרם המבוקש.
videoId רק שידורי VOD. מזהה את הזרם המבוקש בפיד המדיה שצוין.
networkCode (אופציונלי) קוד הרשת ב-Google Ad Manager.
ApiKey מפתח API אופציונלי שיכול להיות נדרש כדי לאחזר את כתובת ה-URL של הסטרימינג מ-IMA DAI SDK
senderCanSkip ערך בוליאני שמאפשר למקבל לדעת אם למכשיר השולח יש אפשרות להציג לחצן דילוג, כדי לאפשר תמיכה במודעות שאפשר לדלג עליהן

כדי להגדיר את הערכים האלה בכלי הפקודה והבקרה של Cast, לוחצים על הכרטיסייה Load Media (טעינת מדיה) ומגדירים את סוג בקשת הטעינה המותאמת אישית לערך LOAD. אחר כך מחליפים את נתוני ה-JSON באזור הטקסט באחד מאובייקטי ה-JSON הבאים:

LIVE

{
  "media": {
    "contentId": "bbb",
    "contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8",
    "streamType": "LIVE",
    "customData": {
      "assetKey": "c-rArva4ShKVIAkNfy6HUQ",
      "networkCode": "21775744923",
      "ApiKey": "",
      "senderCanSkip": true
    }
  },
  "credentials": "testCredentials"
}

VOD

{
  "media": {
    "contentId": "tos",
    "contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/tos.m3u8",
    "streamType": "BUFFERED",
    "customData": {
      "contentSourceId": "2548831",
      "videoId": "tears-of-steel",
      "networkCode": "21775744923",
      "ApiKey": "",
      "senderCanSkip": true
    }
  },
  "credentials": "testCredentials"
}

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

יצירת מקלט CAF בסיסי

בהתאם למדריך Basic Receiver Guide (מדריך בסיסי למקלט) של CAF SDK, יוצרים מקלט אינטרנט בסיסי.

הקוד של המקלט אמור להיראות כך:

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
  </script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    cast.framework.CastReceiverContext.getInstance().start();
  </script>
</body>
</html>

ייבוא של IMA DAI SDK וקבלת Player Manager

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

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();

    castContext.start();
  </script>
</body>
</html>

הפעלת IMA Stream Manager

מאתחלים את Stream Manager של CAF DAI SDK.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    castContext.start();
  </script>
</body>
</html>

יצירת interceptor של הודעות טעינה

‫CAF DAI SDK משתמש בmessage interceptor של CAF load כדי לשלוח בקשות לסטרימינג ולהחליף את כתובת ה-URL של התוכן בסטרימינג הסופי של DAI. הפונקציה למניעת שיבוש הודעות קוראת לפונקציה streamManager.requestStream() שמטפלת בהגדרת הפסקות הפרסום, בשליחת בקשה לסטרימינג ובהחלפת ה-contentURL הקיים.

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

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    const getStreamRequest = (request) => null;

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, (request) => {
          return streamManager.requestStream(request, getStreamRequest(request))
              .then((request) => {
                this.broadcast('Stream request successful.');
                return Promise.resolve(request);
              })
              .catch((error) => {
                this.broadcast('Stream request failed.');
                return Promise.resolve(request);
              });
        });

    castContext.start();
  </script>
</body>
</html>

יצירת בקשת שידור

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

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    const getStreamRequest = (request) => {
      const imaRequestData = request.media.customData;
      let streamRequest = null;
      if (imaRequestData.assetKey) {
        // Live stream
        streamRequest = new google.ima.cast.dai.api.LiveStreamRequest();
        streamRequest.assetKey = imaRequestData.assetKey;
      } else if (imaRequestData.contentSourceId) {
        // VOD stream
        streamRequest = new google.ima.cast.dai.api.VODStreamRequest();
        streamRequest.contentSourceId = imaRequestData.contentSourceId;
        streamRequest.videoId = imaRequestData.videoId;
      }
      if (streamRequest && imaRequestData.networkCode) {
        streamRequest.networkCode = imaRequestData.networkCode;
      }
      if (streamRequest && imaRequestData.ApiKey) {
        streamRequest.ApiKey = imaRequestData.ApiKey;
      }
      if (streamRequest && imaRequestData.senderCanSkip) {
        streamRequest.senderCanSkip = imaRequestData.senderCanSkip;
      }
      return streamRequest;
    };

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, (request) => {
          return streamManager.requestStream(request, getStreamRequest(request))
              .then((request) => {
                return Promise.resolve(request);
              })
              .catch((error) => {
                this.broadcast('Stream request failed.');
                return Promise.resolve(request);
              });
        });

    castContext.start();
  </script>
</body>
</html>

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