إعداد حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لعرض الإعلانات أثناء التشغيل

اختيار حلّ "الإعلانات الديناميكية أثناء عرض الفيديو" الذي يهمّك

إدراج إعلان ديناميكي شامل

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

قبل استخدام هذا الدليل، تأكَّد من التعرّف على بروتوكول Web Receiver في إطار عمل تطبيقات Chromecast. يفترض هذا الدليل معرفة أساسية بمفاهيم أداة استقبال CAF، مثل اعتراض الرسائل وعناصر mediaInformation، بالإضافة إلى معرفة كيفية استخدام أداة "التحكّم والأوامر في Cast" لمحاكاة أداة إرسال CAF.

لاستخدام IMA DAI، يجب أن يكون لديك حساب على مدير الإعلانات 360. إذا كان لديك حساب على "مدير إعلانات Google"، تواصَل مع مدير حسابك للحصول على مزيد من التفاصيل. للحصول على معلومات حول الاشتراك في "مدير إعلانات Google"، يُرجى الانتقال إلى مركز مساعدة "مدير إعلانات Google".

للحصول على معلومات حول الدمج مع منصات أخرى أو استخدام حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية من جهة العميل، يُرجى الاطّلاع على حِزم تطوير البرامج لإعلانات الوسائط التفاعلية.

نظرة عامة على ميزة "إدراج الإعلان الديناميكي" في "برنامج شرك

يتضمّن تنفيذ "الإعلانات الديناميكية أثناء البث" باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA) في CAF عنصرَين رئيسيَّين كما هو موضّح في هذا الدليل:

  • ‫StreamRequest: هو عنصر يحدّد طلب بث إلى خوادم Google الإعلانية. تتوفّر طلبات البث بنوعَين رئيسيَّين:

    • يحدّد LiveStreamRequest مفتاح مادة العرض، بالإضافة إلى مَعلمات اختيارية أخرى.
    • VODStreamRequest: تحدّد هذه السمة معرّف مصدر المحتوى ومعرّف الفيديو بالإضافة إلى معلَمات اختيارية أخرى.
    • يمكن أن يتضمّن كلا نوعَي الطلبات بشكل اختياري مفتاح واجهة برمجة التطبيقات اللازم للوصول إلى مصادر محدّدة، ورمز شبكة في "مدير إعلانات Google" لكي تعالج حزمة تطوير البرامج (SDK) الخاصة بـ IMA معرّفات الإعلانات على النحو المحدّد في إعدادات "مدير إعلانات Google".

  • ‫StreamManager: عنصر يعالج عملية التواصل بين بث الفيديو و"حزمة تطوير البرامج (SDK) لإدراج الإعلانات الديناميكي" في "إعلانات الوسائط التفاعلية"، مثل إرسال إشارات تتبُّع وإعادة توجيه أحداث البث إلى الناشر.

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

ضبط كائنات MediaInfo الخاصة بالمرسِل

أولاً، اضبط عنصر MediaInfo في تطبيق المرسِل ليتضمّن الحقول التالية:

contentId معرّف فريد لعنصر الوسائط هذا
contentUrl عنوان URL الاحتياطي للبث الذي سيتم تحميله في حال تعذّر تنفيذ DAI StreamRequest لأي سبب
streamType بالنسبة إلى أحداث البث المباشر، يجب ضبط هذه القيمة على `LIVE`. أما بالنسبة إلى أحداث الفيديو عند الطلب، فيجب ضبط هذه القيمة على `BUFFERED`.
customData assetKey أحداث البث المباشر فقط تحدّد هذه السمة البث المباشر الذي سيتم تحميله
contentSourceId أحداث البث المباشر للفيديوهات عند الطلب فقط تحدّد هذه السمة خلاصة الوسائط التي تحتوي على البث المطلوب.
videoId أحداث البث المباشر للفيديوهات عند الطلب فقط تحدّد هذه السمة البث المطلوب ضمن خلاصة الوسائط المحدّدة.
networkCode (اختياري) رمز شبكة "مدير إعلانات Google"
ApiKey مفتاح API اختياري يمكن أن يكون مطلوبًا لاسترداد عنوان URL الخاص ببث الفيديو من حزمة تطوير البرامج لإدراج الإعلان الديناميكي (DAI) من "إعلانات الوسائط التفاعلية"
senderCanSkip قيمة منطقية لإعلام جهاز الاستقبال بما إذا كان جهاز الإرسال يتضمّن زر تخطّي، ما يتيح عرض إعلانات قابلة للتخطّي

لضبط هذه القيم في أداة التحكّم في أمر البث، انقر على علامة التبويب تحميل الوسائط، واضبط نوع طلب التحميل المخصّص على LOAD. بعد ذلك، استبدِل بيانات JSON في مربّع النص بأحد كائنات JSON التالية:

مباشر

