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

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

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

إدراج إعلان ديناميكي في حزمة

تسهّل حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك.

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

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

يوضّح هذا الدليل كيفية تشغيل بث DAI Pod Serving باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ IMA DAI في CAF.

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

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

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

نظرة عامة على عرض "مجموعات إعلانات" في "إدراج الإعلان الديناميكي" من "الإعلانات التفاعلية"

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

  • ‫StreamRequest: هو عنصر يحدّد طلب بث إلى خوادم Google الإعلانية. تحدّد الطلبات رمز الشبكة ومفتاح مواد العرض المخصّص ومفتاح واجهة برمجة التطبيقات الاختياري، بالإضافة إلى مَعلمات اختيارية أخرى.
  • ‫StreamManager: عنصر يعالج عملية التواصل بين بث الفيديو و"حزمة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية" الخاصة بميزة "الإعلانات الديناميكية أثناء عرض الفيديو"، مثل إرسال طلبات ping للتتبّع وإعادة توجيه أحداث البث إلى الناشر.

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

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

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

الحقل المحتويات
contentId معرّف فريد لعنصر الوسائط هذا.

CONTENT_ID
contentUrl اختياريّ. عنوان URL الخاص بالبث الاحتياطي الذي سيتم تشغيله في حال تعذُّر تحميل بث "إعلانات البث المباشر الديناميكية"

BACKUP_STREAM_URL

contentType اختياريّ. نوع MIME لمجموعات بث النسخ الاحتياطية من المحتوى مطلوب فقط لفيديوهات البث بتنسيق DASH.

CONTENT_STREAM_MIMETYPE
streamType يختلف الحرفي السلسلي أو الثابت المستخدَم لهذه القيمة حسب المنصة التي يرسل منها الشريك.
customData يحتوي الحقل customData على مخزن مفتاح/قيمة للحقول الإضافية المطلوبة. في هذا النموذج، يحتوي على مَعلمات بث "إعلانات البث المباشر". في تطبيق متاح للجميع، يمكنك بدلاً من ذلك تمرير معرّف يستخدمه تطبيق جهاز الاستقبال الخاص ببث المحتوى لاسترداد هذه المَعلمات من خلال طلب من جهة الخادم.
الحقل المحتويات
daiStreamType نوع بث DAI، وهو إما "LIVE" أو "VOD"

DAI_STREAM_TYPE
networkCode رمز الشبكة لحسابك على "مدير إعلانات Google 360"

NETWORK_CODE
customAssetKey هذا الحقل مطلوب لأحداث البث المباشر فقط. مفتاح مادة العرض المخصّصة الذي يحدّد حدث "عرض الإعلانات المتسلسلة" في "مدير إعلانات Google‏ 360".

CUSTOM_ASSET_KEY
apiKey مفتاح واجهة برمجة تطبيقات اختياري لاسترداد معرّف بث من "حزمة تطوير البرامج للإعلانات الديناميكية المدرَجة" في "إعلانات الوسائط التفاعلية"

API_KEY

في ما يلي بعض نماذج الرموز البرمجية لمساعدتك على البدء:

الويب

لضبط هذه القيم في تطبيق مرسل على الويب خاص بـ Cast، عليك أولاً إنشاء عنصر MediaInfo يتضمّن البيانات المطلوبة، ثم إرسال طلب تحميل إلى تطبيق الاستقبال على الويب.

// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "CONTENT_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.LIVE;
mediaInfo.customData = {
  daiStreamType: "DAI_STREAM_TYPE",
  networkCode: "NETWORK-CODE",
  customAssetKey: "CUSTOM_ASSET_KEY",
  apiKey: "API_KEY"
};

// Make load request to cast web receiver
const castSession = cast.framework.CastContext.getInstance().getCurrentSession();
const request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
  () => { console.log('Load succeed'); },
  (errorCode) => { console.log('Error code: ' + errorCode); });

Android

