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

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

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

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

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

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

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

  • ‫ StreamRequest: إما VODStreamRequest أو LiveStreamRequest: كائن يحدّد طلب بث. يمكن تقديم طلبات بث فيديوهات عند الطلب أو بث مباشر جداول البيانات. تحدد الطلبات معرف المحتوى، بالإضافة إلى مفتاح واجهة برمجة التطبيقات (API) أو الرمز المميز للمصادقة المعلَمات.
  • 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');
}

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

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

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