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

SDK IMA giúp bạn dễ dàng tích hợp quảng cáo đa phương tiện vào trang web và ứng dụng của mình. 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 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, ứng dụng tạo ra yêu cầu phát trực tuyến cho quảng cáo và video nội dung, VOD hoặc nội dung trực tiếp. Sau đó, SDK này 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 quảng cáo và video nội dung trong ứng dụng của bạn.

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

Dịch vụ trọn gói Phân phát nhóm

DAI phân phát nhóm

Hướng dẫn này minh hoạ cách phát một sự kiện Phân phát nhóm DAI cho sự kiện phát trực tiếp hoặc VOD nội dung, sử dụng SDK IMA DAI cho HTML5 với một trình phát video dựa trên hls.js để phát lại. Nếu bạn muốn xem hoặc theo dõi một mẫu hoàn chỉnh có hỗ trợ cả HLS.js và Phát lại Safari, hãy xem Ví dụ về việc phân phát nhóm HLS. Để được hỗ trợ cho DASH.js, hãy xem ví dụ về việc phân phát nhóm DASH. Bạn có thể tải các ứng dụng mẫu này xuống từ bản phát hành HTML5 DAI trên GitHub .

Lưu ý: SDK IMA DAI cho HTML5 hỗ trợ cả luồng HLS và DASH, nhưng việc phát từng luồng đòi hỏi trình phát nội dung đa phương tiện hoặc tiện ích khác như HLS.js hoặc DASH.js, với các thay đổi thực tế.

Hướng dẫn này giải thích cách định cấu hình HLS.js và IMA DAI SDK để phát một luồng HLS, với các lưu ý quan trọng về sự khác biệt khi triển khai cho DASH.

Xem IMA Ứng dụng mẫu DASH.js làm điểm bắt đầu để triển khai luồng DAI DASH với IMA.

Lưu ý quan trọng: Để sử dụng tính năng Phân phát nhóm DAI, bạn phải đang làm việc với tính năng phân phát nhóm và phải có một Ad Manager 360 Tài khoản nâng cao. 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 của bạn để biết thêm chi tiết. Cho thông tin về việc đăng ký Ad Manager, hãy truy cập vào phần Trợ giúp Ad Manager Center.

Lưu ý: Để 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 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 DAI (Chèn quảng cáo động)

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

• PodStreamRequest / PodVodStreamRequest: Một đối tượng xác định yêu cầu truyền trực tuyến máy chủ quảng cáo của Google. Các yêu cầu chỉ định Mã mạng và PodStreamRequest cũng yêu cầu một Khoá thành phần tuỳ chỉnh và một thuộc tính không bắt buộc Khoá API. Cả hai đều bao gồm 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 sự kiện phát trực tuyến đến nhà xuất bản.

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

Trước khi bắt đầu, bạn cần có:

• Ba tệp trống:

  • dai.html
  • dai.css
  • dai.js

• Đã cài đặt Python trên máy tính, hoặc máy chủ web hoặc quy trình phát triển được lưu trữ khác môi trường để sử dụng cho việc kiểm thử

Định cấu hình môi trường phát triển

Vì SDK tải các phần phụ thuộc bằng cách sử dụng cùng một giao thức như trang từ nội dung đã được tải, bạn cần sử dụng một máy chủ web để kiểm thử ứng dụng của mình. Một số mẹo cách khởi động máy chủ phát triển cục bộ là sử dụng máy chủ tích hợp của Python.

1. Sử dụng một dòng lệnh từ thư mục chứa index.html của bạn chạy tệp:

   python -m http.server 8000
   

   Lưu ý: http.server chỉ có trong Python 3.x.

2. Trên trình duyệt web, hãy truy cập vào http://localhost:8000/

   Bạn cũng có thể sử dụng bất kỳ môi trường phát triển được lưu trữ hoặc máy chủ web nào khác, chẳng hạn như làm Máy chủ HTTP Apache.

Tạo trình phát video đơn giản

Lưu ý: Hướng dẫn này giả định rằng bạn đang sử dụng thư viện HLS.js để phát HLS luồng. SDK IMA DAI cho HTML5 cũng có thể hỗ trợ các luồng DASH, với thư viện thích hợp như trình phát Shaka hoặc DASH.js.

