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

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

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

إدراج إعلان ديناميكي شامل

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

نظرة عامة على "الإعلانات الديناميكية أثناء البث" من "إعلانات الوسائط

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

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

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

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

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

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

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

    python -m http.server 8000

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

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

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

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

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


dai.html
 
#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}

dai.css
 
// 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';
  });
}
dai.js

لاستئناف التشغيل أثناء فواصل إعلانية تم إيقافها مؤقتًا، عليك إعداد أدوات معالجة الأحداث للحدثَين 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';
}
dai.js

تحميل حزمة تطوير البرامج لإدراج إعلان ديناميكي من "إعلانات الوسائط التفاعلية"

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

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

تهيئة StreamManager

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

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

تقديم طلب بث

تحديد الدوال لطلب الفيديوهات يتضمّن هذا المثال دوالاً لكل من الفيديو عند الطلب وأحداث البث المباشر، ما يؤدي إلى إنشاء مثيلات للفئة 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.js

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

يستخدم هذا الدليل مشغّل 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();
  });
}
dai.js

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

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