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

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

إدراج إعلان ديناميكي في مجموعة الإعلانات

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

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

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

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

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

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

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

نظرة عامة على عرض الإعلانات المتسلسلة لإعلانات الوسائط التفاعلية

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

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

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

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

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

أولاً، اضبط إعدادات التطبيق عنصر MediaInfo لتضمين الحقول التالية:

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

CONTENT_ID

contentUrl اختياريّ. عنوان URL احتياطي للبث لتشغيله في حال تعذّر تحميل البث DAI

BACKUP_STREAM_URL

contentType اختياريّ. نوع Mime لمجموعات البث الاحتياطية للمحتوى مطلوب فقط لـ DASH ساحات المشاركات.

CONTENT_STREAM_MIMETYPE

streamType تختلف السلسلة الحرفية أو الثابتة المستخدمة لهذه القيمة حسب المُرسِل بدون خادم.
customData يحتوي الحقل customData على مخزن مفتاح وقيم إضافية الحقول المطلوبة.
الحقل المحتويات
manifestUrl عنوان URL لبث الفيديو الذي توفّره الجهة المسؤولة عن التحكّم في البيان أو الجهة الخارجية شريك. من المفترض أن يُطلَب منك إدخال معرّف مصدر البيانات الذي يوفّره. حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية قبل تقديم طلب في هذا النموذج، قد يكون عنوان URL الخاص بالبيان يشتمل على العنصر النائب، [[STREAMID]]، الذي يتم استبداله معرّف مصدر البيانات قبل تقديم طلب.

MANIFEST_URL

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 = {
manifestUrl: "MANIFEST_URL",
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("manifestUrl", "MANIFEST_URL")
  .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 = @{
  @"manifestUrl": @"MANIFEST_URL",
  @"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 = [
  "liveConfigID": "MANIFEST_URL",
  "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

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

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

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

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

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

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

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

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

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

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

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

<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، يجب إنشاء طلب البث في تحميل الرسالة جهة الاعتراض.

    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 لإنشاء ساحة مشاركات تعرض مجموعة إعلانات متسلسلة. على طلب تحميل 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 streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
      const customData = castRequest.media.customData;

      streamRequest.customAssetKey = customData.customAssetKey;
      streamRequest.networkCode = customData.networkCode;
      streamRequest.apiKey = customData.apiKey;

      return streamRequest;
    };

استبدال عنوان URL للمحتوى بعنوان URL الخاص بالبيان ومعرّف مصدر البيانات

إذا تم قبول طلب البث، استخدِم streamManager.getStreamId() استرداد معرّف البث وإدراجه في البيانو في عنوان URL، مع استبدال [[STREAMID]] بعد ذلك، استبدِل contentUrl الحالية بأخرى جديدة. manifestUrl لكي يشغِّل CAF البث المباشر مع مجموعات الإعلانات المتسلسلة المُركّبة.

    /**
     * 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.');
            const media = castRequestWithPodStreamData.media;
                const manifestUrl = media.customData.manifestUrl || "";
                if (manifestUrl) {
                    console.log('Replacing the contentURL with the manifest URL and stream ID');
                    const streamId = streamManager.getStreamId();
                    castRequestWithPodStreamData.media.contentUrl = manifestUrl.replace('[[STREAMID]]', streamId);

            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;
          });
    };

يمكنك الآن طلب بث مجموعات الإعلانات المتسلسلة وتشغيلها باستخدام تطبيق البث. إطار العمل وحزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية لـ CAF.