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

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

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

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

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

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

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

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

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

  • ثلاثة ملفات فارغة
    • 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 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 لأحداث البث المباشر. إلى حزم تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية كما هو موضّح في نموذج الرمز.

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.