Mulai menggunakan IMA DAI SDK

Memilih solusi DAI yang Anda minati

Penayangan Pod DAI

IMA SDK menyederhanakan integrasi iklan multimedia ke dalam situs dan aplikasi Anda.

IMA SDK dapat meminta iklan dari server iklan yang sesuai dengan VAST dan mengelola pemutaran iklan di aplikasi Anda.

Dengan IMA DAI SDK, aplikasi membuat permintaan streaming untuk iklan dan video konten untuk VOD atau konten live. SDK kemudian menampilkan streaming video gabungan, sehingga Anda tidak perlu mengelola pengalihan antara iklan dan video konten dalam aplikasi.

Panduan ini menunjukkan cara memutar streaming Penayangan Pod DAI, menggunakan IMA DAI SDK untuk CAF.

Sebelum menggunakan panduan ini, pahami protokol Penerima Web Framework Aplikasi Chromecast. Panduan ini mengasumsikan pemahaman dasar tentang konsep penerima CAF, seperti interceptor pesan dan objek mediaInformation, serta pemahaman tentang cara menggunakan alat Perintah dan Kontrol Transmisi, untuk mengemulasi pengirim CAF.

Untuk menggunakan Penayangan Pod DAI IMA, Anda harus bekerja sama dengan partner Penayangan Pod dan harus memiliki akun Ad Manager 360 Advanced. Jika Anda memiliki akun Ad Manager, hubungi Account Manager Anda untuk mengetahui detail selengkapnya. Untuk informasi tentang cara mendaftar ke Ad Manager, buka Pusat Bantuan Ad Manager.

Untuk informasi cara berintegrasi dengan platform lain, atau cara menggunakan SDK sisi klien IMA, lihat Interactive Media Ads SDK.

Ringkasan Penayangan Pod DAI IMA

Menerapkan Penayangan Pod menggunakan IMA CAF DAI SDK melibatkan dua komponen utama, yang ditunjukkan dalam panduan ini:

  • StreamRequest: Objek yang menentukan permintaan streaming ke server iklan Google. Permintaan menentukan Kode Jaringan, Kunci Aset Kustom, dan kunci API opsional, serta parameter opsional lainnya.
  • StreamManager: Objek yang menangani komunikasi antara streaming video dan IMA DAI SDK, seperti memicu ping pelacakan dan meneruskan peristiwa streaming ke penayang.

Prasyarat

  • Akun Konsol Developer Cast dengan perangkat pengujian terdaftar.
  • Aplikasi penerima web yang dihosting dan terdaftar di Konsol Developer Cast Anda dan dapat diubah untuk menghosting kode yang disediakan oleh panduan ini.
  • Aplikasi pengirim yang dikonfigurasi untuk menggunakan aplikasi penerima web Anda. Untuk tujuan contoh ini, gunakan alat Kontrol dan Perintah Cast sebagai pengirim Anda.

Mengonfigurasi objek MediaInfo pengirim

Pertama, konfigurasikan objek MediaInfo aplikasi pengirim Anda untuk menyertakan kolom berikut:

Kolom Daftar Isi
contentId ID unik untuk item media ini.

CONTENT_ID
contentUrl Opsional. URL streaming cadangan untuk diputar jika streaming DAI gagal dimuat.

BACKUP_STREAM_URL

contentType Opsional. Mimetype streaming cadangan konten. Hanya diperlukan untuk streaming DASH.

CONTENT_STREAM_MIMETYPE
streamType Literal string atau konstanta yang digunakan untuk nilai ini bervariasi menurut platform pengirim.
customData Kolom customData berisi penyimpanan nilai kunci kolom wajib tambahan. Dalam contoh ini, parameter ini berisi parameter streaming DAI Anda. Dalam aplikasi produksi, Anda dapat meneruskan ID yang akan digunakan aplikasi penerima cast untuk mengambil parameter ini dengan permintaan sisi server.
Kolom Daftar Isi
daiStreamType Jenis streaming DAI Anda. salah satu dari "LIVE" atau "VOD"