Trước tiên, hãy sửa đổi dai.html để tạo một phần tử video HTML5 đơn giản và một div để sử dụng cho các phần tử trên Giao diện người dùng quảng cáo. Ngoài ra, hãy thêm các thẻ cần thiết để tải dai.css và dai.js, cũng như nhập trình phát video hls.js.

Sau đó, hãy sửa đổi dai.css để chỉ định kích thước và vị trí của các phần tử trang. Cuối cùng, trong dai.js, hãy xác định các biến để lưu giữ thông tin về yêu cầu luồng và một hàm initPlayer() để chạy khi trang tải.

Sau đây là các hằng số yêu cầu truyền trực tuyến:

• BACKUP_STREAM: URL cho luồng dự phòng để phát trong quá trình quảng cáo gặp phải một lỗi nghiêm trọng.

• STREAM_URL: Chỉ dùng cho sự kiện phát trực tiếp. URL luồng video được cung cấp bởi trình điều khiển tệp kê khai hoặc đối tác bên thứ ba sử dụng tính năng phân phát nhóm. Phải yêu cầu 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 trường hợp này, URL luồng bao gồm phần giữ chỗ, [[STREAMID]], được thay thế bằng mã luồng trước khi tạo yêu cầu.

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

• CUSTOM_ASSET_KEY: Chỉ dùng cho sự kiện phát trực tiếp. Khoá thành phần tuỳ chỉnh xác định sự kiện phân phát nhóm trong Ad Manager 360. Người tạo có thể tạo 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 của bạn.

• API_KEY: Chỉ dùng cho sự kiện phát trực tiếp. Khoá API không bắt buộc có thể cần thiết để truy xuất ID luồng từ SDK IMA DAI.

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA DAI SDK Demo (HLS.JS)</h2>
    <video id="video"></video>
    <div id="ad-ui"></div>
</body>
</html>

dai.css

#video,
#ad-ui {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#ad-ui {
  cursor: pointer;
}

dai.js

var BACKUP_STREAM =
    'https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8'

// Stream Config.
const STREAM_URL = "https://encodersim.sandbox.google.com/masterPlaylist/...&stream_id=[[STREAMID]]";
const NETWORK_CODE = "51636543";
const CUSTOM_ASSET_KEY = "google-sample";
const API_KEY = "";

var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
}

Tải SDK IMA DAI

Tiếp theo, hãy thêm khung DAI bằng cách sử dụng một thẻ tập lệnh trong dai.html, trước thẻ cho dai.js.

Lưu ý: Để nhận được nhật ký chi tiết hơn trên bảng điều khiển, bạn có thể thay thế ima3_dai.js bằng ima3_dai_debug.js. Tuy nhiên, bạn không nên dùng ima3_dai_debug.js trong ứng dụng chính thức.

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
...

Khởi chạy StreamManager và tạo yêu cầu phát trực tiếp hoặc VOD

Phân phát nhóm sự kiện phát trực tiếp

Để yêu cầu một tập hợp quảng cáo, hãy tạo một ima.dai.api.StreamManager. chịu trách nhiệm yêu cầu và quản lý các luồng DAI. Hàm khởi tạo lấy thành phần video và bản sao thu được sẽ lấy thành phần giao diện người dùng quảng cáo để xử lý quảng cáo tương tác.

Sau đó, hãy xác định một hàm để yêu cầu sự kiện phát trực tiếp phân phát nhóm. Hàm này trước tiên, hãy tạo một PodStreamRequest, định cấu hình đối tượng này bằng StreamRequest tham số được cung cấp ở bước 2, sau đó gọi streamManager.requestStream() với đối tượng yêu cầu đó.

Lưu ý quan trọng: Không có luồng nào trong ví dụ này được bảo vệ, vì vậy apiKey không đã sử dụng. Nếu luồng của bạn yêu cầu Khoá API, hãy xem phần Xác thực luồng video DAI yêu cầu.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  requestLivePodStream(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
}

function requestLivePodStream(networkCode, customAssetKey, apiKey) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving live Stream Request
  const streamRequest = new google.ima.dai.api.PodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.customAssetKey = customAssetKey;
  streamRequest.apiKey = apiKey;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

Phân phát nhóm VOD

Để yêu cầu một tập hợp quảng cáo, hãy tạo một ima.dai.api.StreamManager. chịu trách nhiệm yêu cầu và quản lý các luồng DAI. Hàm khởi tạo lấy thành phần video và bản sao thu được sẽ lấy thành phần giao diện người dùng quảng cáo để xử lý quảng cáo tương tác.

