歡迎加入 Google 廣告與評估社群伺服器的官方 Ad Manager Discord 頻道，與成員一起討論產品並提供意見回饋。

本頁面由 Cloud Translation API 翻譯而成。

設定 DAI 專用的 IMA SDK

選取平台： HTML5 Android iOS tvOS Cast Roku

使用 IMA SDK，即可輕鬆將多媒體廣告整合至網站和應用程式。IMA SDK 可向任何符合 VAST 規定的廣告伺服器請求廣告，並在應用程式中管理廣告播放。應用程式可透過 IMA DAI SDK，對廣告和內容影片 (隨選影片或直播內容) 提出串流請求。SDK 接著會傳回合併的影片串流，因此您不必在應用程式中管理廣告和內容影片之間的切換。

選取您感興趣的 DAI 解決方案

全方位服務 DAI

本指南說明如何將 IMA DAI SDK 整合至簡易影片播放器應用程式。如要查看或跟著操作完整的範例整合，請從 GitHub 下載 BasicExample。

IMA DAI 總覽

如本指南所示，導入 IMA DAI 需使用三個主要 SDK 元件：

IMAAdDisplayContainer：位於影片播放元素頂端的容器物件，用於存放廣告 UI 元素。
IMAAdsLoader：這個物件會要求串流，並處理串流要求回應物件觸發的事件。您應只例項化一個廣告載入器，並在應用程式的整個生命週期內重複使用。
IMAStreamRequest：IMAVODStreamRequest 或 IMALiveStreamRequest：定義串流要求的物件。串流請求可以是隨選影片或直播串流。直播串流請求會指定素材資源金鑰，而 VOD 請求則會指定 CMS ID 和影片 ID。這兩種要求類型都可以選擇性地加入存取指定串流所需的 API 金鑰，以及 Google Ad Manager 聯播網代碼，供 IMA SDK 處理廣告 ID，如 Google Ad Manager 設定中所指定。
IMAStreamManager：這個物件會處理動態廣告插播串流，以及與 DAI 後端的互動。串流管理工具也會處理追蹤 Ping，並將串流和廣告事件轉送給發布商。

必要條件

開始之前，請先備妥下列項目：

Xcode 13 以上版本
Swift Package Manager、 CocoaPods，或 tvOS 適用的 IMA DAI SDK 下載副本

建立新的 Xcode 專案

在 Xcode 中，使用 Objective-C 建立新的 tvOS 專案。使用 BasicExample 做為專案名稱。

將 IMA DAI SDK 新增至 Xcode 專案

請使用下列任一方法安裝 IMA DAI SDK。

使用 Swift Package Manager 安裝 SDK

自 4.8.2 版起，互動式媒體廣告 SDK 支援 Swift Package Manager。請按照下列步驟匯入 Swift 套件。

在 Xcode 中，依序前往「File」(檔案) >「Add Packages」(新增套件)，然後安裝 GoogleInteractiveMediaAds Swift Package。
使用畫面顯示的提示詞框，搜尋「GoogleInteractiveMediaAds Swift Package GitHub repository」：
```
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
```
選取要使用的 GoogleInteractiveMediaAds Swift Package 版本。如果是新專案，建議選用「Up to Next Major Version」(升級至下一個主要版本)。

完成後，Xcode 會解析套件依附元件，並在背景下載。如要進一步瞭解如何新增套件依附元件，請參閱 Apple 的文章。

使用 CocoaPods 安裝 SDK

CocoaPods 是 Xcode 專案的依附元件管理工具，建議您使用這個工具安裝 IMA DAI SDK。如要進一步瞭解如何安裝或使用 CocoaPods，請參閱 CocoaPods 說明文件。安裝 CocoaPods 後，請按照下列操作說明安裝 IMA DAI SDK：

在 BasicExample.xcodeproj 檔案所在的目錄中，建立名為 Podfile 的文字檔案，並新增下列設定：

