با IMA DAI SDK شروع کنید

IMA SDK ادغام تبلیغات چندرسانه ای را در وب سایت ها و برنامه های شما آسان می کند. IMA SDK می‌تواند از هر سرور تبلیغاتی سازگار با VAST آگهی درخواست کند و پخش آگهی را در برنامه‌های شما مدیریت کند. با IMA DAI SDK، برنامه‌ها درخواست پخش جریانی برای آگهی و ویدیوی محتوا را ارائه می‌کنند - اعم از VOD یا محتوای زنده. سپس SDK یک جریان ویدیوی ترکیبی را برمی‌گرداند، به طوری که نیازی به مدیریت جابجایی بین آگهی و ویدیوی محتوا در برنامه خود ندارید.

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

سرو پاد DAI

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

نمای کلی سرویس DAI Pod

اجرای Pod Serving با استفاده از IMA DAI SDK شامل دو جزء اصلی است که در این راهنما نشان داده شده است:

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

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

پیش نیازها

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

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

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

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

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

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

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

    python -m http.server 8000

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

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

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

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

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

ثابت های درخواست جریان به شرح زیر است:

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

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

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

  • CUSTOM_ASSET_KEY : فقط برای پخش زنده استفاده می شود . کلید دارایی سفارشی که رویداد سرویس Pod شما را در Ad Manager 360 شناسایی می‌کند. این می‌تواند توسط دستکاری‌کننده مانیفست شما یا شریک شخص ثالث Pod Serving ایجاد شود.

  • API_KEY : فقط برای پخش زنده استفاده می شود . یک کلید API اختیاری که می تواند برای بازیابی شناسه جریان از 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="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');
}

IMA DAI SDK را بارگیری کنید

سپس، چارچوب 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 کنید

پخش زنده پاد

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

سپس، تابعی را برای درخواست پخش زنده Pod Serving تعریف کنید. این تابع ابتدا یک PodStreamRequest ایجاد می کند، آن را با پارامترهای streamRequest ارائه شده در مرحله 2 پیکربندی می کند و سپس streamManager.requestStream() را با آن شی درخواست فراخوانی می کند.

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

سرویس VOD Pod

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

سپس، تابعی را برای درخواست جریان VOD Pod Serving تعریف کنید. این تابع ابتدا یک PodVodStreamRequest ایجاد می کند، آن را با پارامترهای streamRequest ارائه شده در مرحله 2 پیکربندی می کند و سپس streamManager.requestStream() با آن شی درخواست فراخوانی می کند.

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

رویدادهای جریانی را مدیریت کنید

پخش زنده پاد

در مرحله بعد، شنوندگان رویداد را برای رویدادهای ویدیویی اصلی پیاده سازی کنید. این مثال با فراخوانی یک تابع onStreamEvent() ، رویدادهای STREAM_INITIALIZED ، ERROR ، AD_BREAK_STARTED و AD_BREAK_ENDED را مدیریت می‌کند. این تابع بارگیری جریان و خطاها را کنترل می‌کند، همچنین کنترل‌های پخش‌کننده را در حین پخش آگهی غیرفعال می‌کند، که توسط SDK مورد نیاز است. هنگامی که جریان بارگیری می شود، پخش کننده ویدیو URL ارائه شده را با استفاده از تابع 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);
}

سرویس VOD Pod

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

علاوه بر این، جریان‌های VOD Pod Serving نیاز به فراخوانی StreamManager.loadStreamMetadata() در پاسخ به رویداد STREAM_INITIALIZED دارند. همچنین باید از شریک فناوری ویدیویی خود (VTP) یک URL استریم درخواست کنید. هنگامی که فراخوانی loadStreamMetadata() با موفقیت انجام می شود، یک رویداد LOADED را راه اندازی می کند، جایی که باید یک تابع loadStream() را با URL استریم خود فراخوانی کنید تا جریان را بارگیری و پخش کنید. 

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

مدیریت فراداده جریان

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

فرمت جریان HLS (جریان های زنده و VOD، پخش کننده HLS.js)

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

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

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 برای جریان های زنده یا VOD استفاده کنید:

  • پخش زنده: 'https://developer.apple.com/streaming/emsg-id3'
  • جریان‌های VOD: 'urn:google:dai:2018'

فراداده ID3 را با StreamManager.processMetadata() به SDK منتقل کنید.

برای نمایش خودکار کنترل‌های ویدیو پس از بارگیری و آماده شدن همه چیز، به رویداد DASH.js MANIFEST_LOADED گوش دهید. 

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 با پخش زنده (قالب جریان DASH)

اگر از پخش کننده Shaka برای پخش پخش زنده استفاده می کنید، از رشته '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 با جریان های VOD (فرمت جریان های DASH)

اگر از پخش کننده Shaka برای پخش جریان 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 را پاکسازی کنید

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

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