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

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

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

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

يوضّح هذا الدليل كيفية تشغيل بث مباشر أو فيديو عند الطلب يتضمّن مجموعات إعلانات ديناميكية، وذلك باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA DAI SDK) لنظام التشغيل iOS مع مشغّل فيديو. للاطّلاع على تكامل مكتمل أو اتّباعه، يمكنك تنزيل مثال على عرض حِزم Pod لـ Objective-C أو Swift.

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

يتضمّن تنفيذ عرض مجموعات الإعلانات باستخدام حزمة تطوير البرامج (SDK) لعرض الإعلانات الديناميكية في "إعلانات الوسائط التفاعلية" لنظام التشغيل iOS مكوّنَين أساسيَّين:

  • ‫StreamRequest: عنصر يحدّد طلب بث إلى خوادم Google الإعلانية. يجب إنشاؤها باستخدام IMAPodStreamRequest أو IMAPodVODStreamRequest لتفعيل ميزة "عرض الحِزم". تتطلّب كلتا الطريقتَين استخدام رمز الشبكة، ويتطلّب IMAPodStreamRequest أيضًا استخدام مفتاح مادة العرض المخصّصة. مفتاح واجهة برمجة التطبيقات هو اختياري.

  • ‫IMAStreamManager: عنصر يعالج التواصل بين مجرى الفيديو وحزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية (IMA DAI SDK)، مثل تنشيط إشارات التتبّع و forwarded stream events إلى الناشر.

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

قبل البدء، يجب توفّر ما يلي:

  • الإصدار 13 من Xcode أو إصدار أحدث
  • CocoaPods (الخيار المفضّل) أو Swift Package Manager أو نسخة تم تنزيلها من حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية لنظام التشغيل iOS
  • تطبيق iOS تم إعداده مسبقًا باستخدام حزمة تطوير البرامج لميزة "إدراج الإعلانات الديناميكي" في إعلانات الوسائط التفاعلية لتشغيل أحداث بث الفيديو مع إعلانات ميزة "إدراج الإعلانات الديناميكي" إذا لم يكن لديك تطبيق مماثل، ننصحك باستخدام المثال التالي: iOS DAI BasicExample كنقطة بدء. يحتوي BasicExample على قاعدة البيانات المُشار إليها في هذا الدليل. لمزيد من المعلومات حول كيفية تنفيذ حزمة تطوير البرامج لعرض الإعلانات الديناميكية في الفيديو من IMA، يُرجى الاطّلاع على دليل البدء السريع.

إعداد متغيّرات عرض الحِزم

يتم إجراء جميع التغييرات اللازمة لعرض مجموعة التطبيقات في ViewController.swift في swift أو ViewController.m في Objective-C. تستخدم المقتطفات في هذا الدليل لغة Swift بشكل تلقائي. الخطوة الأولى هي تعديل المتغيّرات الثابتة.

في ما يلي الثوابت لطلب بث مجموعة الإعلانات المتسلسلة التي يجب إضافتها:

  • STREAM_URL (يُستخدَم فقط للبث المباشر): عنوان URL لبث الفيديو المقدَّم من محرِّك البيان أو شريك خارجي يستخدم ميزة "عرض مجموعة المحتوى" من المفترض أن يُطلب منك إدخال معرّف البث المقدَّم من حزمة تطوير البرامج (SDK) لميزة DAI في IMA قبل إرسال طلب. في هذه الحالة، يتضمّن عنوان URL للبث عنصر نائب، وهو"[[STREAMID]]"، ويتم استبداله بمعرّف البث قبل تقديم طلب.
  • NETWORK_CODE: رمز الشبكة لحسابك على "مدير إعلانات Google‏ 360".
  • CUSTOM_ASSET_KEY (يُستخدَم فقط مع أحداث البث المباشر): مفتاح مادة العرض المخصّصة الذي يحدّد حدث عرض مجموعة الإعلانات المتسلسلة في "مدير إعلانات Google‏ 360". يمكن أن يتم إنشاء هذا الملف من قِبل محرِّر البيان أو شريك عرض مجموعات المحتوى التابع لجهة خارجية.
  • ‫API_KEY (يُستخدَم فقط مع أحداث البث المباشر): مفتاح اختياري لواجهة برمجة التطبيقات يمكن أن يكون مطلوبًا لاسترداد معرّف البث من حزمة تطوير البرامج لميزة "إدراج الإعلان الديناميكي" في إعلانات الوسائط التفاعلية.

غيِّر قسم المتغيّرات في المثال ليتطابق مع ما يلي:

...
class ViewController:
  UIViewController,
  IMAAdsLoaderDelegate,
  IMAStreamManagerDelegate,
  AVPlayerViewControllerDelegate
{
  static let streamUrl =
    "https://encodersim.sandbox.google.com/masterPlaylist/9c654d63-5373-4673-8c8d-6d92b66b9d46/master.m3u8?gen-seg-redirect=true&network=51636543&event=google-sample&pids=devrel4628000,devrel896000,devrel3528000,devrel1428000,devrel2628000,devrel1928000&seg-host=dai.google.com&stream_id=[[STREAMID]]"
  static let networkCode = "51636543"
  static let customAssetKey = "google-sample"
  static let APIKey = ""
  static let backupStreamURLString =
    "http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/master.m3u8"

  var adsLoader: IMAAdsLoader?
  ...

إنشاء طلب لبث مجموعة فيديوهات في وقت واحد، سواء كان بثًا مباشرًا أو فيديوهات عند الطلب

عرض مجموعات البث المباشر

عدِّل طريقة requestStream لإنشاء طلب بث مباشر من خلال إنشاء مثيل لـ IMAPodStreamRequest.

  ...

  func requestStream() {
    guard let playerViewController = self.playerViewController else return
    guard let adContainerView = self.adContainerView else return
    guard let adsLoader = self.adsLoader else return

    self.videoDisplay = IMAAVPlayerVideoDisplay(avPlayer: playerViewController.player)
    adDisplayContainer = IMAAdDisplayContainer(
      adContainer: adContainerView, viewController: self)

    // Create a podserving stream request.
    request = IMAPodStreamRequest(
      networkCode: self.networkCode,
      customAssetKey: self.customAssetKey,
      adDisplayContainer: adDisplayContainer,
      videoDisplay: self.videoDisplay,
      userContext: nil)

    adsLoader.requestStream(with: request)
  }

  ...

عرض مجموعة فيديوهات مسجّلة

عدِّل طريقة requestStream لإنشاء طلب بث مجموعة فيديوهات عند الطلب من خلال إنشاء مثيل لـ IMAPodVODStreamRequest.

  ...

  func requestStream() {
    guard let playerViewController = self.playerViewController else return
    guard let adContainerView = self.adContainerView else return
    guard let adsLoader = self.adsLoader else return

    self.videoDisplay = IMAAVPlayerVideoDisplay(avPlayer: playerViewController.player)
    adDisplayContainer = IMAAdDisplayContainer(
      adContainer: adContainerView, viewController: self)

    // Create a podserving stream request.
    request = IMAPodVODStreamRequest(
      networkCode: self.networkCode,
      adDisplayContainer: adDisplayContainer,
      videoDisplay: self.videoDisplay,
      userContext: nil)

    adsLoader.requestStream(with: request)
  }

  ...

تعديل عنوان URL للبث وضبطه

عرض مجموعات البث المباشر

عدِّل طرق IMAAdsLoaderDelegate باستخدام streamManager.streamId للحصول على معرّف مصدر البيانات. بعد ذلك، أدخِل معرّف البث في STREAM_URL، بدلاً من "[[STREAMID]]". بعد إجراء هذا التغيير، يمكن ضبط عنوان URL الجديد للبث باستخدام videoDisplay.loadStream().

  ...

  // MARK: - IMAAdsLoaderDelegate

  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    let streamManager = adsLoadedData.streamManager
    let streamId = streamManager.streamId
    let urlString = streamUrl.replacingOccurrences(of: "[[STREAMID]]", with: streamId)
    let loadedStreamUrl = URL(string:urlString)
    self.videoDisplay.loadStream(loadedStreamUrl, subtitles:@[])
    self.videoDisplay.play()
    streamManager.delegate = self
    streamManager.initialize(with: nil)
    self.streamManager = streamManager
  }

  ...

عرض مجموعة فيديوهات مسجّلة

عدِّل طرق IMAAdsLoaderDelegate باستخدام streamManager.streamId للحصول على معرّف مصدر البيانات. بعد ذلك، اطلب عنوان URL للبث من شريك تكنولوجيا الفيديو (VTP). بعد ذلك، اتصل بـ IMAStreamManager.loadThirdPartyStream() لطلب تحميل IMA عنوان URL للبث وأي مقاطع ترجمة وشرح يعرضها TVP.

  ...

  // MARK: - IMAAdsLoaderDelegate

  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    let streamManager = adsLoadedData.streamManager
    let streamId = streamManager.streamId
    // 'vtpInterface' is a place holder for your own video technology partner
    // (VTP) API calls.
    let streamUrl = vtpInterface.requestStreamURL(streamID)
    self.streamManager.loadThirdPartyStream(streamUrl, streamSubtitles:@[])
    streamManager.delegate = self
    streamManager.initialize(with: nil)
    self.streamManager = streamManager
  }

تنظيف مواد عرض "الإعلانات الديناميكية أثناء عرض الفيديو" في IMA

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

للاطّلاع على أمثلة أخرى على استخدام حزمة تطوير البرامج (SDK) لنظام التشغيل iOS، يُرجى الاطّلاع على عيّنات على GitHub.