source 'https://github.com/CocoaPods/Specs.git'
platform :tvos, '15'
target "BasicExample" do
  pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0'
end

在包含 Podfile 的目錄中執行下列指令：
```
pod install --repo-update
```
開啟 BasicExample.xcworkspace 檔案，確認其中包含兩個專案：BasicExample 和 Pods (CocoaPods 安裝的依附元件)，藉此確認安裝是否成功。

手動下載及安裝 SDK

如果不想使用 Swift Package Manager 或 CocoaPods，可以下載 IMA DAI SDK，然後手動新增至專案。

顯示操作說明

前往下載頁面，下載並解壓縮最新版 IMA DAI SDK。
開啟 BasicExample.xcodeproj。
在左側窗格中，按一下專案名稱。
在中間窗格中，按一下「Build Phases」。
展開「Link Binary With Libraries」部分。
在程式庫清單底部，按一下加號圖示「[+]」。
按一下「新增其他」。
在您解壓縮下載 SDK 的目錄中，選取「GoogleInteractiveMediaAds.framework」，然後按一下「Open」。
在程式庫清單底部，再次點按加號圖示 [+]。
在「狀態」欄中，確認 GoogleInteractiveMediaAds.framework 已設為 Required。
在建構設定中加入 -ObjC 連接器標記。詳情請參閱 Apple QA1490。

匯入 IMA SDK

使用匯入陳述式新增 IMA 架構：

Objective-C

#import "ViewController.h"
#import <AVKit/AVKit.h>

@import GoogleInteractiveMediaAds;ViewController.m

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
ViewController.swift

建立影片播放器並整合 IMA SDK

以下範例會初始化 IMA SDK：

Objective-C

// Live stream asset key, VOD content source and video IDs, and backup content URL.
static NSString *const kAssetKey = @"c-rArva4ShKVIAkNfy6HUQ";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";
static NSString *const kBackupStreamURLString =
    @"http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/"
    @"master.m3u8";
static const StreamType kDefaultStreamType = StreamTypeLive;

@interface ViewController () <IMAAdsLoaderDelegate,
                              IMAStreamManagerDelegate,
                              AVPlayerViewControllerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) id<IMAVideoDisplay> videoDisplay;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];
  self.streamType = kDefaultStreamType;
  [self setupAdsLoader];
  [self setupPlayer];
  [self setupAdContainer];
}

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestStream];
}

- (void)setupPlayer {
  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach video player to view hierarchy.
  [self addChildViewController:self.playerViewController];
  [self.view addSubview:self.playerViewController.view];
  self.playerViewController.view.frame = self.view.bounds;
  [self.playerViewController didMoveToParentViewController:self];
}ViewController.m

Swift

