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

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

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

ارائه DAI در تیم

این راهنما نشان می‌دهد که چگونه بااستفاده از IMA DAI SDK برای HTML5 با پخش‌کننده ویدیویی که برای بازپخش به hls.js متکی است، جاری‌سازی «واحد آگهی DAI» را برای محتوای زنده یا «ویدیو به‌درخواست» پخش کنید. برای مشاهده یا دنبال کردن یک نمونه ادغام تکمیل‌شده، با پشتیبانی از HLS.js و Safari Playback، به نمونه ارائه پاد HLS مراجعه کنید. برای پشتیبانی از DASH.js، به مثال ارائه واحد تبلیغات DASH مراجعه کنید. می‌توانید این برنامه‌های نمونه را از صفحه انتشار HTML5 DAI GitHub بارگیری کنید.

نمای کلی ارائه پاد DAI

پیاده‌سازی «ارائه Pod» بااستفاده از IMA DAI SDK شامل دو مؤلفه اصلی است که در این راهنما نشان داده شده است:

• PodStreamRequest / PodVodStreamRequest: شیئی که درخواست جاری‌سازی را برای سرورهای تبلیغات Google تعریف می‌کند. درخواست‌ها کد شبکه را مشخص می‌کنند و PodStreamRequest همچنین به کلید دارایی سفارشی و کلید میانای برنامه‌سازی کاربردی اختیاری نیاز دارد. هر دو شامل پارامترهای اختیاری دیگر هستند.

• StreamManager: شیئی که ارتباط بین جاری‌سازی ویدیو و کیت توسعه نرم‌افزار IMA DAI را مدیریت می‌کند، مانند ارسال پینگ‌های ردیابی و انتقال رویدادهای جاری‌سازی به ناشر.

پیش‌نیازها

قبل‌از شروع، به موارد زیر نیاز دارید:

• سه فایل خالی:

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

• Python نصب‌شده در رایانه، یا سرور وب یا محیط توسعه میزبانی‌شده دیگری که برای آزمایش استفاده شود

پیکربندی محیط توسعه نرم‌افزار

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

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

   python -m http.server 8000

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

   همچنین می‌توانید از هر محیط توسعه میزبانی‌شده یا سرور وب دیگری مثل Apache HTTP Server استفاده کنید.

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

ابتدا dai.html را تغییر دهید تا عنصر ویدیو HTML5 و div برای استفاده در عناصر واسط کاربر آگهی ایجاد کنید. همچنین برچسب‌های لازم را برای بار کردن فایل‌های dai.css و dai.js و نیز برای وارد کردن پخش‌کننده ویدیو hls.js اضافه کنید.

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

ثابت‌های درخواست جاری‌سازی به‌صورت زیر است:

• BACKUP_STREAM: نشانی وب برای جاری‌سازی پشتیبان برای پخش درصورتی‌که فرایند آگهی‌ها با خطای مهلکی مواجه شود.

• STREAM_URL: فقط برای جاری‌سازی‌های زنده استفاده می‌شود. نشانی وب جاری‌سازی ویدیو ارائه‌شده توسط دستکاری‌کننده مانیفست یا شریک طرف سوم شما بااستفاده از «خدمات‌دهی واحد». این برنامه باید قبل‌از اینکه درخواست کنید، از شما بخواهد شناسه جاری‌سازی ارائه‌شده توسط IMA DAI SDK را وارد کنید. در این مورد، نشانی وب جاری‌سازی شامل جای‌بان، [[STREAMID]]، است که قبل‌از درخواست با شناسه جاری‌سازی جایگزین می‌شود.

• NETWORK_CODE: کد شبکه برای حساب Ad Manager 360 شما.

• ‫CUSTOM_ASSET_KEY: فقط برای جاری‌سازی‌های زنده استفاده می‌شود. کلید دارایی سفارشی که رویداد «ارائه واحد آگهی» شما را در Ad Manager 360 شناسایی می‌کند. این را دستکاری‌کننده مانیفست شما یا شریک «ارائه پاد» طرف سوم می‌تواند ایجاد کند.

• API_KEY: فقط برای جاری‌سازی‌های زنده استفاده می‌شود. کلید اختیاری میانای برنامه‌سازی کاربردی که می‌تواند برای بازیابی شناسه جاری‌سازی از IMA DAI SDK الزامی باشد.

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="adUi"></div>
</body>
</html>

