تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

اختيار حلّ DAI المطلوب

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

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

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

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

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

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

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

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

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

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

إعداد كائنات MediaInfo للمُرسِل

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

`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 أساسي

باتباع دليل استقبال حزمة تطوير البرامج (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>

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

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

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

يجب إعداد مدير البث في حزمة 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>

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

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