لضبط هذه القيم في تطبيق ويب لإرسال المحتوى باستخدام Cast، عليك أولاً إنشاء عنصر MediaInfo يتضمّن البيانات المطلوبة، ثم إرسال طلب تحميل إلى تطبيق الاستقبال على الويب.

JSONObject customData = new JSONObject()?
  .put("daiStreamType", "DAI_STREAM_TYPE")
  .put("networkCode", "NETWORK-CODE")
  .put("customAssetKey", "CUSTOM_ASSET_KEY")
  .put("apiKey", "API_KEY");
MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
  .setContentUrl("BACKUP_STREAM_URL")
  .setContentType("CONTENT_STREAM_MIMETYPE")
  .setStreamType(MediaInfo.STREAM_TYPE_LIVE)
  .setCustomData(customData)
  .build();

RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());

‫iOS (Obj-C)

لضبط هذه القيم في تطبيق مرسل على الويب خاص بـ Cast، عليك أولاً إنشاء عنصر GCKMediaInformation يتضمّن البيانات المطلوبة، ثم إرسال طلب تحميل إلى تطبيق الاستقبال على الويب.

NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
  @"daiStreamType": @"DAI_STREAM_TYPE",
  @"networkCode": @"NETWORK-CODE",
  @"customAssetKey": @"CUSTOM_ASSET_KEY",
  @"apiKey": @"API_KEY"};
mediaInfoBuilder.customData = customData;

GCKMediaInformationBuilder *mediaInfoBuilder =
  [[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeLive;
mediaInfoBuilder.customData = customData;
self.mediaInformation = [mediaInfoBuilder build];

GCKRequest *request = [self.sessionManager.currentSession.remoteMediaClient loadMedia:self.mediaInformation];
if (request != nil) {
  request.delegate = self;
}

‫iOS (Swift)

لضبط هذه القيم في تطبيق مرسل على الويب خاص بـ Cast، عليك أولاً إنشاء عنصر GCKMediaInformation يتضمّن البيانات المطلوبة، ثم إرسال طلب تحميل إلى تطبيق الاستقبال على الويب.

let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
  print("invalid mediaURL")
  return
}

let customData = [
  "daiStreamType": "DAI_STREAM_TYPE",
  "networkCode": "NETWORK-CODE",
  "customAssetKey": "CUSTOM_ASSET_KEY",
  "region": "API_KEY"
]

let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.Live
mediaInfoBuilder.customData = customData
mediaInformation = mediaInfoBuilder.build()

guard let mediaInfo = mediaInformation else {
  print("invalid mediaInformation")
  return
}

if let request = sessionManager.currentSession?.remoteMediaClient?.loadMedia
(mediaInfo) {
  request.delegate = self
}

أداة CAC

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

{
  "media": {
    "contentId": "CONTENT_ID",
    "contentUrl": "BACKUP_STREAM_URL",
    "contentType": ""CONTENT_STREAM_MIMETYPE"",
    "streamType": "LIVE",
    "customData": {
      "daiStreamType": "DAI_STREAM_TYPE",
      "networkCode": "NETWORK-CODE",
      "customAssetKey": "CUSTOM_ASSET_KEY",
      "oAuthToken": "API_KEY"
    }
  }
}

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

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

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

يجب أن تبدو التعليمات البرمجية الخاصة بجهاز الاستقبال على النحو التالي:

<html>
<head>
  <script
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
  </script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    // ...
  </script>
</body>
</html>

استيراد حزمة تطوير البرامج (SDK) لـ "الإعلانات الديناميكية أثناء البث" من "إعلانات الوسائط التفاعلية" والحصول على "أداة إدارة المشغّل"

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

<html>
<head>
  <script
      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"

تهيئة IMA Stream Manager

<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، أنشئ طلب البث في معترِض رسالة LOAD.

    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    /**
     * Creates a livestream request object for a Pod Serving stream.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {StreamRequest} an IMA stream request
     */
    const createStreamRequest = (castRequest) => { /* ... */};

    /**
     * Initates a DAI stream request for the final stream manifest.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
     */
    const createDAICastRequest = (castRequest) => {
        return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
          .then((castRequestWithPodStreamData) => {
            console.log('Successfully made DAI stream request.');
            // ...
            return castRequestWithPodStreamData;
          })
          .catch((error) => {
            console.log('Failed to make DAI stream request.');
            // CAF will automatically fallback to the content URL
            // that it can read from the castRequest object.
            return castRequest;
          });
    };

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, createDAICastRequest);

    castContext.start();

