لمناقشة منتجاتنا وتقديم ملاحظات بشأنها، انضمّ إلى قناة Discord الرسمية في "مدير إعلانات Google" على خادم منتدى Google للإعلان والقياس.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

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

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

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

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

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

نظرة عامة على "إدراج الإعلان الديناميكي" في "اتفاقية الشركاء

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

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

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

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

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

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

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

اتّبِع "دليل أداة استقبال 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 DAI إلى تطبيق "المستقبِل على الويب"، وذلك بعد تحميل النص البرمجي الخاص بـ 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) الخاصة ببث المحتوى الديناميكي وإدخال الإعلانات (DAI) في "إطار عمل البث المباشر" (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>

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