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

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

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

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

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

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

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

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

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

  • ثلاثة ملفات فارغة
    • 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');
}

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

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

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

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

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) لعرض الإعلانات الديناميكية على الشبكة الإعلانية لإعلانات الوسائط التفاعلية. للاطّلاع على معلومات أكثر حول ميزات حزمة تطوير البرامج (SDK) المتقدّمة، يمكنك الاطّلاع على الأدلة الأخرى أو على عيّنات على GitHub.