Bắt đầu sử dụng SDK IMA DAI

Chọn giải pháp DAI mà bạn quan tâm

DAI phân phát nhóm

SDK IMA đơn giản hoá việc tích hợp quảng cáo đa phương tiện vào trang web và ứng dụng của bạn.

SDK IMA có thể yêu cầu quảng cáo từ bất kỳ máy chủ quảng cáo tuân thủ VAST nào và quản lý việc phát quảng cáo trong các ứng dụng của bạn.

Với SDK IMA DAI, các ứng dụng tạo một yêu cầu phát trực tuyến đối với quảng cáo và video nội dung cho nội dung VOD hoặc nội dung trực tiếp. Sau đó, SDK sẽ trả về một luồng video kết hợp để bạn không phải quản lý việc chuyển đổi giữa video quảng cáo và video nội dung trong ứng dụng của mình.

Hướng dẫn này minh hoạ cách phát luồng Phân phát nhóm DAI trực tiếp bằng cách sử dụng SDK IMA DAI cho CAF.

Trước khi sử dụng hướng dẫn này, hãy làm quen với giao thức Bộ nhận web của Khung ứng dụng Chromecast. Hướng dẫn này giả định bạn đã nắm được kiến thức cơ bản về các khái niệm của bộ nhận CAF, chẳng hạn như các đối tượng trình chặn tin nhắnmediaInformation, cũng như hiểu rõ cách sử dụng công cụ Điều khiển và Lệnh truyền để mô phỏng một người gửi CAF.

Để sử dụng tính năng phân phát nhóm IMA DAI, bạn phải làm việc với một đối tác phân phát nhóm và phải có tài khoản Ad Manager 360 Advanced. Nếu bạn có tài khoản Ad Manager, hãy liên hệ với người quản lý tài khoản để biết thêm thông tin. Để biết thông tin về cách đăng ký Ad Manager, hãy truy cập vào Trung tâm trợ giúp Ad Manager.

Để biết thông tin về cách tích hợp với các nền tảng khác hoặc về cách sử dụng SDK phía máy khách IMA, hãy xem phần SDK quảng cáo trên phương tiện truyền thông tương tác.

Tổng quan về việc phân phát nhóm IMA DAI

Việc triển khai tính năng phân phát nhóm bằng SDK DAI của IMA CAF bao gồm hai thành phần chính, như minh hoạ trong hướng dẫn này:

  • StreamRequest: Một đối tượng xác định yêu cầu truyền trực tuyến đến các máy chủ quảng cáo của Google. Các yêu cầu sẽ chỉ định Mã mạng, Khoá thành phần tuỳ chỉnh và khoá API không bắt buộc, cũng như các tham số không bắt buộc khác.
  • StreamManager: Một đối tượng xử lý hoạt động giao tiếp giữa luồng video và SDK IMA DAI, chẳng hạn như kích hoạt ping theo dõi và chuyển tiếp các sự kiện luồng đến nhà xuất bản.

Điều kiện tiên quyết

Định cấu hình đối tượng MediaInfo của người gửi

Trước tiên, hãy định cấu hình đối tượng MediaInfo của ứng dụng gửi để bao gồm các trường sau:

Kỹ thuật Nội dung
contentId Giá trị nhận dạng duy nhất của mục nội dung đa phương tiện này.

CONTENT_ID

contentUrl Không bắt buộc. URL luồng dự phòng sẽ phát nếu luồng DAI không tải được.

BACKUP_STREAM_URL

contentType Không bắt buộc. Mimetype của luồng sao lưu nội dung. Chỉ cần thiết cho luồng DASH.

CONTENT_STREAM_MIMETYPE

streamType Hằng số hoặc giá trị cố định kiểu chuỗi được dùng cho giá trị này sẽ khác nhau tuỳ theo nền tảng của người gửi.
customData Trường customData chứa kho khoá-giá trị gồm các trường bắt buộc khác.
Kỹ thuật Nội dung
manifestUrl URL luồng video do trình kiểm soát tệp kê khai hoặc đối tác bên thứ ba cung cấp. Bạn phải chèn mã luồng do SDK IMA DAI cung cấp trước khi đưa ra yêu cầu. Trong mẫu này, URL tệp kê khai bao gồm một phần giữ chỗ [[STREAMID]], sẽ được thay thế bằng mã luồng trước khi tạo yêu cầu.

