راه‌اندازی کیت توسعه نرم‌افزار IMA برای DAI

پلاتفرم را انتخاب کنید: HTML5 Android iOS tvOS Cast Roku

کیت‌های توسعه نرم‌افزار IMA ادغام آگهی‌های چندرسانه‌ای در وب‌سایت‌ها و برنامه‌هایتان را آسان می‌کنند. کیت‌های توسعه نرم‌افزار IMA می‌توانند از هر سرور آگهی سازگار با VAST درخواست آگهی کنند و بازپخش آگهی را در برنامه‌هایتان مدیریت کنند. با کیت‌های توسعه نرم‌افزار IMA DAI، برنامه‌ها درخواست جاری‌سازی برای ویدیو آگهی و محتوا (چه ویدیو به‌درخواست و چه محتوای زنده) ارسال می‌کنند. سپس کیت توسعه نرم‌افزار یک جریان ویدیویی ترکیبی برمی‌گرداند، بنابراین شما مجبور نیستید در برنامه خود بین ویدیو آگهی و محتوا جابه‌جایی را مدیریت کنید.

راه‌حل DAI موردعلاقه‌تان را انتخاب کنید

بازرسی پویای ARP با خدمات کامل

این راهنما نشان می‌دهد چگونه «کیت توسعه نرم‌افزار IMA DAI» را در برنامه پخش‌کننده ویدیو ادغام کنید. اگر می‌خواهید یکپارچه‌سازی نمونه کامل‌شده را مشاهده کنید یا با آن همراه شوید، نمونه ساده را از GitHub بارگیری کنید.

نمای کلی IMA DAI

پیاده‌سازی کیت توسعه نرم‌افزار IMA DAI شامل دو جزء اصلی است که در این راهنما نشان داده شده است:

  • StreamRequest— یا VODStreamRequest یا LiveStreamRequest: شیئی که درخواست جاری‌سازی را تعریف می‌کند. درخواست‌های جاری‌سازی می‌تواند برای ویدیو به‌درخواست یا جاری‌سازی زنده باشد. درخواست‌های جاری‌سازی زنده کلید دارایی را مشخص می‌کنند، درحالی‌که درخواست‌های VOD شناسه CMS و شناسه ویدیو را مشخص می‌کنند. هر دو نوع درخواست می‌توانند به‌صورت اختیاری شامل کلید API موردنیاز برای دسترسی به جاری‌سازی‌های مشخص‌شده و کد شبکه Google Ad Manager برای IMA SDK باشند تا شناسه‌های آگهی را همان‌طور که در تنظیمات Google Ad Manager مشخص شده است مدیریت کند.
  • ‫ StreamManager: شیئی که جریان‌های درج آگهی پویا و تعاملات با زیرینه DAI را مدیریت می‌کند. مدیر جاری‌سازی همچنین پینگ‌های ردیابی را مدیریت می‌کند و رویدادهای جاری‌سازی و آگهی را به ناشر ارسال می‌کند.

پیش‌نیازها

  • سه فایل خالی
    • dai.html
    • dai.css
    • dai.js
  • Python نصب‌شده در رایانه، یا سرور وب برای استفاده در آزمایش

شروع سرور توسعه

ازآنجایی‌که «کیت توسعه نرم‌افزار IMA DAI» وابستگی‌ها را بااستفاده از همان پروتکل صفحه‌ای که از آن بارگیری می‌شود بار می‌کند، باید از سرور وب برای آزمایش برنامه‌تان استفاده کنید. یکی از روش‌های سریع برای شروع سرور توسعه محلی استفاده از سرور داخلی Python است.

  1. بااستفاده از خط فرمان، از فهرست راهنمایی که حاوی فایل index.html شما است این دستور را اجرا کنید:

    python -m http.server 8000
  2. در مرورگر وب، به http://localhost:8000/ بروید

    همچنین می‌توانید از هر سرور وب دیگری، مانند Apache HTTP Server استفاده کنید.

ایجاد پخش‌کننده ویدیو

ابتدا، dai.html را تغییر دهید تا عنصر ویدیو HTML5 و یک div برای استفاده در کلیک‌گذر ایجاد کنید. مثال زیر IMA DAI SDK را وارد می‌کند. برای جزئیات بیشتر، وارد کردن کیت توسعه نرم‌افزار IMA DAI را ببینید.

