תחילת העבודה עם IMA DAI SDK

ערכות ה-SDK של IMA מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות. ערכות ה-SDK של IMA יכולות לבקש מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות. באמצעות ערכות ה-SDK של IMA DAI, האפליקציות שולחות בקשה לשידור של מודעת וידאו ותוכן וידאו – VOD או תוכן בשידור חי. לאחר מכן, ה-SDK מחזיר שידור וידאו משולב, כך שלא תצטרכו לנהל את המעבר בין סרטון המודעה לסרטון התוכן באפליקציה.

בחירת פתרון ה-DAI הרצוי

Pod Serving DAI

המדריך הזה מראה איך להפעיל שידור חי או VOD של מודעות דינמיות (DAI) באמצעות IMA DAI SDK ל-tvOS עם נגן וידאו. כדי להציג או לפעול לפי דוגמה לשילוב מלא, אפשר להוריד את אפליקציית הדוגמה של Pod Serving (ב-Obj C או ב-Swift).

סקירה כללית על הצגת מודעות ב-IMA DAI Pod

כדי להטמיע הצגת מודעות ברצף באמצעות IMA DAI SDK ל-tvOS, צריך שני רכיבים עיקריים:

  • StreamRequest: אובייקט שמגדיר בקשת סטרימינג לשרתים של Google לפרסום. כדי להפעיל את Pod Serving, צריך ליצור אותו באמצעות IMAPodStreamRequest או IMAPodVODStreamRequest. בשתי השיטות נדרשים קוד רשת, וגם ב-IMAPodStreamRequest נדרש מפתח נכס מותאם אישית. מפתח API הוא אופציונלי.

  • IMAStreamManager: אובייקט שמטפל בתקשורת בין מקור הווידאו ל-IMA DAI SDK, למשל הפעלת פינגים למעקב והעברת אירועי מקור לבעלים של האתר.

דרישות מוקדמות

לפני שמתחילים, צריך את הדברים הבאים:

  • Xcode מגרסה 13 ואילך.
  • CocoaPods (מומלץ), Swift Package Manager או עותק שהורדתם של IMA DAI SDK for tvOS.
  • אפליקציית tvOS שכבר מוגדרת עם IMA DAI SDK כדי להפעיל שידורי וידאו עם מודעות DAI. אם עדיין אין לכם אפליקציה כזו, מומלץ להשתמש ב-tvOS DAI BasicExample כנקודת התחלה. ב-BasicExample יש את קוד המקור שמוזכר במדריך הזה. מידע נוסף על הטמעת IMA DAI SDK זמין במדריך למתחילים.

הגדרת משתני ההצגה של Pod

כל השינויים הנדרשים להצגת Pod מתבצעים ב-ViewController.swift ב-Swift או ב-ViewController.m ב-Objective-C. ברירת המחדל של קטעי הקוד במדריך הזה היא שימוש בשפת Swift. השלב הראשון הוא לעדכן את המשתנים הקבועים.

אלה הקבועים של בקשות הסטרימינג של רצפי המודעות שצריך להוסיף:

  • STREAM_URL (משמש רק לשידורים חיים): כתובת ה-URL של סטרימינג הווידאו שסופקה על ידי מנתח המניפסט או על ידי שותף צד שלישי באמצעות הצגת מודעות ברצף. לפני שליחת הבקשה, תתבקשו להזין את מזהה הסטרימינג שסופק על ידי IMA DAI SDK. במקרה כזה, כתובת ה-URL של הסטרימינג כוללת placeholder‏, "[[STREAMID]]", שתוחלף במזהה הסטרימינג לפני שליחת הבקשה.
  • NETWORK_CODE: קוד הרשת של חשבון Ad Manager 360.
  • CUSTOM_ASSET_KEY (משמש רק בשידורים חיים): מפתח הנכס בהתאמה אישית שמזהה את אירוע הצגת המודעות של הפודקאסט ב-Ad Manager 360. אפשר ליצור אותו באמצעות הכלי לעיבוד המניפסט או באמצעות שותף צד שלישי להצגת מודעות ב-Pod.
  • API_KEY (משמש רק בשידורים חיים): מפתח API אופציונלי שעשוי להידרש כדי לאחזר מזהה של שידור מ-IMA DAI SDK.

משנים את הקטע של המשתנה בדוגמה כך שיתאים לקוד הבא:

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

יצירת בקשה לסטרימינג של פודקאסט בשידור חי או ב-VOD

הצגת מודעות ברצף של שידורים חיים

כדי ליצור בקשה לשידור חי של פולד, משנים את השיטה 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)
  }

  ...

הצגת מודעות ב-Pod של שידור VOD

משנים את השיטה requestStream כדי ליצור בקשה להעברת נתונים של רצף VOD, על ידי יצירה של 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
  }

  ...

הצגת מודעות ב-Pod של שידור VOD

משנים את השיטות של 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 DAI

אחרי שתסיימו לבקש ולהציג מודעות בסטרימינג של Pod Serving באמצעות IMA DAI SDK, מומלץ לנקות את המשאבים בסיום הסשן של Pod Serving. צריך להפעיל את הפונקציה IMAStreamManager.destroy() כדי להפסיק את ההפעלה של הסטרימינג, להפסיק את כל המעקב אחר מודעות ולשחרר את כל נכסי הסטרימינג שנטענו.

דוגמאות נוספות לשימוש ב-tvOS SDK זמינות בדוגמאות ב-GitHub.