Warning: The IMA SDK for Cast SDK v2 has been officially deprecated, as of November 17th, 2021. All existing users are urged to migrate to CAF native Ad Breaks.

Aplikasi penerima HTML5

Stay organized with collections Save and categorize content based on your preferences.

Panduan ini menunjukkan cara membuat aplikasi penerima kustom yang berkomunikasi antara aplikasi pengirim dan perangkat penerima, serta memungkinkan Anda mengintegrasikan IMA SDK ke dalam aplikasi Cast.

Jika Anda lebih memilih untuk mengikuti penerima IMA SDK yang sudah selesai, download aplikasi contoh atau lihat di GitHub. Anda juga dapat mendaftarkan penerima kustom untuk menggunakan contoh kami di GitHub dengan perangkat transmisi.

Contoh penerima kami dihosting di GitHub, sehingga Anda dapat menyiapkan penerima kustom Anda untuk diuji menggunakan URL berikut di penerima: https://googleads.github.io/googleads-ima-cast/client_receiver/player.html

File penerima

Penerima terdiri dari tiga bagian: HTML, CSS, dan JavaScript. Buat file HTML, bernama player.html, yang berisi kode berikut:

pemutar.html

<html>
<head>
  <title>IMA Example receiver</title>
  <link rel="stylesheet" type="text/css" href="style.css">
  <script src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
  <script type="text/javascript" src="player.js"></script>
</head>
<body>
  <div id="adContainer">
    <video id="mediaElement"></video>
    <script>
      var player = new Player(document.getElementById('mediaElement'));
    </script>
  </div>
</body>
</html>

HTML ini merujuk ke library IMA SDK dan library Google Cast, selain style.css dan player.js, yang dijelaskan di bawah. Selain referensi ini, variabel ini membuat variabel Player tunggal, yang juga Anda tentukan di player.js.

Buat halaman CSS, bernama style.css, yang berisi kode berikut untuk penerima:

gaya.css

video {
  width: 100%;
  height: 100%;
  overflow-y: hidden;
}

#adContainer {
  width: 100%;
  height: 100%;
}

Kode ini menentukan penyajian adContainer DIV, yang dibuat dalam HTML di atas.

JavaScript

Konstruktor

Logika utama untuk penerima masuk ke dalam file player.js. Buat file baru dengan nama ini. Buat konstruktor untuk jenis Player. Masukkan kode berikut ke dalam file:

pemutar.js

'use strict';

/**
 * Creates new player for video and ad playback.
 * @param {cast.receiver.MediaManager} mediaElement The video element.
 */
var Player = function(mediaElement) {
  var namespace = 'urn:x-cast:com.google.ads.ima.cast';
  this.mediaElement_ = mediaElement;
  this.mediaManager_ = new cast.receiver.MediaManager(this.mediaElement_);
  this.castReceiverManager_ = cast.receiver.CastReceiverManager.getInstance();
  this.imaMessageBus_ = this.castReceiverManager_.getCastMessageBus(namespace);
  this.castReceiverManager_.start();

  this.originalOnLoad_ = this.mediaManager_.onLoad.bind(this.mediaManager_);
  this.originalOnEnded_ = this.mediaManager_.onEnded.bind(this.mediaManager_);
  this.originalOnSeek_ = this.mediaManager_.onSeek.bind(this.mediaManager_);

  this.setupCallbacks_();
};

Ini adalah fungsi konstruktor untuk jenis Player. Perlu DOM elemen media, yang digunakan untuk memutar video HTML5. Buat cast.receiver.MediaManager, yang akan mengirim dan menerima pesan dan peristiwa media. Dapatkan referensi ke cast.receiver.CastReceiverManager, yang memungkinkan komunikasi dengan platform dan mengirim/menerima pesan dan peristiwa sistem.

Untuk mengirim dan menerima pesan khusus aplikasi, buat saluran untuk namespace tertentu, dan mulai CastReceiverManager.

Ada beberapa pengendali yang diganti di MediaManager, jadi simpan pengendali asli di sini untuk memanggilnya dari pengendali baru.

Menyiapkan callback

Hal terakhir yang dilakukan konstruktor adalah memanggil setupCallbacks_(), jadi tentukan di sini:

pemutar.js

/**
 * Attaches necessary callbacks.
 * @private
 */
