如要討論產品並提供意見回饋，請加入 Google 廣告與評估社群伺服器中的官方 Ad Manager Discord 頻道。

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

設定 IMA SDK

選取平台： HTML5 Android iOS tvOS

使用 IMA SDK，即可輕鬆將多媒體廣告整合至網站和應用程式。IMA SDK 可向任何符合 VAST 規定的廣告伺服器請求廣告，並在應用程式中管理廣告播放。使用 IMA 用戶端 SDK 時，您可以控管內容影片的播放，SDK 則負責處理廣告播放。廣告會在應用程式內容影片播放器上方的獨立影片播放器中播放。

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

IMA 用戶端總覽

導入 IMA 用戶端時，會用到四個主要的 SDK 元件，本指南將說明這些元件：

IMAAdDisplayContainer：容器物件，用於指定 IMA 要在何處算繪廣告 UI 元素及評估可視度，包括 Active View 和 Open Measurement。
IMAAdsLoader：要求廣告並處理廣告請求回應事件的物件。您應該只例項化一個廣告載入器，這個載入器可在應用程式的整個生命週期中重複使用。
IMAAdsRequest：定義廣告請求的物件。廣告請求會指定 VAST 廣告代碼的網址，以及廣告尺寸等其他參數。
IMAAdsManager：這個物件包含廣告請求的回應、控管廣告播放，並監聽 SDK 觸發的廣告事件。

必要條件

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

Xcode 13 以上版本
CocoaPods (建議使用)、Swift Package Manager，或下載的 tvOS 適用的 IMA SDK 副本

1. 建立新的 Xcode 專案

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

2. 將 IMA SDK 新增至 Xcode 專案

使用 CocoaPods 安裝 SDK (建議)

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

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

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

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

使用 Swift Package Manager 安裝 SDK

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

在 Xcode 中，依序前往「File」>「Add Packages...」，安裝 IMA SDK Swift Package。

在顯示的提示中，搜尋 IMA SDK Swift 套件 GitHub 存放區：

https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos

選取要使用的 IMA SDK Swift 套件版本。對於新專案，建議使用「Up to Next Major Version」。

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

手動下載及安裝 SDK

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

顯示/隱藏操作說明

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

3. 建立簡單的影片播放器

首先，請導入基本影片播放器。一開始，這個播放器不會使用 IMA SDK，且尚未包含任何觸發播放的方法。

ViewController.m

Objective-C

#import "ViewController.h"

#import <AVKit/AVKit.h>

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";

@interface ViewController ()
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = UIColor.blackColor;
  [self setupContentPlayer];
}

- (void)setupContentPlayer {
  // Create a content video player.
  NSURL *contentURL = [NSURL URLWithString:kContentURLString];
  AVPlayer *player = [AVPlayer playerWithURL:contentURL];
  self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
  self.contentPlayerViewController.player = player;
  self.contentPlayerViewController.view.frame = self.view.bounds;

  // Attach content video player to view hierarchy.
  [self showContentPlayer];
}

// Add the content video player as a child view controller.
- (void)showContentPlayer {
  [self addChildViewController:self.contentPlayerViewController];
  self.contentPlayerViewController.view.frame = self.view.bounds;
  [self.view insertSubview:self.contentPlayerViewController.view atIndex:0];
  [self.contentPlayerViewController didMoveToParentViewController:self];
}

// Remove and detach the content video player.
- (void)hideContentPlayer {
  // The whole controller needs to be detached so that it doesn't capture events from the remote.
  [self.contentPlayerViewController willMoveToParentViewController:nil];
  [self.contentPlayerViewController.view removeFromSuperview];
  [self.contentPlayerViewController removeFromParentViewController];
}

@end

Swift

import AVFoundation
import UIKit

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

  var playerViewController: AVPlayerViewController!

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

  func setUpContentPlayer() {
    // Load AVPlayer with path to your content.
    let contentURL! = URL(string: ViewController.ContentURLString)
    let player = AVPlayer(url: contentURL)
    playerViewController = AVPlayerViewController()
    playerViewController.player = player

    showContentPlayer()
  }

  func showContentPlayer() {
    self.addChild(playerViewController)
    playerViewController.view.frame = self.view.bounds
    self.view.insertSubview(playerViewController.view, at: 0)
    playerViewController.didMove(toParent:self)
  }

  func hideContentPlayer() {
    // The whole controller needs to be detached so that it doesn't capture  events from the remote.
    playerViewController.willMove(toParent:nil)
    playerViewController.view.removeFromSuperview()
    playerViewController.removeFromParent()
  }
}

4. 匯入 IMA SDK

接著，在現有匯入項目下方，使用匯入陳述式新增 IMA 架構。

ViewController.m