DAI_STREAM_TYPE
networkCode Kode jaringan untuk akun Google Ad Manager 360 Anda.

NETWORK_CODE
customAssetKey Kolom ini hanya diperlukan untuk Live stream. Kunci aset kustom yang mengidentifikasi peristiwa Penayangan Pod di Google Ad Manager 360.

CUSTOM_ASSET_KEY
apiKey Kunci API opsional untuk mengambil ID Streaming dari IMA DAI SDK.

API_KEY

Berikut adalah beberapa contoh kode untuk membantu Anda memulai:

Web

Untuk mengonfigurasi nilai ini di pengirim web Cast, buat objek MediaInfo terlebih dahulu dengan data yang diperlukan, lalu buat permintaan muat ke penerima 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 = {
  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

Untuk mengonfigurasi nilai ini di pengirim web Cast, buat objek MediaInfo terlebih dahulu dengan data yang diperlukan, lalu buat permintaan pemuatan ke penerima web.

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)

Untuk mengonfigurasi nilai ini di pengirim web Cast, buat objek GCKMediaInformation terlebih dahulu dengan data yang diperlukan, lalu buat permintaan muat ke penerima web.

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)

Untuk mengonfigurasi nilai ini di pengirim web Cast, buat objek GCKMediaInformation terlebih dahulu dengan data yang diperlukan, lalu buat permintaan muat ke penerima web.

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
}

Alat CAC

Untuk mengonfigurasi nilai ini di alat Cast Command and Control, klik tab Load Media, lalu tetapkan jenis permintaan pemuatan kustom ke LOAD. Kemudian, ganti data JSON di area teks dengan JSON ini:

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

Permintaan pemuatan kustom ini dapat dikirim ke penerima untuk menguji langkah-langkah lainnya.

Membuat penerima CAF dasar

Buat penerima web kustom, seperti yang terlihat dalam Panduan Penerima Web Kustom CAF SDK.

Kode penerima Anda akan terlihat seperti ini:

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

Mengimpor IMA DAI SDK dan mendapatkan Pengelola Pemutar

Tambahkan tag skrip untuk mengimpor IMA DAI SDK untuk CAF ke penerima web Anda, tepat setelah skrip memuat CAF. Dalam tag skrip, simpan konteks penerima dan pengelola pemutar sebagai konstanta sebelum memulai penerima.

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

Melakukan inisialisasi Pengelola Streaming IMA

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

Membuat Stream Manager Load Interceptor

Sebelum item media diteruskan ke CAF, buat permintaan streaming di interceptor pesan 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();

Membuat permintaan streaming

Selesaikan fungsi createStreamRequest untuk membuat streaming Pod Serving berdasarkan permintaan pemuatan 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;
    };

Mengambil manifes yang digabungkan dari VTP

Jika permintaan streaming Anda berhasil, gunakan streamManager.getStreamId() untuk mengambil ID streaming. Partner Teknis Video (VTP) atau manipulator manifes kustom Anda akan memberikan petunjuk untuk mengambil URL manifes, menggunakan ID streaming ini.

Setelah mengambil URL manifes, ganti contentUrl yang ada dengan manifestUrl baru.

Terakhir, sebelum menampilkan manifes streaming yang dimodifikasi, panggil metode loadStreamMetadata di streamManager untuk memberi tahu IMA SDK bahwa SDK tersebut dapat meminta metadata streaming dengan aman. Panggilan ini hanya diperlukan untuk streaming 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;
          });
    };

Membersihkan aset DAI IMA

Setelah berhasil menyelesaikan permintaan dan menampilkan iklan di streaming Penayangan Pod dengan IMA DAI SDK, sebaiknya bersihkan resource apa pun setelah sesi Penayangan Pod selesai. Panggil StreamManager.destroy() untuk menghentikan pemutaran streaming, menghentikan semua pelacakan iklan, dan merilis semua aset streaming yang dimuat.