Player.prototype.setupCallbacks_ = function() {
  var self = this;

  // Google Cast device is disconnected from sender app.
  this.castReceiverManager_.onSenderDisconnected = function() {
    window.close();
  };

  // Receives messages from sender app. The message is a comma separated string
  // where the first substring indicates the function to be called and the
  // following substrings are the parameters to be passed to the function.
  this.imaMessageBus_.onMessage = function(event) {
    console.log(event.data);
    var message = event.data.split(',');
    var method = message[0];
    switch (method) {
      case 'requestAd':
        var adTag = message[1];
        var currentTime = parseFloat(message[2]);
        self.requestAd_(adTag, currentTime);
        break;
      case 'seek':
        var time = parseFloat(message[1]);
        self.seek_(time);
        break;
      default:
        self.broadcast_('Message not recognized');
        break;
    }
  };

  // Initializes IMA SDK when Media Manager is loaded.
  this.mediaManager_.onLoad = function(event) {
    self.originalOnLoadEvent_ = event;
    self.initIMA_();
    self.originalOnLoad_(self.originalOnLoadEvent_);
  };
};

/**
 * Sends messages to all connected sender apps.
 * @param {!string} message Message to be sent to senders.
 * @private
 */
Player.prototype.broadcast_ = function(message) {
  this.imaMessageBus_.broadcast(message);
};

Tangani pesan CastReceiverManager.onSenderDisconneded dengan menutup jendela. Kemudian, tentukan beberapa jenis pesan yang ingin Anda respons dari aplikasi pengirim di bus namespace ima. Semua pesan ini diteruskan sebagai string yang dipisahkan koma, dengan substring pertama adalah nama fungsi. Pengirim meminta Anda meminta iklan saat transmisi dimulai, sehingga Anda menerima pesan requestAd dalam kasus ini, dengan tag iklan sebagai parameter kedua dan waktu mulai berada di urutan ketiga.

Pesan pengirim lainnya adalah seek, yang dipanggil saat melakukan transmisi ke dalam konten (dan bukan iklan). Ganti MediaManager.onLoad() untuk menginisialisasi IMA SDK sebelum memanggil onLoad() yang asli. Tentukan juga fungsi siaran untuk menyiarkan pesan ke pengirim.

Menginisialisasi IMA

Terapkan kode inisialisasi IMA yang menyiapkan AdsLoader, yang digunakan untuk meminta iklan.

pemutar.js

/**
 * Creates new AdsLoader and adds listeners.
 * @private
 */
Player.prototype.initIMA_ = function() {
  this.currentContentTime_ = 0;
  var adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), this.mediaElement_);
  adDisplayContainer.initialize();
  this.adsLoader_ = new google.ima.AdsLoader(adDisplayContainer);
  this.adsLoader_.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      this.onAdsManagerLoaded_.bind(this), false);
  this.adsLoader_.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR,
      this.onAdError_.bind(this), false);
  this.adsLoader_.addEventListener(google.ima.AdEvent.Type.ALL_ADS_COMPLETED,
      this.onAllAdsCompleted_.bind(this), false);
};

/**
 * Once the ads have been retrieved, use AdsManager to play the ads. Sends AdsManager
 * playAdsAfterTime if starting in the middle of content.
 * @param {ima.AdsManagerLoadedEvent} adsManagerLoadedEvent The loaded event.
 * @private
 */
Player.prototype.onAdsManagerLoaded_ = function(adsManagerLoadedEvent) {
  var adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.playAdsAfterTime = this.currentContentTime_;

  console.log(this.mediaElement_);
  // Get the ads manager.
  this.adsManager_ = adsManagerLoadedEvent.getAdsManager(
    this.mediaElement_, adsRenderingSettings);

  // Add listeners to the required events.
  this.adsManager_.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      this.onAdError_.bind(this));
  this.adsManager_.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      this.onContentPauseRequested_.bind(this));
  this.adsManager_.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      this.onContentResumeRequested_.bind(this));

  try {
    this.adsManager_.init(this.mediaElement_.width, this.mediaElement_.height,
        google.ima.ViewMode.FULLSCREEN);
    this.adsManager_.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    this.broadcast_('Ads Manager Error: ' + adError.getMessage());
  }
};

