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

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

הטמעת מודעות דינמיות (DAI) ב-Pod

ערכות IMA SDK מפשטות את השילוב של מודעות מולטימדיה באתרים ובאפליקציות.

IMA SDK יכול לבקש מודעות מכל תואם ל-VAST שרת מודעות ולנהל את הפעלת המודעות באפליקציות שלכם.

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

המדריך הזה מדגים איך להפעיל שידור חי של הצגת Pod של DAI ב-DAI באמצעות IMA DAI SDK ל-CAF.

לפני השימוש במדריך הזה, כדאי להכיר את מקלט האינטרנט של Chromecast Application Framework של Google. המדריך הזה מבוסס על הבנה בסיסית של מושגי מקלטי CAF, כמו כלים ליירוט הודעות וגם mediaInformation לאובייקטים שונים, והיכרות עם כלי הפקודה והבקרה של הפעלת Cast, כדי לחקות שולח CAF.

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

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

סקירה כללית בנושא הצגת מודעות Pod של IMA DAI

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

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

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

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

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

שדה תוכן עניינים
contentId מזהה ייחודי של פריט המדיה הזה.

CONTENT_ID

contentUrl זה שינוי אופציונלי. כתובת ה-URL של השידור לגיבוי, שיופעל אם טעינת הסטרימינג של DAI נכשלה.

BACKUP_STREAM_URL

contentType זה שינוי אופציונלי. mimetype של שידורי גיבוי התוכן. נדרש רק עבור DASH סטרימינג.

CONTENT_STREAM_MIMETYPE

streamType ליטרל או קבוע של המחרוזת המשמש לערך הזה משתנה בהתאם לשולח הפלטפורמה.
customData השדה customData מכיל מאגר מפתח/ערך של עוד שדות חובה.
שדה תוכן עניינים
manifestUrl כתובת ה-URL של שידור הווידאו שסופקה על ידי הכלי לשינוי המניפסט או על ידי צד שלישי שותף. לשם כך תצטרכו להזין את מזהה מקור הנתונים שסופק על ידי IMA DAI SDK לפני שליחת בקשה. בדוגמה הזו, כתובת ה-URL של המניפסט כולל placeholder בשם [[STREAMID]], שיוחלף ב- מזהה של מקור נתונים לפני שליחת בקשה.

MANIFEST_URL

networkCode קוד הרשת של חשבון Google Ad Manager 360.

NETWORK_CODE

customAssetKey מפתח הנכס המותאם אישית שמזהה את אירוע הצגת ה-Pod ב-Google Ads Manager 360. במקרים מסוימים, ניתן לקבל את הפרטים האלה מהמניפסט. או שותף הצגת Pod של צד שלישי.

CUSTOM_ASSET_KEY

apiKey מפתח API אופציונלי לאחזור מזהה מקור נתונים מ-IMA DAI SDK.

API_KEY

הנה כמה דוגמאות קוד שיעזרו לכם להתחיל:

פיתוח אתרים

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

// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "CONTENT_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.LIVE;
mediaInfo.customData = {
manifestUrl: "MANIFEST_URL",
networkCode: "NETWORK-CODE",
customAssetKey: "CUSTOM_ASSET_KEY",
apiKey: "API_KEY"
};

// Make load request to cast web receiver
const castSession = cast.framework.CastContext.getInstance().getCurrentSession();
const request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
  () => { console.log('Load succeed'); },
  (errorCode) => { console.log('Error code: ' + errorCode); });

Android

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

JSONObject customData = new JSONObject()?
  .put("manifestUrl", "MANIFEST_URL")
  .put("networkCode", "NETWORK-CODE")
  .put("customAssetKey", "CUSTOM_ASSET_KEY")
  .put("apiKey", "API_KEY");
MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
  .setContentUrl("BACKUP_STREAM_URL")
  .setContentType("CONTENT_STREAM_MIMETYPE")
  .setStreamType(MediaInfo.STREAM_TYPE_LIVE)
  .setCustomData(customData)
  .build();

RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());

iOS (Obj-C)

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

NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
  @"manifestUrl": @"MANIFEST_URL",
  @"networkCode": @"NETWORK-CODE",
  @"customAssetKey": @"CUSTOM_ASSET_KEY",
  @"apiKey": @"API_KEY"};
mediaInfoBuilder.customData = customData;

