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

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

اختيار حلّ DAI المطلوب

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

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

نظرة عامة على إدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية

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

  • StreamRequest— إما VODStreamRequest أو LiveStreamRequest: كائن يعرّف طلب البث. يمكن تقديم طلبات البث بشأن فيديوهات عند الطلب أو لأحداث بث مباشر. تحدّد الطلبات Content ID، بالإضافة إلى مفتاح واجهة برمجة التطبيقات أو الرمز المميز للمصادقة ومعلَمات أخرى.
  • StreamManager: عنصر يتعامل مع أحداث إدراج الإعلانات الديناميكية والتفاعلات مع خلفية DAI. ويتولى مدير البث أيضًا إشعارات التتبع وإعادة توجيه أحداث البث والإعلانات إلى الناشر.

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

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

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

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

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

    python -m http.server 8000

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

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

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

أولاً، عدّل dai.html لإنشاء عنصر فيديو HTML5 بسيط وعنصر div لاستخدامه في نسبة النقر إلى الظهور. أضِف أيضًا العلامات اللازمة لتحميل ملفات dai.css وdai.js، وكذلك لاستيراد مشغّل الفيديو hls.js. بعد ذلك، عدِّل dai.css لتحديد حجم عناصر الصفحة وموضعها. وأخيرًا، في dai.js، حدِّد المتغيّرات للاحتفاظ بمعلومات طلب مصدر البيانات ودالة initPlayer() لتشغيلها عند تحميل الصفحة.

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 DAI Demo (HLS.JS)</h2>
    <video id="video"></video>
    <div id="ad-ui"></div>
</body>
</html>

dai.css

#video,
#ad-ui {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#ad-ui {
  cursor: pointer;
}

dai.js

var BACKUP_STREAM =
    'https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8'

// Livestream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2548831";
var TEST_VIDEO_ID = "tears-of-steel";

var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;
var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
}

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

بعد ذلك، أضِف إطار عمل إعلانات الوسائط التفاعلية باستخدام علامة نص برمجي في 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 وتقديم طلب بث

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

بعد ذلك، حدِّد الدوال التي تتطلّب عمليات البث. يتضمن هذا المثال دوال لكل من الفيديوهات عند الطلب وأحداث البث المباشر التي تنشئ مثيلين من VODStreamRequest وLiveStreamRequest على التوالي، ثم تطلب streamManager.requestStream() باستخدام مَعلمات streamRequest. في البث المباشر، يجب أيضًا إضافة معالج للاستماع إلى أحداث البيانات الوصفية الموقوتة وإعادة توجيه الأحداث إلى StreamManager. يمكنك التعليق على الرمز أو إلغاء التعليق عليه لتناسب حالة استخدامك. تتطلب كلتا الطريقتين مفتاح واجهة برمجة تطبيقات اختياريًا. إذا كنت تستخدم بثًا محميًا، عليك إنشاء مفتاح مصادقة باستخدام DAI.

لا تتم حماية أيّ مصدر بيانات في هذا المثال، لذا لا يتم استخدام apiKey.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  // Timed metadata is only used for LIVE streams.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(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(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });

  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, null);
  // Uncomment the line below and comment out the one above to request a
  // LIVE stream instead of a VOD stream.
  //requestLiveStream(TEST_ASSET_KEY, null);
}

function requestVODStream(cmsId, videoId, apiKey) {
  var streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

function requestLiveStream(assetKey, apiKey) {
  var streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

التعامل مع أحداث البث

وأخيرًا، تحتاج إلى تنفيذ أدوات معالجة الأحداث لأحداث الفيديو الرئيسية. يعالج هذا المثال البسيط الأحداث LOADED وERROR وAD_BREAK_STARTED وAD_BREAK_ENDED من خلال استدعاء دالة onStreamEvent(). وتعالج هذه الوظيفة تحميل البث والأخطاء، بالإضافة إلى إيقاف عناصر التحكم في المشغّل أثناء عرض إعلان، وهو أمر تطلبه حزمة تطوير البرامج (SDK). عندما يتم تحميل البث، يحمِّل مشغّل الفيديو عنوان URL المقدَّم ويشغّله باستخدام وظيفة loadUrl().

وننصحك أيضًا بإعداد أدوات معالجة الأحداث لأحداث pause وstart الخاصة بعنصر الفيديو، وذلك للسماح للمستخدم باستئناف التشغيل عند توقُّف إعلانات الوسائط التفاعلية مؤقتًا أثناء الفواصل الإعلانية.

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

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);

  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.LOADED,
     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.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');
      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 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();
  });
}

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';
  }
}

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