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

اختيار حل DAI الذي يهمّك

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

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

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

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

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

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

إنّ تنفيذ ميزة DAI باستخدام حزمة IMA CAF DAI SDK يتضمّن مكوّنَين أساسيَين كما هو موضّح في هذا الدليل:

• StreamRequest: كائن يحدِّد طلب بث المحتوى إلى خوادم الإعلانات في Google. تنقسم طلبات البث إلى نوعَين أساسيَين:

  • LiveStreamRequest: يحدّد مفتاح مادة العرض ومفتاح واجهة برمجة التطبيقات الاختياري، بالإضافة إلى معلَمات اختيارية أخرى.
  • VODStreamRequest: يجب تحديد معرّف مصدر المحتوى ومعرّف الفيديو ومفتاح واجهة برمجة التطبيقات الاختياري، بالإضافة إلى معلَمات اختيارية أخرى.

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

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

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

ضبط كائنات MediaInfo للمُرسِل

أولاً، اضبط MediaInfo object لتطبيق المرسل ليتضمن الحقول التالية:

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

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

بث مباشر

{
  "media": {
    "contentId": "bbb",
    "contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8",
    "streamType": "LIVE",
    "customData": {
      "assetKey": "sN_IYUG8STe1ZzhIIE_ksA",
      "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",
      "ApiKey": "",
      "senderCanSkip": true
    }
  },
  "credentials": "testCredentials"
}

يمكن إرسال كائن طلب التحميل المخصّص هذا إلى المستلِم لاختبار الخطوات التالية.

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

باتّباع دليل جهاز الاستقبال الأساسي لـ CAF SDK، أنشئ مستقبِل ويب أساسيًا.

من المفترض أن يظهر رمز المُستلِم على النحو التالي:

<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>

استورِد حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية واحصل على "مدير المشغّل"

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

<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>

إعداد مدير بث إعلانات الوسائط التفاعلية

يجب إعداد إدارة البث في CAF DAI SDK.

<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>

إنشاء اعتراض تحميل الرسائل

تستخدم حزمة CAF DAI SDK أداة اعتراض الرسائل لتحميل عناصر 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.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 وتشغيلها باستخدام حزمة CAF DAI SDK من Google. لمعرفة المزيد من المعلومات عن ميزات حِزم SDK المتقدّمة، يمكنك الاطّلاع على الأدلة الأخرى أو تنزيل نماذج تطبيقات المُستلِم.