dai.css

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

#adUi {
  cursor: pointer;
}

dai.js

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

// Stream Config.
const STREAM_URL = "";
const NETWORK_CODE = "";
const CUSTOM_ASSET_KEY = "";
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');
}

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

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

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

‫StreamManager را مقداردهی اولیه کنید و درخواست جاری‌سازی زنده یا VOD بدهید

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

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

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

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

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

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

در این مرحله، شنوندگان رویداد را برای فراداده پیاده‌سازی می‌کنید تا وقتی رویدادهای آگهی رخ می‌دهد به کیت توسعه نرم‌افزار اطلاع دهند. گوش دادن به رویدادهای فراداده درون جاری‌سازی می‌تواند بسته به قالب جاری‌سازی (HLS یا DASH)، نوع جاری‌سازی (جاری‌سازی زنده یا VOD)، نوع پخش‌کننده شما و نوع زیرینه DAI مورد استفاده متفاوت باشد. برای اطلاعات بیشتر، راهنمای فراداده زمان‌دار ما را ببینید.

قالب جاری‌سازی HLS (جاری‌سازی‌های زنده و VOD، پخش‌کننده HLS.js)

اگر از پخش‌کننده HLS.js استفاده می‌کنید، به رویداد HLS.js FRAG_PARSING_METADATA گوش دهید تا فراداده ID3 را دریافت کنید و آن را با StreamManager.processMetadata() به کیت توسعه نرم‌افزار ارسال کنید.

برای پخش خودکار ویدیو پس‌از بارگذاری و آماده شدن همه چیز، به رویداد MANIFEST_PARSED HLS.js گوش دهید تا پخش را راه‌اندازی کند.

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 (قالب جاری‌سازی‌های DASH، نوع جاری‌سازی زنده و VOD)

اگر از پخش‌کننده DASH.js استفاده می‌کنید، باید از رشته‌های مختلفی برای گوش دادن به فراداده ID3 برای جاری‌سازی‌های زنده یا ویدیو به‌درخواست استفاده کنید:

• جاری‌سازی‌های زنده: 'https://developer.apple.com/streaming/emsg-id3'
• جاری‌سازی‌های ویدیو به‌درخواست: 'urn:google:dai:2018'

فراداده ID3 را با StreamManager.processMetadata() به کیت توسعه نرم‌افزار منتقل کنید.

برای نمایش خودکار کنترل‌های ویدیو پس‌از بارگیری و آماده شدن همه چیز، به رویداد 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 با جاری‌سازی‌های زنده (قالب جاری‌سازی‌های DASH)

اگر از Shaka player برای بازپخش جاری‌سازی زنده استفاده می‌کنید، از رشته 'emsg' برای گوش دادن به رویدادهای فراداده استفاده کنید. سپس از داده‌های پیام رویداد در تماستان برای 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});
}

Shaka Player با جاری‌سازی‌های «ویدیو به‌درخواست» (قالب جاری‌سازی‌های DASH)

اگر از Shaka player برای بازپخش جاری‌سازی VOD استفاده می‌کنید، از رشته 'timelineregionenter' برای گوش دادن به رویدادهای فراداده استفاده کنید. سپس، از داده‌های پیام رویداد در فراخوانی خود به StreamManager.processMetadata() با رشته '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);
       }
}

رسیدگی به رویدادهای بازیکن

شنوندگان رویداد را به رویدادهای pause و start عنصر ویدیو اضافه کنید تا به کاربر اجازه دهید وقتی SDK درحین وقفه‌های آگهی مکث می‌کند، پخش را ازسر بگیرد.

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';
  }
}

پاک‌سازی دارایی‌های IMA DAI

وقتی با موفقیت درخواست و نمایش آگهی‌ها را در یک «واحد آگهی» جاری‌سازی با IMA DAI SDK انجام دادید، پیشنهاد می‌کنیم پس‌از تکمیل جلسه «واحد آگهی»، همه منابع را پاک‌سازی کنید. برای توقف بازپخش جاری‌سازی، توقف همه ردگیری‌های آگهی، و واگذاری همه دارایی‌های جاری‌سازی بارشده، StreamManager.destroy() را فراخوانی کنید.

برای آشنایی با ویژگی‌های پیشرفته‌تر کیت توسعه نرم‌افزار، راهنماهای دیگر یا نمونه‌های GitHub را ببینید.