البدء

Stay organized with collections Save and categorize content based on your preferences.

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

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

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

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

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

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

قبل البدء، تحتاج إلى ما يلي:

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

1- بدء خادم التطوير

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

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

    python -m http.server 8000
    
  2. في متصفح الويب، انتقل إلى http://localhost:8000/

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

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

عليك أولاً تعديل 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'

// Live stream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2528370";
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');
}

3- تحميل أداة تطوير البرامج لإعلانات الوسائط التفاعلية

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

...

4. إعداد StreamManager وإجراء طلب البث

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

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

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

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

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

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

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