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

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

اختيار حل DAI الذي يهمّك

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

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

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

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

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

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

  • ثلاثة ملفات فارغة
    • dai.html
    • dai.css
    • dai.js
  • تم تثبيت 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 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 لعنصر الفيديو للسماح للمستخدم باستئناف التشغيل عند توقُّف أداة IMA مؤقتًا أثناء الفواصل الإعلانية.

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

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.