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

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

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

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

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

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

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

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

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

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

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

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

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

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

ضبط كائنات 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 Command and Control، انقر على علامة التبويب "تحميل الوسائط" (Load Media)، واضبط نوع طلب التحميل المخصّص على 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) لـ "إعلانات الوسائط التفاعلية" (IMA) في "البث المباشر" (DAI) والحصول على "أداة إدارة المشغّل"

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

<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

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