Anda telah menyiapkan dan menginisialisasi AdDisplayContainer menggunakan adContainer DIV dan elemen media, lalu membuat AdsLoader dengan penampung tersebut. Anda telah mendaftarkan pemroses peristiwa ke AdsLoader untuk menangani peristiwa iklan. Setelah iklan diambil, AdsManager akan menampilkannya.

Peristiwa AdsManager dan meminta iklan

Di bagian sebelumnya, Anda telah menambahkan pemroses peristiwa untuk peristiwa AdsManager dan error iklan. Bagian ini membahasnya secara mendetail.

pemutar.js

/**
 * Handles errors from AdsLoader and AdsManager.
 * @param {ima.AdErrorEvent} adErrorEvent error
 * @private
 */
Player.prototype.onAdError_ = function(adErrorEvent) {
  this.broadcast_('Ad Error: ' + adErrorEvent.getError().toString());
  // Handle the error logging.
  if (this.adsManager_) {
    this.adsManager_.destroy();
  }
  this.mediaElement_.play();
};

/**
 * When content is paused by AdsManager to start playing an ad.
 * @private
 */
Player.prototype.onContentPauseRequested_ = function() {
  this.currentContentTime_ = this.mediaElement_.currentTime;
  this.broadcast_('onContentPauseRequested,' + this.currentContentTime_);
  this.mediaManager_.onEnded = function(event) {};
  this.mediaManager_.onSeek = function(event) {};
};

/**
 * When an ad finishes playing and AdsManager resumes content.
 * @private
 */
Player.prototype.onContentResumeRequested_ = function() {
  this.broadcast_('onContentResumeRequested');
  this.mediaManager_.onEnded = this.originalOnEnded_.bind(this.mediaManager_);
  this.mediaManager_.onSeek = this.originalOnSeek_.bind(this.mediaManager_);

  this.originalOnLoad_(this.originalOnLoadEvent_);
  this.seek_(this.currentContentTime_);
};

/**
 * Destroys AdsManager when all requested ads have finished playing.
 * @private
 */
Player.prototype.onAllAdsCompleted_ = function() {
  if (this.adsManager_) {
    this.adsManager_.destroy();
  }
};

/**
 * Sets time video should seek to when content resumes and requests ad tag.
 * @param {!string} adTag ad tag to be requested.
 * @param {!float} currentTime time of content video to resume from.
 * @private
 */
Player.prototype.requestAd_ = function(adTag, currentTime) {
  if (currentTime != 0) {
    this.currentContentTime_ = currentTime;
  }
  var adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = adTag;
  adsRequest.linearAdSlotWidth = this.mediaElement_.width;
  adsRequest.linearAdSlotHeight = this.mediaElement_.height;
  adsRequest.nonLinearAdSlotWidth = this.mediaElement_.width;
  adsRequest.nonLinearAdSlotHeight = this.mediaElement_.height / 3;
  this.adsLoader_.requestAds(adsRequest);
};

/**
 * Seeks content video.
 * @param {!float} time time to seek to.
 * @private
 */
Player.prototype.seek_ = function(time) {
  this.currentContentTime_ = time;
  this.mediaElement_.currentTime = time;
  this.mediaElement_.play();
};

Fungsi onAdError() menangani error dari AdsLoader dan AdsManager. Jika mengalami error, penerima akan mencatatnya dalam log, lalu menghancurkan AdsManager, lalu memutar media konten. Selanjutnya, Anda memiliki dua fungsi yang menangani penjedaan dan melanjutkan konten, diikuti dengan fungsi untuk membersihkan AdsManager setelah iklan selesai.

Saat penerima memutar iklan, fungsi transmisi onEnded dan onSeek diganti untuk mencegah perangkat transmisi mengasumsikan bahwa akhiran iklan berarti video konten sudah selesai.

Terakhir, ada fungsi yang meminta iklan dari server menggunakan AdsLoader dan fungsi yang memutar video konten.

Langkah berikutnya

Pada tahap ini, Anda harus memiliki aplikasi penerima kustom transmisi yang telah selesai. Untuk mencobanya:

  • Daftarkan penerima untuk menerima ID aplikasi yang digunakan dengan panggilan API dari aplikasi pengirim.
  • Buat aplikasi pengirim Android atau iOS.