Sau đó, hãy xác định một hàm để yêu cầu luồng VOD phân phát nhóm. Hàm này trước tiên, hãy tạo một PodVodStreamRequest, định cấu hình đối tượng này bằng StreamRequest tham số được cung cấp ở bước 2, sau đó gọi streamManager.requestStream() với đối tượng yêu cầu đó.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  requestVodPodStream(NETWORK_CODE);
}

function requestVodPodStream(networkCode) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving VOD Stream Request
  const streamRequest = new google.ima.dai.api.PodVodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

Xử lý sự kiện phát trực tiếp

Phân phát nhóm sự kiện phát trực tiếp

Tiếp theo, hãy triển khai trình nghe sự kiện cho các sự kiện video chính. Ví dụ này xử lý STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED và AD_BREAK_ENDED bằng cách gọi hàm onStreamEvent(). Hàm này xử lý luồng trong quá trình tải và lỗi, cũng như tắt các nút điều khiển trình phát khi quảng cáo đang phát theo yêu cầu của SDK. Khi luồng được tải, video trình phát tải và phát URL được cung cấp bằng cách sử dụng hàm loadStream().

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    google.ima.dai.api.StreamEvent.Type.ERROR,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);
...
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
      console.log('Stream initialized');
      loadStream(e.getStreamData().streamId);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream('');
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

function loadStream(streamID) {
  var url;
  if(streamID) {
    url = STREAM_URL.replace('[[STREAMID]]', streamID);
  } else {
    console.log('Stream Initialization Failed');
    url = BACKUP_STREAM;
  }
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
}

Phân phát nhóm VOD

Tiếp theo, hãy triển khai trình nghe sự kiện cho các sự kiện video chính. Ví dụ này xử lý STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED và AD_BREAK_ENDED bằng cách gọi một hàm onStreamEvent(). Chiến dịch này xử lý lỗi và quá trình tải luồng, cũng như tắt trình phát các chức năng điều khiển trong khi quảng cáo đang phát mà SDK yêu cầu.

Ngoài ra, bạn phải gọi phương thức gọi điện để phân phát luồng VOD nhóm StreamManager.loadStreamMetadata() nhằm tuân thủ Sự kiện STREAM_INITIALIZED. Bạn cũng cần yêu cầu một URL luồng từ đối tác công nghệ video (VTP). Sau khi lệnh gọi loadStreamMetadata() thành công hàm này kích hoạt sự kiện LOADED, trong đó bạn nên gọi hàm loadStream() bằng URL của sự kiện phát trực tiếp để tải và phát sự kiện đó.

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    google.ima.dai.api.StreamEvent.Type.ERROR,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);
...
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
      const streamId = e.getStreamData().streamId;
      // 'vtpInterface' is a place holder for your own video technology
      //  partner (VTP) API calls.
      vtpInterface.requestStreamURL({
        'streamId': streamId,
      })
      .then( (vtpStreamUrl) => {
        streamUrl = vtpStreamUrl;
        streamManager.loadStreamMetadata();
      }, (error) => {
        // Handle the error.
      });
      break;
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      loadStream(streamUrl);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

function loadStream(url) {
  if(url) {
    console.log('Loading:' + url);
    hls.loadSource(url);
  } else {
    console.log('Stream Initialization Failed');
    hls.loadSource(BACKUP_STREAM);
  }
  hls.attachMedia(videoElement);
}

Xử lý siêu dữ liệu của sự kiện phát trực tiếp

Ở bước này, bạn triển khai trình nghe sự kiện cho siêu dữ liệu để thông báo cho SDK khi các sự kiện quảng cáo xảy ra. Khả năng theo dõi các sự kiện siêu dữ liệu trong luồng phát có thể khác nhau, tuỳ thuộc vào định dạng sự kiện phát trực tiếp (HLS hoặc DASH), loại sự kiện phát trực tiếp (sự kiện phát trực tiếp hoặc video theo yêu cầu), loại trình phát và loại phụ trợ DAI đang được sử dụng. Xem Báo cáo theo thời gian của chúng tôi Siêu dữ liệu để biết thêm thông tin.

Định dạng luồng HLS (luồng trực tiếp và VOD, trình phát HLS.js)

Nếu bạn đang sử dụng trình phát HLS.js, hãy nghe sự kiện FRAG_PARSING_METADATA HLS.js để nhận siêu dữ liệu ID3 và truyền siêu dữ liệu đó đến SDK với StreamManager.processMetadata().

