IMA SDK 可讓您輕鬆將多媒體廣告整合至您的網站和應用程式。IMA SDK 可以從任何 符合 VAST 規定的廣告伺服器請求廣告，並管理在應用程式中播放的廣告。使用 IMA 用戶端 SDK 時，您可以保有內容影片播放的控制權，而 SDK 會處理廣告播放作業。廣告會在應用程式內容影片播放器上方的個別影片播放器中播放。
本指南說明如何在簡單的影片播放器應用程式中整合 IMA SDK。如果您要查看或按照完整的整合範例操作，請從 GitHub 下載 BasicExample。
IMA 用戶端總覽
導入 IMA 用戶端涉及四項主要 SDK 元件，如本指南所示：
IMAAdDisplayContainer： 顯示廣告的容器物件。IMAAdsLoader： 這個物件會請求廣告，以及處理廣告請求回應中的事件。您只應模擬一個廣告載入器，且在應用程式生命週期內皆可重複使用。IMAAdsRequest： 定義廣告請求的物件。廣告請求會指定 VAST 廣告代碼的網址以及其他參數，例如廣告尺寸。IMAAdsManager：這個物件包含對廣告請求的回應、控制廣告播放，以及監聽 SDK 觸發的廣告事件。
先備知識
開始之前，請先備妥以下項目：
- Xcode 13 以上版本
- CocoaPods (建議使用)、Swift 套件管理工具，或下載的 tvOS 專用 IMA SDK 副本
1. 建立新的 Xcode 專案
在 Xcode 中，使用 Objective-C 或 Swift 建立新的 tvOS 專案。使用 BasicExample 做為專案名稱。
2. 在 Xcode 專案中加入 IMA SDK
使用 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.13.0' end從包含 Podfile 的目錄，執行
pod install --repo-update開啟 BasicExample.xcworkspace 檔案，並確認該檔案包含兩個專案：BasicExample 和 Pods (由 CocoaPods 安裝的依附元件)，驗證安裝成功。
使用 Swift Package Manager 安裝 SDK
自 4.8.2 版起，互動式媒體廣告 SDK 支援 Swift 套件管理工具。請按照下列步驟匯入 Swift 套件。
在 Xcode 中依序前往「File」>「Add Packages...」，安裝 IMA SDK Swift 套件。
在隨即顯示的提示中，搜尋 IMA SDK Swift 套件 GitHub 存放區：
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos選取您要使用的 IMA SDK Swift 套件版本。如要建立新專案，建議您使用直到下一個主要版本。
完成後，Xcode 會解析套件依附元件，並在背景中下載這些依附元件。如要進一步瞭解如何新增套件依附元件，請參閱 Apple 的文章。
手動下載並安裝 SDK
如果不想使用 CocoaPods，您可以下載 IMA SDK，然後手動加到專案中。
顯示/隱藏操作說明
- 從 tvOS IMA SDK 下載頁面，下載並擷取最新版的 tvOS IMA SDK。
- 開啟「BasicExample.xcodeproj」BasicExample.xcodeproj。
- 在左側窗格中，按一下專案名稱。
- 按一下中間窗格中的「Build Phases」。
- 展開「Link Binary With Libraries」部分，
- 在資料庫清單底部，按一下加號圖示 [+]。
- 按一下「新增其他」。
- 在您擷取下載 SDK 的目錄中選取「GoogleInteractiveMediaAds.framework」GoogleInteractiveMediaAds.framework，然後按一下「Open」GoogleInteractiveMediaAds.framework。
- 在資料庫清單底部，再次按一下加號圖示 [+]。
- 在「Status」(狀態) 欄中，確認
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 知道內容播放完畢的時間，才能顯示片尾廣告。方法是使用 AVPlayerItemDidPlayToEndTimeNotification 在 IMAAdsLoader 上呼叫 contentComplete。
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&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
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&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-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 平台上盡量提高廣告收益，請要求應用程式資訊公開和追蹤權限以使用廣告識別碼。