إعداد حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لعرض الإعلانات أثناء التشغيل

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

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

اختيار حلّ "الإعلانات الديناميكية داخل الفيديو" الذي يهمّك

إدراج إعلان ديناميكي كامل الخدمات

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

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

يتضمّن تنفيذ حزمة تطوير البرامج IMA DAI مكوّنَين رئيسيَّين كما هو موضّح في هذا الدليل:

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

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

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

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

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

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

    python -m http.server 8000

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

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

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

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

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

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

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