開始使用

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

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

注意：如要瞭解如何整合其他平台，或使用 IMA DAI SDK，請參閱「 互動式媒體廣告 SDK」。

IMA 用戶端簡介

實作 IMA 用戶端時，需要四個主要 SDK 元件，本指南會示範這四個元件：

• IMAAdDisplayContainer：廣告算繪的容器物件。
• IMAAdsLoader：要求廣告的物件，並處理廣告請求回應中的事件。您應該只例項化一個廣告載入器，這樣在整個應用程式生命週期中，您就能重複使用廣告載入器。
• IMAAdsRequest：定義廣告請求的物件。廣告要求會指定 VAST 廣告代碼的網址，以及廣告尺寸等其他參數。
• IMAAdsManager：包含廣告請求回應、控制廣告播放，以及監聽 SDK 觸發的廣告事件的物件。

必要條件

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

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

1. 建立新的 Xcode 專案

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

2. 將 IMA SDK 新增至 Xcode 專案

使用 CocoaPods 安裝 SDK (建議做法)

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

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

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

2. 在包含 Podfile 的目錄中執行 pod install --repo-update

3. 開啟 BasicExample.xcworkspace 檔案，確認檔案包含兩個專案：BasicExample 和 Pods (由 CocoaPods 安裝的依附元件)，即可驗證安裝是否成功。

使用 Swift Package Manager 安裝 SDK

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

注意： 如果您要從以 CocoaPods 為基礎的專案遷移，請執行 pod deintegrate，從 Xcode 專案中移除 CocoaPods。之後，您可以放心刪除 CocoaPods 產生的 .xcworkspace 檔案。如果您是首次將互動式媒體廣告 SDK 新增至專案，可以略過這個步驟。

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

2. 在出現的提示中，搜尋 IMA SDK Swift Package GitHub 存放區：

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

3. 選取要使用的 IMA SDK Swift 套件版本。對於新專案，建議您使用升級至下一個主要版本。

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

手動下載及安裝 SDK

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

顯示/隱藏操作說明

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

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

首先，實作基本影片播放器。這個播放器一開始不會使用 IMA SDK，也不包含任何觸發播放的做法。

ViewController.m

Objective-CSwift

#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
      

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-CSwift

#import "ViewController.h"

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

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 知道內容播放完畢的時間，以便顯示片中廣告。方法是使用 AVPlayerItemDidPlayToEndTimeNotification 在 IMAAdsLoader 上呼叫 contentComplete。

ViewController.m

Objective-CSwift

...

@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
      

...

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-CSwift

...

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&impl=s&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
      

...

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&impl=s&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-CSwift

...

@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
      

...

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-CSwift

@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];
  }
}

...
      

...

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-CSwift

...

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

...

  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-CSwift

...

- (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
      

...

  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 平台的廣告收益，請申請應用程式透明度和追蹤權限，以便使用廣告識別碼。