برای گفتگو و ارائه بازخورد در مورد محصولات ما، به کانال رسمی Ad Manager Discord در سرور انجمن تبلیغات و اندازه‌گیری Google بپیوندید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

راهکار 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

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

PodStreamRequest / PodVodStreamRequest : شیء‌ای که یک درخواست پخش زنده به سرورهای تبلیغاتی گوگل را تعریف می‌کند. درخواست‌ها یک کد شبکه را مشخص می‌کنند و PodStreamRequest همچنین به یک کلید دارایی سفارشی و یک کلید API اختیاری نیاز دارد. هر دو شامل پارامترهای اختیاری دیگری نیز هستند.
StreamManager : شیء‌ای که ارتباط بین جریان ویدئو و IMA DAI SDK را مدیریت می‌کند، مانند اجرای پینگ‌های ردیابی و ارسال رویدادهای جریان به ناشر.

پیش‌نیازها

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

سه فایل خالی:
- dai.html
- دای.css
- dai.js
پایتون نصب شده روی رایانه شما، یا یک وب سرور یا محیط توسعه میزبانی شده دیگر برای استفاده جهت آزمایش

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

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

با استفاده از خط فرمان، از دایرکتوری که فایل index.html شما در آن قرار دارد، دستور زیر را اجرا کنید:
```
python -m http.server 8000
```
توجه: http.server فقط در پایتون ۳.x موجود است.
در یک مرورگر وب، به 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

سپس، تابعی را برای درخواست جریان 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);
}

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

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

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

در مرحله بعد، شنونده‌های رویداد را برای رویدادهای مهم ویدیویی پیاده‌سازی کنید. این مثال رویدادهای 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 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 مراجعه کنید.