開始使用 IMA DAI SDK

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

選取感興趣的動態廣告解決方案

全方位服務 DAI

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

IMA DAI 總覽

實作 IMA DAI 時,需要使用四個主要 SDK 元件,如本指南所示:

  • IMAAdDisplayContainer – 容器物件,位於影片播放元素上方,並容納廣告 UI 元素。
  • IMAAdsLoader:要求串流的物件,並處理由串流要求回應物件觸發的事件。您應該只將一個廣告載入器例項化,這樣一來,您就能在應用程式生命週期中重複使用。
  • IMAStreamRequest IMAVODStreamRequest IMALiveStreamRequest。定義串流要求的物件。串流要求可以是隨選影片或直播串流。要求會指定內容 ID,以及 API 金鑰或驗證權杖和其他參數。
  • IMAStreamManager:處理動態廣告插播串流和與 DAI 後端互動的物件。串流管理員也會處理追蹤 ping,並將串流和廣告事件轉送給發布商。

必要條件

開始之前,請先準備下列項目:

您也需要用來從 IMA SDK 要求串流的參數。如需要求參數示例,請參閱「範例串流」。

直播參數
素材資源金鑰 在 Google Ad Manager 中識別直播活動的素材資源金鑰。
示例:c-rArva4ShKVIAkNfy6HUQ
VOD 串流參數
內容來源 ID Google Ad Manager 中的內容來源 ID。
示例:2548831
影片 ID Google Ad Manager 的影片 ID。
示例:tears-of-steel

建立新的 Xcode 專案

在 Xcode 中,使用 Objective-C 建立新的 iOS 專案。請使用「BasicExample」BasicExample做為專案名稱。

將 IMA DAI SDK 新增至 Xcode 專案

請使用下列三種方法之一安裝 IMA DAI SDK。

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

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

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

    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '14'
    
    target 'BasicExample' do
      pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0'
    end
    
  2. 在包含 Podfile 的目錄中執行以下指令:

    pod install --repo-update`
  3. 如要確認安裝是否成功,請開啟 BasicExample.xcworkspace 檔案,並確認檔案包含兩個專案:BasicExamplePods (由 CocoaPods 安裝的依附元件)。

使用 Swift Package Manager 安裝 SDK

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

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

  2. 在出現的提示中,搜尋 IMA DAI SDK Swift Package GitHub 存放區:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
    
  3. 選取要使用的 IMA DAI SDK Swift 套件版本。對於新專案,建議您使用升級至下一個主要版本

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

手動下載及安裝 SDK

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

建立簡單的影片播放器

在主要 View Controller 中實作影片播放器,使用包裝在 UI 檢視畫面中的 AV 播放器。IMA SDK 會使用 UI 檢視畫面顯示廣告 UI 元素。

#import "ViewController.h"

#import <AVKit/AVKit.h>

/// Content URL.
static NSString *const kBackupContentUrl =
    @"http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8";

@interface ViewController ()
/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

@property(nonatomic, weak) IBOutlet UIView *videoView;
/// Video player.
@property(nonatomic, strong) AVPlayer *videoPlayer;
@end

@implementation ViewController

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

  // Load AVPlayer with the path to your content.
  NSURL *contentURL = [NSURL URLWithString:kBackupContentUrl];
  self.videoPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.videoPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self.videoPlayer play];
  self.playButton.hidden = YES;
}

@end

初始化廣告載入器

將 IMA SDK 匯入至 View Controller,並採用 IMAAdsLoaderDelegateIMAStreamManagerDelegate 協定,以便處理廣告載入器和串流管理器事件。

新增下列私人屬性,以儲存重要 IMA SDK 元件:

在檢視區載入後,初始化廣告載入器、廣告顯示容器和影片顯示功能。

@import GoogleInteractiveMediaAds;

// ...

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
/// The entry point for the IMA DAI SDK to make DAI stream requests.
@property(nonatomic, strong) IMAAdsLoader *adsLoader;
/// The container where the SDK renders each ad's user interface elements and companion slots.
@property(nonatomic, strong) IMAAdDisplayContainer *adDisplayContainer;
/// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
/// metadata.
@property(nonatomic, strong) IMAAVPlayerVideoDisplay *imaVideoDisplay;
/// References the stream manager from the IMA DAI SDK after successful stream loading.
@property(nonatomic, strong) IMAStreamManager *streamManager;

// ...

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;

  // Create an ad display container for rendering each ad's user interface elements and companion
  // slots.
  self.adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];

  // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
  self.imaVideoDisplay = [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.videoPlayer];
}

提出串流要求

當使用者按下播放按鈕時,請提出新的串流要求。使用 IMALiveStreamRequest 類別進行直播。如為隨選影片串流,請使用 IMAVODStreamRequest 類別。

串流要求需要串流參數,以及廣告顯示容器和影片顯示的參照。

- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestStream];
  self.playButton.hidden = YES;
}

- (void)requestStream {
  // Create a stream request. Use one of "Live stream request" or "VOD request", depending on your
  // type of stream.
  IMAStreamRequest *request;
  // Switch this variable to NO to make a VOD request.
  BOOL useLiveStream = YES;
  if (useLiveStream) {
    // Live stream request. Replace the asset key with your value.
    request = [[IMALiveStreamRequest alloc] initWithAssetKey:@"c-rArva4ShKVIAkNfy6HUQ"
                                          adDisplayContainer:self.adDisplayContainer
                                                videoDisplay:self.imaVideoDisplay
                                                 userContext:nil];
  } else {
    // VOD request. Replace the content source ID and video ID with your values.
    request = [[IMAVODStreamRequest alloc] initWithContentSourceID:@"2548831"
                                                           videoID:@"tears-of-steel"
                                                adDisplayContainer:self.adDisplayContainer
                                                      videoDisplay:self.imaVideoDisplay
                                                       userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}

監聽串流載入事件

當串流要求初始化成功或失敗時,IMAAdsLoader 類別會呼叫 IMAAdsLoaderDelegate 方法。

adsLoadedWithData 委派方法中,設定 IMAStreamManagerDelegate 並初始化串流管理員。在初始化時,串流管理員會開始播放。

failedWithErrorData 委派方法中記錄錯誤。視需要播放備用串流。請參閱 DAI 最佳做法

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  NSLog(@"Stream created with: %@.", adsLoadedData.streamManager.streamId);
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Log the error and play the content.
  NSLog(@"AdsLoader error, code:%ld, message: %@", adErrorData.adError.code,
        adErrorData.adError.message);
  [self.videoPlayer play];
}

監聽廣告事件

IMAStreamManager 會呼叫 IMAStreamManagerDelegate 方法,將串流事件和錯誤傳遞至應用程式。

在這個範例中,將主要廣告事件記錄到控制台:

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

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      NSLog(@"Ad break started");
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      NSLog(@"Ad break ended");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_STARTED: {
      NSLog(@"Ad period started");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_ENDED: {
      NSLog(@"Ad period ended");
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  NSLog(@"StreamManager error with type: %ld\ncode: %ld\nmessage: %@", error.type, error.code,
        error.message);
  [self.videoPlayer play];
}

執行應用程式,如果成功,您就可以使用 IMA SDK 要求及播放 Google DAI 串流。如要進一步瞭解更進階的 SDK 功能,請參閱左側邊欄列出的其他指南,或參閱 GitHub 上的範例