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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

إعداد كائنات 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`

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

الويب

لضبط هذه القيم في مرسِل الويب للبث، عليك أولاً إنشاء كائن 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)

لضبط هذه القيم في مرسِل الويب للبث، عليك أولاً إنشاء كائن 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)

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.