GCKMediaInformationBuilder *mediaInfoBuilder =
  [[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeLive;
mediaInfoBuilder.customData = customData;
self.mediaInformation = [mediaInfoBuilder build];

GCKRequest *request = [self.sessionManager.currentSession.remoteMediaClient loadMedia:self.mediaInformation];
if (request != nil) {
  request.delegate = self;
}

iOS (Swift)

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

let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
  print("invalid mediaURL")
  return
}

let customData = [
  "liveConfigID": "MANIFEST_URL",
  "networkCode": "NETWORK-CODE",
  "customAssetKey": "CUSTOM_ASSET_KEY",
  "region": "API_KEY"
]

let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.Live
mediaInfoBuilder.customData = customData
mediaInformation = mediaInfoBuilder.build()

guard let mediaInfo = mediaInformation else {
  print("invalid mediaInformation")
  return
}

if let request = sessionManager.currentSession?.remoteMediaClient?.loadMedia
(mediaInfo) {
  request.delegate = self
}

כלי CAC

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

{
  "media": {
    "contentId": "CONTENT_ID",
    "contentUrl": "BACKUP_STREAM_URL",
    "contentType": ""CONTENT_STREAM_MIMETYPE"",
    "streamType": "LIVE",
    "customData": {
      "liveConfigID": "MANIFEST_URL",
      "networkCode": "NETWORK-CODE",
      "customAssetKey": "CUSTOM_ASSET_KEY",
      "oAuthToken": "API_KEY"
    }
  }
}

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

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

יצירת מקלט אינטרנט מותאם אישית, כפי שמוצג ב-CAF SDK Custom Web בצדr (מקלט אינטרנט מותאם אישית של CAF SDK) מדריך.

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

<html>
<head>
  <script
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
  </script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    // ...
  </script>
</body>
</html>

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

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

<html>
<head>
  <script
      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

הפעלת IMA Stream Manager.

<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>

יצירת יירוט העומס של מנהל השידורים

לפני שפריטי המדיה יועברו ל-CAF, יש ליצור את הבקשה לשידור טעינת ההודעה ומיירוט.

    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    /**
     * Creates a livestream request object for a pod serving stream.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {StreamRequest} an IMA stream request
     */
    const createStreamRequest = (castRequest) => { /* ... */};

    /**
     * Initates a DAI stream request for the final stream manifest.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
     */
    const createDAICastRequest = (castRequest) => {
        return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
          .then((castRequestWithPodStreamData) => {
            console.log('Successfully made DAI stream request.');
            // ...
            return castRequestWithPodStreamData;
          })
          .catch((error) => {
            console.log('Failed to make DAI stream request.');
            // CAF will automatically fallback to the content URL
            // that it can read from the castRequest object.
            return castRequest;
          });
    };

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, createDAICastRequest);

    castContext.start();

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

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

    /**
     * Creates a livestream request object for a pod serving stream.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {StreamRequest} an IMA stream request
     */
    const createStreamRequest = (castRequest) => {

      const streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
      const customData = castRequest.media.customData;

      streamRequest.customAssetKey = customData.customAssetKey;
      streamRequest.networkCode = customData.networkCode;
      streamRequest.apiKey = customData.apiKey;

      return streamRequest;
    };

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

אם הבקשה לשידור הבקשה תאושר, משתמשים ב-streamManager.getStreamId() כדי לאחזר את מזהה מקור הנתונים ולהוסיף אותו לקובץ המניפסטUrl, לאחר החלפתו. [[STREAMID]]. לאחר מכן, מחליפים את contentUrl הקיים בערך החדש manifestUrl כדי ש-CAF יפעיל את השידור החי עם רצף המודעות המחובר.

    /**
     * Initates a DAI stream request for the final stream manifest.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
     */
    const createDAICastRequest = (castRequest) => {
        return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
          .then((castRequestWithPodStreamData) => {
            console.log('Successfully made DAI stream request.');
            const media = castRequestWithPodStreamData.media;
                const manifestUrl = media.customData.manifestUrl || "";
                if (manifestUrl) {
                    console.log('Replacing the contentURL with the manifest URL and stream ID');
                    const streamId = streamManager.getStreamId();
                    castRequestWithPodStreamData.media.contentUrl = manifestUrl.replace('[[STREAMID]]', streamId);

            return castRequestWithPodStreamData;
          })
          .catch((error) => {
            console.log('Failed to make DAI stream request.');
            // CAF will automatically fallback to the content URL
            // that it can read from the castRequest object.
            return castRequest;
          });
    };

עכשיו אפשר לבקש ולהפעיל שידורים של רצפי מודעות באמצעות האפליקציה Cast מסגרת ו-IMA DAI SDK עבור CAF.