راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI

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

IMA SDKs make it easy to integrate multimedia ads into your websites and apps. IMA SDKs can request ads from any VAST-compliant ad server and manage ad playback in your apps. With IMA DAI SDKs, apps make a stream request for ad and content video—either VOD or live content. The SDK then returns a combined video stream, so that you don't have to manage switching between ad and content video within your app.

راهکار DAI مورد نظرتان را انتخاب کنید

غلاف سروینگ دای

This guide demonstrates how to play a DAI Pod Serving stream for live or VOD content, using the IMA DAI SDK for HTML5 with a video player that relies on hls.js for playback. To view or follow a completed sample integration, with support for both HLS.js and Safari Playback, see the HLS Pod Serving example . For DASH.js support, see the DASH Pod Serving example . You can download these sample apps from the HTML5 DAI GitHub release page .

نمای کلی سرو پاد DAI

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

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

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

پیش‌نیازها

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

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

    • dai.html
    • دای.css
    • dai.js

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

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

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

  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 : یک URL برای پخش استریم پشتیبان در صورتی که فرآیند تبلیغات با خطای مهلک مواجه شود.

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

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

  • CUSTOM_ASSET_KEY : فقط برای پخش زنده استفاده می‌شود . کلید دارایی سفارشی که رویداد Pod Serving شما را در 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="adUi"></div>
</body>
</html>

دای.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');
}

بارگیری SDK مربوط به IMA DAI

سپس، فریم‌ورک DAI را با استفاده از تگ script در 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

برای درخواست مجموعه‌ای از تبلیغات، یک 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);
}

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

پخش زنده پاد سرو

Next, implement event listeners for major video events. This example handles the STREAM_INITIALIZED , ERROR , AD_BREAK_STARTED and AD_BREAK_ENDED events by calling an onStreamEvent() function. This function handles stream loading and errors, as well as disabling the player controls while an ad is playing, which is required by the SDK. When the stream is loaded, the video player loads and plays the provided URL using a loadStream() function.

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

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

In addition, VOD Pod Serving streams require calling StreamManager.loadStreamMetadata() in response to the to the STREAM_INITIALIZED event. You also need to request a stream URL from your, video technology partner (VTP). Once the loadStreamMetadata() call succeeds it triggers a LOADED event, where you should call a loadStream() function with your stream URL to load and play the stream. 

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 backend مورد استفاده، متفاوت باشد. برای اطلاعات بیشتر به راهنمای فراداده زمان‌بندی‌شده ما مراجعه کنید.

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

اگر از پخش‌کننده‌ی HLS.js استفاده می‌کنید، به رویداد FRAG_PARSING_METADATA در HLS.js گوش دهید تا متادیتای 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 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 با پخش‌های VOD (فرمت پخش‌های 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 عنصر ویدیو، شنونده‌های رویداد (event listeners) اضافه کنید تا به کاربر اجازه دهید هنگام مکث 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 Serving با IMA DAI SDK را با موفقیت به پایان رساندید، پیشنهاد می‌کنیم پس از اتمام جلسه Pod Serving، هرگونه منبعی را پاک کنید. برای متوقف کردن پخش جریان، متوقف کردن تمام ردیابی تبلیغات و آزاد کردن تمام دارایی‌های جریان بارگذاری شده، StreamManager.destroy() را فراخوانی کنید.

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