همچنین، برچسب‌های لازم را برای بار کردن فایل‌های dai.css و dai.js و همچنین برای وارد کردن پخش‌کننده ویدیو hls.js اضافه کنید. سپس، dai.css را اصلاح کنید تا اندازه و موقعیت عناصر صفحه را مشخص کنید. درنهایت، در dai.js، متغیرهایی را برای نگهداری اطلاعات درخواست جاری‌سازی تعریف کنید، تابعی را برای اجرا شدن هنگام بار شدن صفحه initPlayer() تعریف کنید، و دکمه پخش را برای درخواست جاری‌سازی هنگام کلیک راه‌اندازی کنید.

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>

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

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}
// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}

برای ازسر گرفتن بازپخش درطول وقفه‌های آگهی موقتاً متوقف‌شده، شنوندگان رویداد را برای رویدادهای pause و start عنصر ویدیو راه‌اندازی کنید تا کنترل‌های پخش‌کننده را نشان دهند و پنهان کنند.

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}

بار کردن کیت توسعه نرم‌افزار IMA DAI

سپس، چارچوب IMA را بااستفاده از برچسب نوشتاری در dai.html، قبل‌از برچسب برای dai.js اضافه کنید.

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>

مقداردهی اولیه StreamManager

برای درخواست مجموعه آگهی، ima.dai.api.StreamManager ایجاد کنید که مسئول درخواست و مدیریت جاری‌سازی‌های DAI است. سازنده یک عنصر ویدیو و یک عنصر میانای کاربر آگهی را برای مدیریت کلیک‌های آگهی می‌گیرد.

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}

درخواست جاری‌سازی کنید

توابعی را برای درخواست جاری‌سازی‌ها تعریف کنید. این مثال شامل توابعی برای ویدیو به‌درخواست و جاری‌سازی زنده است که نمونه‌هایی از کلاس VODStreamRequest و کلاس LiveStreamRequest ایجاد می‌کند. پس‌از اینکه نمونه streamRequest را داشتید، متد streamManager.requestStream() را با نمونه درخواست جاری‌سازی فراخوانی کنید.

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

هر دو روش درخواست جاری‌سازی یک کلید اختیاری API را می‌پذیرند. اگر از یک جاری‌سازی محافظت‌شده استفاده می‌کنید، باید یک کلید اصالت‌سنجی DAI ایجاد کنید. برای جزئیات بیشتر، درخواست‌های جاری‌سازی ویدیو DAI را اصالت‌سنجی کنید را ببینید. هیچ‌کدام از جاری‌سازی‌ها در این مثال بااستفاده از کلید اصالت‌سنجی DAI محافظت نمی‌شوند، بنابراین از apiKey استفاده نمی‌شود.

فراداده‌های جاری‌سازی را تجزیه کنید

همچنین باید یک کنترل‌کننده اضافه کنید تا به رویدادهای فراداده زمان‌دار گوش دهد و رویدادها را به کلاس StreamManager ارسال کند تا IMA بتواند رویدادهای آگهی را درطول وقفه‌های آگهی منتشر کند:

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Timed metadata is handled differently by different video players, and the
  // IMA SDK provides two ways to pass in metadata,
  // StreamManager.processMetadata() and StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });
}

این راهنما از پخش‌کننده hls.js برای بازپخش جاری‌سازی استفاده می‌کند، اما پیاده‌سازی فراداده شما به نوع پخش‌کننده‌ای که استفاده می‌کنید بستگی دارد.

مدیریت رویدادهای جاری‌سازی

شنوندگان رویداد را برای رویدادهای ویدیویی اصلی پیاده‌سازی کنید. این مثال رویدادهای LOADED، ERROR، AD_BREAK_STARTED، و AD_BREAK_ENDED را با فراخوانی تابع onStreamEvent() مدیریت می‌کند. این تابع بارگیری جاری‌سازی، خطاهای جاری‌سازی، و غیرفعال کردن کنترل‌های پخش‌کننده را درطول بازپخش آگهی مدیریت می‌کند که IMA SDK به آن نیاز دارد.

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      console.log('Stream loaded');
      loadUrl(e.getStreamData().url);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadUrl(BACKUP_STREAM);
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
function loadUrl(url) {
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  hls.on(Hls.Events.MANIFEST_PARSED, function() {
    console.log('Video Play');
    videoElement.play();
  });
}

وقتی جاری‌سازی بار می‌شود، پخش‌کننده ویدیو نشانی وب ارائه‌شده را بااستفاده از تابع loadUrl() بار و پخش می‌کند.

فقط همین! اکنون با «کیت توسعه نرم‌افزار IMA DAI» آگهی درخواست و نمایش می‌دهید. برای آشنایی با ویژگی‌های پیشرفته‌تر کیت توسعه نرم‌افزار، راهنماهای دیگر یا نمونه‌های GitHub را ببینید.