Để tự động phát video sau khi mọi thứ đã được tải và sẵn sàng, hãy nghe sự kiện MANIFEST_PARSED HLS.js để kích hoạt phát lại.

function loadStream(streamID) {
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  
  // Timed metadata is passed HLS stream events to the streamManager.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
  hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}

function parseID3Events(event, data) {
  if (streamManager && data) {
    // For each ID3 tag in the metadata, pass in the type - ID3, the
    // tag data (a byte array), and the presentation timestamp (PTS).
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
}

function startPlayback() {
  console.log('Video Play');
  videoElement.play();
}

DASH.js (định dạng luồng DASH, loại luồng trực tiếp và VOD)

Nếu bạn đang sử dụng trình phát DASH.js, bạn phải sử dụng các chuỗi khác nhau để nghe siêu dữ liệu ID3 cho Nội dung phát trực tiếp hoặc VOD luồng:

• Sự kiện phát trực tiếp: 'https://developer.apple.com/streaming/emsg-id3'
• Luồng video theo yêu cầu: 'urn:google:dai:2018'

Truyền siêu dữ liệu ID3 đến SDK bằng StreamManager.processMetadata().

Cách tự động hiển thị các nút điều khiển video sau khi mọi thứ đã được tải và sẵn sàng: theo dõi sự kiện MANIFEST_LOADED DASH.js.

const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);

function processMetadata(metadataEvent) {
  const messageData = metadataEvent.event.messageData;
  const timestamp = metadataEvent.event.calculatedPresentationTime;

  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with dash.js.
  streamManager.processMetadata('ID3', messageData, timestamp);
}

function loadlistener() {
  showControls();

  // This listener must be removed, otherwise it triggers as addional
  // manifests are loaded. The manifest is loaded once for the content,
  // but additional manifests are loaded for upcoming ad breaks.
  dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}

Shaka Player với sự kiện phát trực tiếp (định dạng luồng DASH)

Nếu bạn đang sử dụng trình phát Shaaka cho phát trực tiếp, hãy sử dụng chuỗi 'emsg' để nghe các sự kiện siêu dữ liệu. Sau đó, sử dụng dữ liệu tin nhắn sự kiện trong cuộc gọi của bạn đến StreamManager.onTimedMetadata().

shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));

function onEmsgEvent(metadataEvent) {
  // Use StreamManager.onTimedMetadata() if your video player provides
  // processed metadata, as with Shaka player livestreams.
  streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}

Trình phát Shaka với luồng VOD (định dạng luồng DASH)

Nếu bạn đang sử dụng trình phát Shaaka cho Phát luồng VOD, sử dụng chuỗi 'timelineregionenter' để nghe sự kiện siêu dữ liệu. Sau đó, hãy sử dụng dữ liệu tin nhắn sự kiện trong cuộc gọi của bạn để StreamManager.processMetadata() bằng chuỗi 'urn:google:dai:2018'.

shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));

function onTimelineEvent(metadataEvent) {
  const detail = metadataEvent.detail;
  if ( detail.eventElement.attributes &&
       detail.eventElement.attributes['messageData'] &&
       detail.eventElement.attributes['messageData'].value ) {
        const mediaId = detail.eventElement.attributes['messageData'].value;
        const pts = detail.startTime;
        // Use StreamManager.processMetadata() if your video player provides raw
        // ID3 tags, as with Shaka player VOD streams.
        streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
       }
}

Xử lý sự kiện của người chơi

Thêm trình nghe sự kiện vào các sự kiện pause và start của phần tử video để cho phép người dùng để tiếp tục phát khi SDK tạm dừng trong điểm chèn quảng cáo.

function loadStream(streamUrl) {
  ...
  
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);
}

function onStreamPause() {
  console.log('paused');
  if (isAdBreak) {
    videoElement.controls = true;
    adUiElement.style.display = 'none';
  }
}

function onStreamPlay() {
  console.log('played');
  if (isAdBreak) {
    videoElement.controls = false;
    adUiElement.style.display = 'block';
  }
}

Vậy là xong! Bạn hiện đang yêu cầu và hiển thị quảng cáo trong luồng phân phát nhóm với SDK IMA DAI cho HTML5. Để tìm hiểu thêm về các tính năng SDK nâng cao, hãy xem các hướng dẫn khác hoặc mẫu trên GitHub.