class ViewController:
  UIViewController,
  IMAAdsLoaderDelegate,
  IMAStreamManagerDelegate,
  AVPlayerViewControllerDelegate
{
  // Live stream asset key, VOD content source and video IDs, Google Ad Manager network code, and
  // backup content URL.
  static let assetKey = "c-rArva4ShKVIAkNfy6HUQ"
  static let contentSourceID = "2548831"
  static let videoID = "tears-of-steel"
  static let networkCode = "21775744923"
  static let backupStreamURLString =
    "http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/master.m3u8"

  var adsLoader: IMAAdsLoader?
  var videoDisplay: IMAAVPlayerVideoDisplay!
  var adDisplayContainer: IMAAdDisplayContainer?
  var adContainerView: UIView?
  private var streamManager: IMAStreamManager?
  private var contentPlayhead: IMAAVPlayerContentPlayhead?
  private var playerViewController: AVPlayerViewController!
  private var userSeekTime = 0.0
  private var adBreakActive = false

  private enum StreamType {
    case live
    /// Video on demand.
    case vod
  }

  /// Set the stream type here.
  private let currentStreamType: StreamType = .live

  deinit {
    NotificationCenter.default.removeObserver(self)
  }

  override func viewDidLoad() {
    super.viewDidLoad()
    self.view.backgroundColor = UIColor.black

    setupAdsLoader()
    setupPlayer()
    setupAdContainer()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    requestStream()
  }

  func setupPlayer() {
    let player = AVPlayer()
    let playerViewController = AVPlayerViewController()
    playerViewController.delegate = self
    playerViewController.player = player

    // Set up our content playhead and contentComplete callback.
    contentPlayhead = IMAAVPlayerContentPlayhead(avPlayer: player)
    NotificationCenter.default.addObserver(
      self,
      selector: #selector(ViewController.contentDidFinishPlaying(_:)),
      name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
      object: player.currentItem)

    self.addChild(playerViewController)
    playerViewController.view.frame = self.view.bounds
    self.view.insertSubview(playerViewController.view, at: 0)
    playerViewController.didMove(toParent: self)
    self.playerViewController = playerViewController
  }ViewController.swift

在 viewDidLoad() 中，setupAdsLoader() 會建立 IMAAdsLoader，setupPlayer() 會建立 AVPlayerViewController，而 setupAdContainer() 則會準備 UIView 以顯示廣告。檢視畫面顯示後，viewDidAppear() 會呼叫 requestStream() 來要求 DAI 串流。

如要定義串流要求參數，這個範例會使用常數，例如直播的 asset key，或是 VOD 串流的 content source ID 和 video ID。此外，這個範例也使用下列元件管理 IMA SDK：

adsLoader：處理對 Google Ad Manager 的串流請求。建議您在應用程式的生命週期內使用單一執行個體。
videoDisplay：這項 IMAVideoDisplay 實作項目可讓 IMA 使用 AVPlayer 控制影片播放，並追蹤播放事件。
adDisplayContainer：管理用於算繪廣告 UI 元素的檢視區塊，並在廣告插播期間處理 UI 焦點。
streamManager：管理合併廣告和內容串流的播放作業，並使用其委派項目傳送廣告生命週期事件。
playerViewController：tvOS 播放器，用於呈現 IMA SDK 管理的影片串流。
adBreakActive：表示是否正在播放廣告插斷的布林值標記，用於防止略過廣告及管理 UI 焦點。

實作 IMAAdsLoader

接著，例項化 IMAAdsLoader，並將廣告容器檢視區塊附加至檢視區塊階層。

Objective-C

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] init];
  self.adsLoader.delegate = self;
}

- (void)setupAdContainer {
  // Attach the ad container to the view hierarchy on top of the player.
  self.adContainerView = [[UIView alloc] init];
  [self.view addSubview:self.adContainerView];
  self.adContainerView.frame = self.view.bounds;
  // Keep hidden initially, until an ad break.
  self.adContainerView.hidden = YES;
}ViewController.m

Swift

func setupAdsLoader() {
  let adsLoader = IMAAdsLoader(settings: nil)
  adsLoader.delegate = self
  self.adsLoader = adsLoader
}

func setupAdContainer() {
  // Attach the ad container to the view hierarchy on top of the player.
  let adContainerView = UIView()
  self.view.addSubview(adContainerView)
  adContainerView.frame = self.view.bounds
  // Keep hidden initially, until an ad break.
  adContainerView.isHidden = true
  self.adContainerView = adContainerView
}ViewController.swift

提出串流要求

建立幾個常數來保存串流資訊，然後實作串流要求函式來提出要求。

Objective-C