Objective-C

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

5. 實作內容播放頭追蹤器和串流結束觀察器

如要播放影片中廣告，IMA SDK 必須追蹤影片內容的目前位置。如要這麼做，請建立實作 IMAContentPlayhead 的類別。如本範例所示，如果您使用 AVPlayer，SDK 會提供 IMAAVPlayerContentPlayhead 類別，為您執行這項操作。如果您不使用 AVPlayer，就必須在自己的類別中導入 IMAContentPlayhead。

您也必須告知 SDK 內容播放完畢的時間，以便顯示片尾廣告。方法是在 IMAAdsLoader 上呼叫 contentComplete，並使用 AVPlayerItemDidPlayToEndTimeNotification。

ViewController.m

Objective-C

...

@interface ViewController ()
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

...

- (void)setupContentPlayer {
  // Create a content video player.
  NSURL *contentURL = [NSURL URLWithString:kContentURLString];
  AVPlayer *player = [AVPlayer playerWithURL:contentURL];
  self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
  self.contentPlayerViewController.player = player;
  self.contentPlayerViewController.view.frame = self.view.bounds;
  self.contentPlayhead =
      [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayerViewController.player];

  // Track end of content.
  AVPlayerItem *contentPlayerItem = self.contentPlayerViewController.player.currentItem;
  [NSNotificationCenter.defaultCenter addObserver:self
                                         selector:@selector(contentDidFinishPlaying:)
                                             name:AVPlayerItemDidPlayToEndTimeNotification
                                           object:contentPlayerItem];

  // Attach content video player to view hierarchy.
  [self showContentPlayer];
}

...

- (void)contentDidFinishPlaying:(NSNotification *)notification {}

- (void)dealloc {
  [NSNotificationCenter.defaultCenter removeObserver:self];
}

@end

Swift

...

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

  deinit {
    NotificationCenter.default.removeObserver(self)
  }

...

  func setUpContentPlayer() {
    // Load AVPlayer with path to your content.
    let contentURL! = URL(string: ViewController.ContentURLString)
    let player = AVPlayer(url: contentURL)
    playerViewController = AVPlayerViewController()
    playerViewController.player = player

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

    showContentPlayer()
  }

...

  @objc func contentDidFinishPlaying(_ notification: Notification) {
    adsLoader.contentComplete()
  }
}

6. 初始化廣告載入器並提出廣告請求

如要要求一組廣告，您需要建立 IMAAdsLoader 例項。這個載入器可用於處理與指定廣告代碼網址相關聯的 IMAAdsRequest 物件。

最佳做法是，在整個應用程式生命週期中，只維護一個 IMAAdsLoader 例項。如要提出額外的廣告請求，請建立新的 IMAAdsRequest 物件，但重複使用相同的 IMAAdsLoader。詳情請參閱 IMA SDK 常見問題。

ViewController.m

Objective-C

...

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
NSString *const kAdTagURLString = @"https://pubads.g.doubleclick.net/gampad/ads?"
    @"iu=/21775744923/external/vmap_ad_samples&sz=640x480&"
    @"cust_params=sample_ar%3Dpremidpostlongpod&"
    @"ciu_szs=300x250&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&"
    @"env=vp&cmsid=496&vid=short_onecue&correlator=";

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = UIColor.blackColor;
  [self setupContentPlayer];
  [self setupAdsLoader];
}

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

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

- (void)requestAds {
  // Pass the main view as the container for ad display.
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view];
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
                                                adDisplayContainer:adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}

...

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Notify the SDK that the postrolls should be played.
  [self.adsLoader contentComplete];
}

...

@end

Swift

...

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"
  static let AdTagURLString = "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&correlator="

  var adsLoader: IMAAdsLoader!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

...

  override func viewDidLoad() {
    super.viewDidLoad()
    self.view.backgroundColor = UIColor.black;
    setUpContentPlayer()
    setUpAdsLoader()
  }

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

...

  func setUpAdsLoader() {
    adsLoader = IMAAdsLoader(settings: nil)
  }

  func requestAds() {
    // Create ad display container for ad rendering.
    let adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view)
    // Create an ad request with your ad tag, display container, and optional user context.
    let request = IMAAdsRequest(
        adTagUrl: ViewController.AdTagURLString,
        adDisplayContainer: adDisplayContainer,
        contentPlayhead: contentPlayhead,
        userContext: nil)

    adsLoader.requestAds(with: request)
  }

  @objc func contentDidFinishPlaying(_ notification: Notification) {
    adsLoader.contentComplete()
  }
}

7. 設定廣告載入器委派

