الإعداد باستخدام "إدراج الإعلان الديناميكي" (DAI) مع الخدمة الكاملة

اختيار النظام الأساسي: HTML5 Android iOS tvOS Cast Roku

يوضّح هذا الدليل كيفية دمج حزمة تطوير البرامج (SDK) لتقنية IMA DAI في تطبيق مشغّل فيديو. إذا كنت تريد الاطّلاع على نموذج دمج مكتمل أو متابعته، يمكنك تنزيل المثال البسيط من GitHub.

نظرة عامة على IMA DAI

يتضمّن تنفيذ حزمة تطوير البرامج (SDK) لتقنية "إدراج الإعلان الديناميكي" في "إعلانات الوسائط التفاعلية" مكوّنَين رئيسيَّين كما هو موضّح في هذا الدليل:

  • ‫ StreamRequest: إما VODStreamRequest أو LiveStreamRequest: عنصر يحدّد طلب بث. يمكن أن تكون طلبات البث لفيديوهات عند الطلب أو أحداث بث مباشر. تحدّد طلبات البث المباشر مفتاح مادة عرض، بينما تحدّد طلبات الفيديو عند الطلب معرّف "نظام إدارة المحتوى" ومعرّف الفيديو. يمكن أن يتضمّن كلا نوعَي الطلبات اختياريًا مفتاح واجهة برمجة التطبيقات اللازم للوصول إلى أحداث بث معيّنة، ورمز شبكة "إدارة إعلانات Google" لكي تتعامل حزمة IMA SDK مع معرّفات الإعلانات على النحو المحدّد في إعدادات "إدارة إعلانات Google".
  • ‫ StreamManager: عنصر يعالج أحداث بث "إدراج الإعلانات الديناميكية" والتفاعلات مع الخلفية الخاصة بهذه الميزة. يتولّى مدير البث أيضًا تتبُّع إشعارات الاتصال وإعادة توجيه أحداث البث والإعلانات إلى الناشر.

المتطلبات الأساسية

  • ثلاثة ملفات فارغة
    • dai.html
    • dai.css
    • dai.js
  • تثبيت Python على جهاز الكمبيوتر أو خادم ويب لاستخدامه في الاختبار

بدء خادم تطوير

بما أنّ حزمة تطوير البرامج (SDK) لتقنية IMA DAI تحمّل التبعيات باستخدام البروتوكول نفسه الذي تستخدمه الصفحة التي يتم تحميلها منها، عليك استخدام خادم ويب لاختبار تطبيقك. يمكنك استخدام خادم Python المضمّن كطريقة سريعة لبدء خادم تطوير محلي.

  1. باستخدام سطر الأوامر، من الدليل الذي يحتوي على ملف index.html، شغِّل:

    python -m http.server 8000

  2. في متصفّح ويب، انتقِل إلى http://localhost:8000/

    يمكنك أيضًا استخدام أي خادم ويب آخر، مثل خادم Apache HTTP.

إنشاء مشغّل فيديو

أولاً، عدِّل dai.html لإنشاء عنصر فيديو HTML5 وقسم لاستخدامه في النقر للوصول. يستورد المثال التالي حزمة تطوير البرامج (SDK) لتقنية IMA DAI. لمزيد من التفاصيل، يُرجى الاطّلاع على استيراد حزمة تطوير البرامج (SDK) لإدراج الإعلان الديناميكي (DAI) في إعلانات الوسائط التفاعلية (IMA).

أضِف أيضًا العلامات اللازمة لتحميل ملفَّي 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';
}

تحميل حزمة تطوير البرامج (SDK) لتقنية IMA DAI

بعد ذلك، أضِف إطار عمل IMA باستخدام علامة برمجية في dai.html، قبل علامة dai.js.

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

إعداد StreamManager

لطلب مجموعة من الإعلانات، أنشئ ima.dai.api.StreamManager، وهو المسؤول عن طلب وإدارة أحداث البث المباشر لإدراج الإعلانات ديناميكيًا. تتلقّى الدالة الإنشائية عنصر فيديو وعنصرًا في واجهة المستخدم للإعلان من أجل معالجة النقرات على الإعلانات.

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

تتطلّب كلتا طريقتَي طلب البث مفتاح واجهة برمجة تطبيقات اختياريًا. إذا كنت تستخدم بثًا محميًا، عليك إنشاء مفتاح مصادقة "إدراج إعلان ديناميكي". لمزيد من التفاصيل، يُرجى الاطّلاع على مصادقة طلبات بث الفيديو عبر ميزة "إدراج الإعلان ديناميكيًا". لا تتم حماية أي من البثَّين في هذا المثال باستخدام مفتاح مصادقة "إدراج الإعلان ديناميكيًا"، لذا لا يتم استخدام 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();
  });
}

عند تحميل البث، يتم تحميل مشغّل الفيديو وتشغيل عنوان URL المقدَّم باستخدام دالة loadUrl().

هذا كل شيء! يمكنك الآن طلب الإعلانات وعرضها باستخدام حزمة تطوير البرامج (SDK) لإدراج الإعلانات الديناميكية في إعلانات الوسائط التفاعلية (IMA DAI). لمزيد من المعلومات حول ميزات حزمة تطوير البرامج (SDK) الأكثر تقدّمًا، يُرجى الاطّلاع على الأدلة الأخرى أو النماذج على GitHub.