- (void)requestStream {
  self.videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
  self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView
                                                                viewController:self];

  // Use the streamType property to determine which request to create.
  IMAStreamRequest *request;

  switch (self.streamType) {
    case StreamTypeLive: {
      request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                                   networkCode:kNetworkCode
                                            adDisplayContainer:self.adDisplayContainer
                                                  videoDisplay:self.videoDisplay
                                                   userContext:nil];
      NSLog(@"IMA: Requesting Live Stream with Asset Key: %@.", kAssetKey);
      break;
    }
    case StreamTypeVOD: {
      request = [[IMAVODStreamRequest alloc] initWithContentSourceID:kContentSourceID
                                                             videoID:kVideoID
                                                         networkCode:kNetworkCode
                                                  adDisplayContainer:self.adDisplayContainer
                                                        videoDisplay:self.videoDisplay
                                                         userContext:nil];
      NSLog(@"IMA: Requesting VOD Stream with Video ID: %@.", kVideoID);
      break;
    }
  }

  if (request) {
    [self.adsLoader requestStreamWithRequest:request];
  } else {
    // Fallback or error handling if no request object was created
    NSLog(@"IMA Error: Could not create stream request for unknown type.");
    [self playBackupStream];
  }
}ViewController.m

Swift

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!)
  let adDisplayContainer = IMAAdDisplayContainer(
    adContainer: adContainerView, viewController: self)
  self.adDisplayContainer = adDisplayContainer

  // Variable to hold the specific stream request object.
  let request: IMAStreamRequest

  switch self.currentStreamType {
  case .live:
    // Create a live stream request.
    request = IMALiveStreamRequest(
      assetKey: ViewController.assetKey,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer,
      videoDisplay: self.videoDisplay,
      pictureInPictureProxy: nil,
      userContext: nil)
    print("IMA: Requesting Live Stream with asset key \(ViewController.assetKey)")

  case .vod:
    // Create a VOD stream request.
    request = IMAVODStreamRequest(
      contentSourceID: ViewController.contentSourceID,
      videoID: ViewController.videoID,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer,
      videoDisplay: self.videoDisplay,
      pictureInPictureProxy: nil,
      userContext: nil)
    print(
      "IMA: Requesting VOD Stream with content source ID \(ViewController.contentSourceID) and "
        + "video ID \(ViewController.videoID)")
  }

  adsLoader.requestStream(with: request)
}ViewController.swift

處理串流事件

IMAAdsLoader 和 IMAStreamManager 會觸發事件，用於處理初始化、錯誤和串流狀態變化。這些事件會透過 IMAAdsLoaderDelegate 和 IMAStreamManagerDelegate 協定觸發。監聽廣告載入事件並初始化串流。如果廣告無法載入，請改為播放備用串流。

Objective-C

- (void)playBackupStream {
  NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
  [self.videoDisplay loadStream:backupStreamURL withSubtitles:@[]];
  [self.videoDisplay play];
  [self startMediaSession];
}

- (void)startMediaSession {
  [[AVAudioSession sharedInstance] setActive:YES error:nil];
  [[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryPlayback error:nil];
}

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to stream manager's events.
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
  NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing the backup stream.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self playBackupStream];
}ViewController.m

Swift

@objc func contentDidFinishPlaying(_ notification: Notification) {
  guard let adsLoader = self.adsLoader else { return }
  adsLoader.contentComplete()
}

func startMediaSession() {
  try? AVAudioSession.sharedInstance().setActive(true, options: [])
  try? AVAudioSession.sharedInstance().setCategory(.playback)
}

// MARK: - IMAAdsLoaderDelegate

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  let streamManager = adsLoadedData.streamManager!
  streamManager.delegate = self
  streamManager.initialize(with: nil)
  self.streamManager = streamManager
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  print("Error loading ads: \(adErrorData.adError.message)")
  let streamUrl = URL(string: ViewController.backupStreamURLString)
  self.videoDisplay.loadStream(streamUrl!, withSubtitles: [])
  self.videoDisplay.play()
  playerViewController.player?.play()
}ViewController.swift

處理記錄和錯誤事件

串流管理員委派可處理多種事件，但就基本實作而言，最重要的用途是執行事件記錄、在廣告播放期間防止搜尋動作，以及處理錯誤。

Objective-C