MANIFEST_URL

networkCode Mã mạng cho tài khoản Google Ad Manager 360 của bạn.

NETWORK_CODE

customAssetKey Khoá thành phần tuỳ chỉnh xác định sự kiện phân phát nhóm trong Google Ad Manager 360. Trong một số trường hợp, bạn có thể lấy mã này từ trình điều khiển tệp kê khai hoặc đối tác phân phát nhóm bên thứ ba.

CUSTOM_ASSET_KEY

apiKey Khoá API không bắt buộc để truy xuất Mã luồng từ SDK IMA DAI.

API_KEY

Dưới đây là một số mã mẫu để giúp bạn bắt đầu:

Web

Để định cấu hình các giá trị này trong trình gửi Cast web, trước tiên hãy tạo một đối tượng MediaInfo với dữ liệu bắt buộc, sau đó thực hiện yêu cầu tải đến trình thu nhận web.

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

Để định cấu hình các giá trị này trong trình gửi Cast web, trước tiên hãy tạo đối tượng MediaInfo cho dữ liệu bắt buộc, sau đó thực hiện yêu cầu tải đến trình thu nhận web.

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)

Để định cấu hình các giá trị này trong trình gửi Cast web, trước tiên hãy tạo một đối tượng GCKMediaInformation với dữ liệu bắt buộc, sau đó thực hiện yêu cầu tải đến trình thu nhận web.

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)

Để định cấu hình các giá trị này trong trình gửi Cast web, trước tiên hãy tạo một đối tượng GCKMediaInformation với dữ liệu bắt buộc, sau đó thực hiện yêu cầu tải đến trình thu nhận web.

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
}

Công cụ CAC

Để định cấu hình các giá trị này trong Cast Command and Control tool (Lệnh truyền và công cụ Control), hãy nhấp vào thẻ Load Media (Tải nội dung nghe nhìn) rồi đặt loại yêu cầu tải tuỳ chỉnh thành TẢI. Sau đó, hãy thay thế dữ liệu JSON trong vùng văn bản bằng JSON sau:

{
  "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"
    }
  }
}

Yêu cầu tải tuỳ chỉnh này có thể được gửi đến trình nhận để kiểm thử các bước còn lại.

Tạo một bộ thu CAF cơ bản

Tạo một trình thu nhận web tuỳ chỉnh, như nêu trong Hướng dẫn về trình thu nhận web tuỳ chỉnh SDK CAF.

Mã của bộ nhận sẽ có dạng như sau:

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

Nhập SDK IMA DAI và tải Trình quản lý trình phát

Thêm một thẻ tập lệnh để nhập SDK IMA DAI cho CAF vào bộ thu web của bạn, ngay sau khi tập lệnh tải CAF. Trong thẻ tập lệnh, hãy lưu trữ ngữ cảnh của receiver và trình quản lý trình phát dưới dạng hằng số trước khi khởi động receiver.

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

Khởi chạy Trình quản lý luồng IMA

Khởi chạy Trình quản lý luồng IMA.

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

Tạo Trình chặn tải trong trình quản lý luồng

Trước khi các mục nội dung đa phương tiện của bạn được chuyển đến CAF, hãy tạo yêu cầu phát trực tuyến trong trình chặn thông báo TẢI.

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

Tạo yêu cầu luồng

Hoàn tất hàm createStreamRequest để tạo một luồng phân phát nhóm dựa trên yêu cầu tải 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;
    };

Thay thế URL nội dung bằng URL tệp kê khai và mã luồng

Nếu yêu cầu truyền trực tuyến của bạn thành công, hãy sử dụng streamManager.getStreamId() để truy xuất mã luồng và chèn mã đó vào manifestUrl, thay thế [[STREAMID]]. Sau đó, hãy thay thế contentUrl hiện có bằng manifestUrl mới để CAF phát sự kiện phát trực tiếp với các nhóm quảng cáo được ghép.

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

Giờ đây, bạn có thể yêu cầu và phát lại luồng phân phát nhóm bằng Khung ứng dụng truyền và SDK IMA DAI cho CAF.