เริ่มต้นใช้งาน IMA DAI SDK

เลือกโซลูชัน DAI ที่คุณสนใจ

DAI ของ Pod Serving

IMA SDK ช่วยให้ผสานรวมโฆษณามัลติมีเดียลงในเว็บไซต์และแอปได้ง่ายขึ้น

IMA SDK สามารถขอโฆษณาจากเซิร์ฟเวอร์โฆษณาที่เป็นไปตามข้อกําหนดของ VAST ใดก็ได้ และจัดการการเล่นโฆษณาในแอป

เมื่อใช้ IMA DAI SDK แอปจะส่งคําขอสตรีมสําหรับโฆษณาและวิดีโอเนื้อหาสําหรับ VOD หรือเนื้อหาสด จากนั้น SDK จะแสดงผลสตรีมวิดีโอแบบรวม คุณจึงไม่ต้องจัดการการสลับระหว่างโฆษณากับวิดีโอเนื้อหาภายในแอป

คู่มือนี้แสดงวิธีเล่นสตรีม DAI Pod Serving โดยใช้ IMA DAI SDK สําหรับ CAF

ก่อนใช้คู่มือนี้ โปรดทำความคุ้นเคยกับโปรโตคอลตัวรับเว็บของเฟรมเวิร์กแอปพลิเคชัน Chromecast คู่มือนี้ถือว่าคุณเข้าใจแนวคิดพื้นฐานเกี่ยวกับตัวรับ CAF เช่น ออบเจ็กต์ message interceptor และ mediaInformation รวมถึงคุ้นเคยกับการใช้เครื่องมือ Command and Control ของ Cast เพื่อจําลองตัวส่ง CAF

หากต้องการใช้ IMA DAI Pod Serving คุณต้องทํางานร่วมกับพาร์ทเนอร์ Pod Serving และต้องมีบัญชี Ad Manager 360 Advanced หากมีบัญชี Ad Manager โปรดติดต่อผู้จัดการฝ่ายดูแลลูกค้าเพื่อขอรายละเอียดเพิ่มเติม ดูข้อมูลเกี่ยวกับการลงชื่อสมัครใช้ Ad Manager ได้ที่ศูนย์ช่วยเหลือของ Ad Manager

ดูข้อมูลเกี่ยวกับการผสานรวมกับแพลตฟอร์มอื่นๆ หรือการใช้ SDK ฝั่งไคลเอ็นต์ของ IMA ได้ที่ SDK โฆษณาสื่ออินเทอร์แอกทีฟ

ภาพรวมของ IMA DAI Pod Serving

การใช้ Pod Serving โดยใช้ IMA CAF DAI SDK ประกอบด้วยคอมโพเนนต์หลัก 2 อย่างดังที่แสดงในคู่มือนี้

  • StreamRequest: ออบเจ็กต์ที่กําหนดคําขอสตรีมไปยังเซิร์ฟเวอร์โฆษณาของ Google คำขอจะระบุรหัสเครือข่าย คีย์ชิ้นงานที่กำหนดเอง และคีย์ API (ไม่บังคับ) รวมถึงพารามิเตอร์อื่นๆ (ไม่บังคับ)
  • StreamManager: ออบเจ็กต์ที่จัดการการสื่อสารระหว่างสตรีมวิดีโอกับ IMA DAI SDK เช่น การเรียกใช้การติดตาม Ping และการส่งต่อเหตุการณ์สตรีมไปยังผู้เผยแพร่โฆษณา

ข้อกำหนดเบื้องต้น

  • บัญชี Cast Developer Console ที่มีอุปกรณ์ทดสอบที่ลงทะเบียนไว้
  • แอปตัวรับเว็บที่โฮสต์ไว้ซึ่งลงทะเบียนกับแผงควบคุมสำหรับนักพัฒนาซอฟต์แวร์ Cast และแก้ไขให้โฮสต์โค้ดที่ได้จากคู่มือนี้ได้
  • แอปส่งที่กำหนดค่าให้ใช้แอปรับเว็บของคุณ ในตัวอย่างนี้ ให้ใช้เครื่องมือควบคุมและสั่งการแคสต์เป็นผู้ส่ง

กำหนดค่าออบเจ็กต์ MediaInfo ของผู้ส่ง

ก่อนอื่น ให้กําหนดค่าออบเจ็กต์ MediaInfo ของแอปผู้ส่งเพื่อรวมช่องต่อไปนี้

ช่อง เนื้อหา
contentId ตัวระบุที่ไม่ซ้ำกันสำหรับรายการสื่อนี้

CONTENT_ID
contentUrl ไม่บังคับ URL ของสตรีมสำรองที่จะเล่นหากสตรีม DAI โหลดไม่สำเร็จ

BACKUP_STREAM_URL

contentType ไม่บังคับ ประเภท MIME ของสตรีมการสำรองข้อมูลเนื้อหา จำเป็นสำหรับสตรีม DASH เท่านั้น

CONTENT_STREAM_MIMETYPE
streamType สตริงตัวอักษรล้วนหรือค่าคงที่ที่ใช้สำหรับค่านี้จะแตกต่างกันไปตามแพลตฟอร์มของผู้ส่ง
customData ช่อง customData มีที่เก็บคีย์-ค่าของช่องที่ต้องกรอกเพิ่มเติม ในตัวอย่างนี้ มีพารามิเตอร์สตรีม DAI ในแอปเวอร์ชันที่ใช้งานจริง คุณอาจส่งตัวระบุที่แอปรับแคสต์จะใช้เพื่อดึงข้อมูลพารามิเตอร์เหล่านี้ด้วยคำขอฝั่งเซิร์ฟเวอร์แทน
ช่อง เนื้อหา
daiStreamType ประเภทสตรีม DAI ของคุณ ซึ่งอาจเป็น "LIVE" หรือ "VOD"