{
  "media": {
    "contentId": "bbb",
    "contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8",
    "streamType": "LIVE",
    "customData": {
      "assetKey": "c-rArva4ShKVIAkNfy6HUQ",
      "networkCode": "21775744923",
      "ApiKey": "",
      "senderCanSkip": true
    }
  },
  "credentials": "testCredentials"
}

فيديوهات عند الطلب

{
  "media": {
    "contentId": "tos",
    "contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/tos.m3u8",
    "streamType": "BUFFERED",
    "customData": {
      "contentSourceId": "2548831",
      "videoId": "tears-of-steel",
      "networkCode": "21775744923",
      "ApiKey": "",
      "senderCanSkip": true
    }
  },
  "credentials": "testCredentials"
}

يمكن إرسال عنصر طلب التحميل المخصّص هذا إلى جهاز الاستقبال لاختبار الخطوات التالية.

إنشاء جهاز استقبال أساسي في CAF

اتّبِع دليل "المستقبِل الأساسي" في حزمة تطوير البرامج (SDK) لإطار عمل CAF لإنشاء مستقبِل أساسي على الويب.

يجب أن تبدو التعليمات البرمجية الخاصة بجهاز الاستقبال على النحو التالي:

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
  </script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    cast.framework.CastReceiverContext.getInstance().start();
  </script>
</body>
</html>

استيراد حزمة تطوير البرامج (SDK) لـ "إعلانات الوسائط التفاعلية" (IMA) في "البث المباشر" (DAI) والحصول على "أداة إدارة المشغّل"

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

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();

    castContext.start();
  </script>
</body>
</html>

تهيئة "مدير البث" في IMA

ابدأ Stream Manager في حزمة تطوير البرامج (SDK) الخاصة بميزة "الإعلانات الديناميكية أثناء عرض الفيديو" في CAF.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    castContext.start();
  </script>
</body>
</html>

إنشاء أداة اعتراض رسالة التحميل

تستخدِم حزمة تطوير البرامج (SDK) لإدراج الإعلانات الديناميكية (DAI) في CAF معترِض رسالة التحميل في CAF لتقديم طلبات البث واستبدال عنوان URL الخاص بالمحتوى ببث DAI النهائي. يستدعي معترض الرسائل الدالة streamManager.requestStream() التي تتولّى ضبط فواصل الإعلانات وطلب البث واستبدال contentURL الحالي.

يمكن أن يكون هناك معترِض واحد فقط لرسالة التحميل، لذا إذا كان تطبيقك يتطلّب استخدام المعترِض، عليك دمج أي وظائف مخصّصة في معاودة الاتصال نفسها.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    const getStreamRequest = (request) => null;

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, (request) => {
          return streamManager.requestStream(request, getStreamRequest(request))
              .then((request) => {
                this.broadcast('Stream request successful.');
                return Promise.resolve(request);
              })
              .catch((error) => {
                this.broadcast('Stream request failed.');
                return Promise.resolve(request);
              });
        });

    castContext.start();
  </script>
</body>
</html>

إنشاء طلب البث

لإكمال عملية دمج CAF DAI، عليك إنشاء طلب البث باستخدام البيانات التي تم تضمينها في العنصر mediaInfo من المرسِل.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    const getStreamRequest = (request) => {
      const imaRequestData = request.media.customData;
      let streamRequest = null;
      if (imaRequestData.assetKey) {
        // Live stream
        streamRequest = new google.ima.cast.dai.api.LiveStreamRequest();
        streamRequest.assetKey = imaRequestData.assetKey;
      } else if (imaRequestData.contentSourceId) {
        // VOD stream
        streamRequest = new google.ima.cast.dai.api.VODStreamRequest();
        streamRequest.contentSourceId = imaRequestData.contentSourceId;
        streamRequest.videoId = imaRequestData.videoId;
      }
      if (streamRequest && imaRequestData.networkCode) {
        streamRequest.networkCode = imaRequestData.networkCode;
      }
      if (streamRequest && imaRequestData.ApiKey) {
        streamRequest.ApiKey = imaRequestData.ApiKey;
      }
      if (streamRequest && imaRequestData.senderCanSkip) {
        streamRequest.senderCanSkip = imaRequestData.senderCanSkip;
      }
      return streamRequest;
    };

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, (request) => {
          return streamManager.requestStream(request, getStreamRequest(request))
              .then((request) => {
                return Promise.resolve(request);
              })
              .catch((error) => {
                this.broadcast('Stream request failed.');
                return Promise.resolve(request);
              });
        });

    castContext.start();
  </script>
</body>
</html>

يمكنك الآن طلب بث DAI وتشغيله باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ CAF DAI من Google. للاطّلاع على المزيد من الميزات المتقدّمة في حزمة تطوير البرامج (SDK)، راجِع الأدلة الأخرى أو نزِّل تطبيقات نموذجية لجهاز الاستقبال.