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

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

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

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

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

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

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

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

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

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

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

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

يتم إجراء جميع التغييرات اللازمة لعرض الوحدات في 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 لنظام التشغيل tvOS، يُرجى الاطّلاع على عيّنات على GitHub.