#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"StreamManager event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_STREAM_STARTED: {
      [self startMediaSession];
      break;
    }
    case kIMAAdEvent_STARTED: {
      // Log extended data.
      NSString *extendedAdPodInfo = [[NSString alloc]
          initWithFormat:@"Showing ad %zd/%zd, bumper: %@, title: %@, description: %@, contentType:"
                         @"%@, pod index: %zd, time offset: %lf, max duration: %lf.",
                         event.ad.adPodInfo.adPosition, event.ad.adPodInfo.totalAds,
                         event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
                         event.ad.adDescription, event.ad.contentType, event.ad.adPodInfo.podIndex,
                         event.ad.adPodInfo.timeOffset, event.ad.adPodInfo.maxDuration];

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      self.adContainerView.hidden = NO;
      // Trigger an update to send focus to the ad display container.
      self.adBreakActive = YES;
      [self setNeedsFocusUpdate];
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      self.adContainerView.hidden = YES;
      // Trigger an update to send focus to the content player.
      self.adBreakActive = NO;
      [self setNeedsFocusUpdate];
      break;
    }
    case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
      // Resume playback after the user has closed the dialog.
      [self.videoDisplay play];
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing the backup stream.
  NSLog(@"StreamManager error: %@", error.message);
  [self playBackupStream];
}ViewController.m

Swift

// MARK: - IMAStreamManagerDelegate
func streamManager(_ streamManager: IMAStreamManager, didReceive event: IMAAdEvent) {
  print("StreamManager event \(event.typeString).")
  switch event.type {
  case IMAAdEventType.STREAM_STARTED:
    self.startMediaSession()
  case IMAAdEventType.STARTED:
    // Log extended data.
    if let ad = event.ad {
      let extendedAdPodInfo = String(
        format: "Showing ad %zd/%zd, bumper: %@, title: %@, "
          + "description: %@, contentType:%@, pod index: %zd, "
          + "time offset: %lf, max duration: %lf.",
        ad.adPodInfo.adPosition,
        ad.adPodInfo.totalAds,
        ad.adPodInfo.isBumper ? "YES" : "NO",
        ad.adTitle,
        ad.adDescription,
        ad.contentType,
        ad.adPodInfo.podIndex,
        ad.adPodInfo.timeOffset,
        ad.adPodInfo.maxDuration)

      print("\(extendedAdPodInfo)")
    }
    break
  case IMAAdEventType.AD_BREAK_STARTED:
    if let adContainerView = self.adContainerView {
      adContainerView.isHidden = false
    }
    // Trigger an update to send focus to the ad display container.
    adBreakActive = true
    setNeedsFocusUpdate()
    break
  case IMAAdEventType.AD_BREAK_ENDED:
    if let adContainerView = self.adContainerView {
      adContainerView.isHidden = true
    }
    // Trigger an update to send focus to the content player.
    adBreakActive = false
    setNeedsFocusUpdate()
    break
  case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
    // Resume playback after the user has closed the dialog.
    self.videoDisplay.play()
    break
  default:
    break
  }
}

func streamManager(_ streamManager: IMAStreamManager, didReceive error: IMAAdError) {
  print("StreamManager error: \(error.message ?? "Unknown Error")")
}ViewController.swift

大功告成！您現在可以使用 IMA DAI SDK 請求及顯示廣告。如要瞭解更多進階 SDK 功能，請參閱其他指南或 GitHub 上的範例。

設定 DAI 專用的 IMA SDK 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

全方位服務 DAI

IMA DAI 總覽

必要條件

建立新的 Xcode 專案

將 IMA DAI SDK 新增至 Xcode 專案

使用 Swift Package Manager 安裝 SDK

使用 CocoaPods 安裝 SDK

手動下載及安裝 SDK

顯示操作說明

匯入 IMA SDK

Objective-C

Swift

建立影片播放器並整合 IMA SDK

Objective-C

Swift

實作 IMAAdsLoader

Objective-C

Swift

提出串流要求

Objective-C

Swift

處理串流事件

Objective-C

Swift

處理記錄和錯誤事件

Objective-C

Swift

設定 DAI 專用的 IMA SDK