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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لضبط هذه القيم في أداة التحكّم بطلبات البث، انقر على علامة التبويب Load Media (تحميل الوسائط)، واضبط نوع طلب التحميل المخصّص على 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 Basic Receiver" لإنشاء أداة استقبال ويب أساسية.

يجب أن يظهر رمز جهاز الاستقبال على النحو التالي:

<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 والحصول على أداة إدارة المشغّل

أضِف علامة نصية لاستيراد حزمة تطوير البرامج (SDK) لميزة DAI في IMA لتنسيق CAF إلى مستقبل الويب، مباشرةً بعد loading 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>

بدء تشغيل IMA Stream Manager

اضبط 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 الحالي.

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

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

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