DAI_STREAM_TYPE
networkCode รหัสเครือข่ายสําหรับบัญชี Google Ad Manager 360

NETWORK_CODE
customAssetKey ช่องนี้จำเป็นสำหรับสตรีมแบบสดเท่านั้น คีย์ชิ้นงานที่กําหนดเองซึ่งระบุเหตุการณ์การแสดงพ็อดใน Google Ad Manager 360

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 = {
  daiStreamType: "DAI_STREAM_TYPE",
  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("daiStreamType", "DAI_STREAM_TYPE")
  .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 = @{
  @"daiStreamType": @"DAI_STREAM_TYPE",
  @"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 = [
  "daiStreamType": "DAI_STREAM_TYPE",
  "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 ให้คลิกแท็บโหลดสื่อ แล้วตั้งค่าประเภทคำขอโหลดที่กำหนดเองเป็น LOAD จากนั้นแทนที่ข้อมูล JSON ในพื้นที่ข้อความด้วย JSON นี้

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

คุณส่งคําขอการโหลดที่กําหนดเองนี้ไปยังผู้รับเพื่อทดสอบขั้นตอนที่เหลือได้

สร้างตัวรับ CAF พื้นฐาน

สร้างเว็บรีซีฟเวอร์ที่กําหนดเองตามที่แสดงในคู่มือเว็บรีซีฟเวอร์ที่กําหนดเองของ 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>

สร้างตัวขัดจังหวะการโหลดของ Stream Manager

ก่อนส่งรายการสื่อไปยัง CAF ให้สร้างคำขอสตรีมในตัวขัดจังหวะข้อความ LOAD

    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 ให้เสร็จสมบูรณ์เพื่อสร้างสตรีมการแสดงโฆษณาพ็อดตามคำขอโหลด 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 customData = castRequest.media.customData;
      let streamRequest;
      if (customData.daiStreamType == "LIVE") {
        streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
        streamRequest.customAssetKey = customData.customAssetKey;
        streamRequest.networkCode = customData.networkCode;
        streamRequest.apiKey = customData.apiKey;
      } else if (customData.daiStreamType == "VOD") {
        streamRequest = new google.ima.cast.dai.api.PodVodStreamRequest();
        streamRequest.networkCode = customData.networkCode;
        streamRequest.apiKey = customData.apiKey;
      }
      return streamRequest;
    };

เรียกข้อมูลไฟล์ Manifest ที่ต่อกันจาก VTP

หากคำขอสตรีมสำเร็จ ให้ใช้ streamManager.getStreamId() เพื่อเรียกดูรหัสของสตรีม พาร์ทเนอร์ด้านเทคนิควิดีโอ (VTP) หรือเครื่องมือจัดการไฟล์ Manifest ที่กําหนดเองจะระบุวิธีการดึงข้อมูล URL ของไฟล์ Manifest โดยใช้รหัสสตรีมนี้

เมื่อดึงข้อมูล URL ของไฟล์ Manifest แล้ว ให้แทนที่ contentUrl ที่มีอยู่ด้วย manifestUrl ใหม่

สุดท้าย ก่อนแสดงผลไฟล์ Manifest ของสตรีมที่แก้ไขแล้ว ให้เรียกใช้เมธอด loadStreamMetadata ใน streamManager เพื่อแจ้งให้ IMA SDK ทราบว่าสามารถขอข้อมูลเมตาของสตรีมได้อย่างปลอดภัย การเรียกใช้นี้จำเป็นสำหรับสตรีม VOD เท่านั้น

    /**
     * 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.');

            // This is a sample VTP integration. Consult your VTP documentation
            // for how to retrieve an ad-stitched stream manifest URL.
            const manifestTemplate = "https://.../manifest.m3u8?gam_stream_id=[[STREAMID]]";
            const streamId = streamManager.getStreamId();
            const manifestUrl = manifestTemplate.replace('[[STREAMID]]', streamId)
            // Assign your manifestUrl to the request's content URL.
            castRequestWithPodStreamData.media.contentUrl = manifestUrl;

            // After generating the manifest URL, VOD streams must notify the
            // IMA SDK that it is safe to request ad pod metadata.
            // This is only necessary for VOD streams. It is a no-op for
            // livestreams, so no conditional is needed.
            streamManager.loadStreamMetadata();

            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;
          });
    };

ล้างข้อมูลชิ้นงาน IMA DAI

เมื่อขอและแสดงโฆษณาในสตรีมการแสดงโฆษณาพ็อดด้วย IMA DAI SDK เรียบร้อยแล้ว เราขอแนะนำให้คุณล้างทรัพยากรทั้งหมดหลังจากเซสชันการแสดงโฆษณาพ็อดเสร็จสมบูรณ์ เรียกใช้ StreamManager.destroy() เพื่อหยุดการเล่นสตรีม หยุดการติดตามโฆษณาทั้งหมด และปล่อยชิ้นงานสตรีมที่โหลดไว้ทั้งหมด