إنشاء طلب البث

أكمِل الدالة createStreamRequest لإنشاء بث Pod Serving استنادًا إلى طلب تحميل CAF.

    /**
     * Creates a livestream request object for a Pod Serving stream.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {StreamRequest} an IMA stream request
     */
    const createStreamRequest = (castRequest) => {
      const customData = castRequest.media.customData;
      let streamRequest;
      if (customData.daiStreamType == "LIVE") {
        streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
        streamRequest.customAssetKey = customData.customAssetKey;
        streamRequest.networkCode = customData.networkCode;
        streamRequest.apiKey = customData.apiKey;
      } else if (customData.daiStreamType == "VOD") {
        streamRequest = new google.ima.cast.dai.api.PodVodStreamRequest();
        streamRequest.networkCode = customData.networkCode;
        streamRequest.apiKey = customData.apiKey;
      }
      return streamRequest;
    };

استرداد بيان التطبيق المدمج من VTP

إذا تم طلب البث بنجاح، استخدِم streamManager.getStreamId() لاسترداد معرّف البث. سيقدّم لك "شريكك التقني للفيديوهات" (VTP) أو أداة تعديل ملف البيان المخصّص تعليمات لاسترداد عنوان URL لملف البيان باستخدام معرّف البث هذا.

بعد استرداد عنوان URL لملف البيان، استبدِل contentUrl الحالي بـ manifestUrl الجديد.

أخيرًا، قبل عرض بيان البث المعدَّل، استدعِ الطريقة loadStreamMetadata في streamManager لإعلام حزمة IMA SDK بأنّه يمكنها طلب بيانات البث الوصفية بأمان. هذه المكالمة ضرورية فقط لبث الفيديو عند الطلب.

    /**
     * Initates a DAI stream request for the final stream manifest.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
     */
    const createDAICastRequest = (castRequest) => {
        return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
          .then((castRequestWithPodStreamData) => {
            console.log('Successfully made DAI stream request.');

            // This is a sample VTP integration. Consult your VTP documentation
            // for how to retrieve an ad-stitched stream manifest URL.
            const manifestTemplate = "https://.../manifest.m3u8?gam_stream_id=[[STREAMID]]";
            const streamId = streamManager.getStreamId();
            const manifestUrl = manifestTemplate.replace('[[STREAMID]]', streamId)
            // Assign your manifestUrl to the request's content URL.
            castRequestWithPodStreamData.media.contentUrl = manifestUrl;

            // After generating the manifest URL, VOD streams must notify the
            // IMA SDK that it is safe to request ad pod metadata.
            // This is only necessary for VOD streams. It is a no-op for
            // livestreams, so no conditional is needed.
            streamManager.loadStreamMetadata();

            return castRequestWithPodStreamData;
          })
          .catch((error) => {
            console.log('Failed to make DAI stream request.');
            // CAF will automatically fallback to the content URL
            // that it can read from the castRequest object.
            return castRequest;
          });
    };

تنظيم مواد عرض IMA DAI

عند الانتهاء بنجاح من طلب الإعلانات وعرضها في بث Pod Serving باستخدام حزمة تطوير البرامج IMA DAI SDK، ننصحك بتنظيف أي موارد بعد اكتمال جلسة Pod Serving. اتّصِل بالرقم StreamManager.destroy() لإيقاف تشغيل البث المباشر، وإيقاف جميع عمليات تتبُّع الإعلانات، وإصدار جميع مواد عرض البث المباشر التي تم تحميلها.