載入事件成功後，IMAAdsLoader 會呼叫指派的委派項目的 adsLoadedWithData 方法，並傳遞 IMAAdsManager 的執行個體。接著，您可以初始化廣告管理工具，載入廣告代碼網址回應中定義的個別廣告。

此外，請務必處理載入程序中可能發生的任何錯誤。如果廣告未載入，請確保媒體播放作業會繼續進行 (不含廣告)，以免干擾使用者體驗。

ViewController.m

Objective-C

...

@interface ViewController () <IMAAdsLoaderDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

...

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

...

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to the ads manager loaded for this request.
  self.adsManager = adsLoadedData.adsManager;
  [self.adsManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayerViewController.player play];
}

@end

Swift

...

class ViewController: UIViewController, IMAAdsLoaderDelegate {

...

  var adsLoader: IMAAdsLoader!
  var adsManager: IMAAdsManager!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

...

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

...

  // MARK: - IMAAdsLoaderDelegate

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

  func adsLoader(_ loader: IMAAdsLoader!, failedWith adErrorData: IMAAdLoadingErrorData!) {
    print("Error loading ads: " + adErrorData.adError.message)
    showContentPlayer()
    playerViewController.player?.play()
  }
}

8. 設定廣告管理員代表

最後，為了管理事件和狀態變更，廣告管理員需要自己的委派項目。IMAAdManagerDelegate 具有處理廣告事件和錯誤的方法，以及觸發影片內容播放和暫停的方法。

開始播放

didReceiveAdEvent 方法可用於處理許多事件，但以這個基本範例來說，只要監聽 LOADED 事件，即可告知廣告管理工具開始播放內容和廣告。

ViewController.m

Objective-C

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>

...

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to the ads manager loaded for this request.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  [self.adsManager initializeWithAdsRenderingSettings:nil];
}

...

#pragma mark - IMAAdsManagerDelegate

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // Play each ad once it has loaded.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}

...

Swift

...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {

...

  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    // Grab the instance of the IMAAdsManager and set yourself as the delegate.
    adsManager = adsLoadedData.adsManager
    adsManager.delegate = self
    adsManager.initialize(with: nil)
  }

...

  // MARK: - IMAAdsManagerDelegate

  func adsManager(_ adsManager: IMAAdsManager!, didReceive event: IMAAdEvent!) {
    // Play each ad once it has been loaded
    if event.type == IMAAdEventType.LOADED {
      adsManager.start()
    }
  }

...

處理錯誤

同時也新增廣告錯誤的處理常式。如果發生錯誤 (如上一個步驟所述)，請繼續播放內容。

ViewController.m

Objective-C

...

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing content.
  NSLog(@"AdsManager error: %@", error.message);
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}
@end

Swift

...

  func adsManager(_ adsManager: IMAAdsManager!, didReceive error: IMAAdError!) {
    // Fall back to playing content
    print("AdsManager error: " + error.message)
    showContentPlayer()
    playerViewController.player?.play()
  }

觸發播放和暫停事件

您需要導入的最後兩個委派方法，是用來在 IMA SDK 要求時，觸發基礎影片內容的播放和暫停事件。在廣告顯示時觸發暫停和播放功能，可避免使用者錯過部分影片內容。

ViewController.m

Objective-C

...

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // Pause the content for the SDK to play ads.
  [self.contentPlayerViewController.player pause];
  [self hideContentPlayer];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // Resume the content since the SDK is done playing ads (at least for now).
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}

@end

Swift

...

  func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager!) {
    // Pause the content for the SDK to play ads.
    playerViewController.player?.pause()
    hideContentPlayer()
  }

  func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager!) {
    // Resume the content since the SDK is done playing ads (at least for now).
    showContentPlayer()
    playerViewController.player?.play()
  }
}

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

後續步驟

如要在 tvOS 平台上盡量提高廣告收益，請要求應用程式追蹤透明度和追蹤權限，以便使用廣告識別碼。

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

IMA 用戶端總覽

必要條件

1. 建立新的 Xcode 專案

2. 將 IMA SDK 新增至 Xcode 專案

使用 CocoaPods 安裝 SDK (建議)

使用 Swift Package Manager 安裝 SDK

手動下載及安裝 SDK

顯示/隱藏操作說明

3. 建立簡單的影片播放器

Objective-C

Swift

4. 匯入 IMA SDK

Objective-C

Swift

5. 實作內容播放頭追蹤器和串流結束觀察器

Objective-C

Swift

6. 初始化廣告載入器並提出廣告請求

Objective-C

Swift

7. 設定廣告載入器委派

Objective-C

Swift

8. 設定廣告管理員代表

開始播放

Objective-C

Swift

處理錯誤

Objective-C

Swift

觸發播放和暫停事件

Objective-C

Swift

後續步驟

設定 IMA SDK