الإعداد باستخدام "إدراج الإعلان الديناميكي" (DAI) مع الخدمة الكاملة

اختيار النظام الأساسي: HTML5 Android iOS tvOS Cast Roku

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

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

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

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

نظرة عامة على CAF DAI

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

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

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

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

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

  • حساب على Cast Developer Console يتضمّن جهازًا تجريبيًا مسجَّلاً
  • تطبيق ويب مستقبِل مستضاف ومسجَّل في Cast Developer Console ويمكن تعديله لاستضافة الرمز البرمجي المقدَّم في هذا الدليل
  • تطبيق إرسال تم ضبطه لاستخدام تطبيق استقبال البث على الويب. يستخدم هذا المثال أداة Cast Command and Control كمرسِل.

ضبط عناصر MediaInfo الخاصة بالمرسِل

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

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

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

LIVE

{
  "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) لمنصة Google Cast Application Framework (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 والحصول على Player Manager

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

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