开始使用 IMA DAI SDK

借助 IMA SDK,您可以轻松将多媒体广告集成到您的网站和应用中。IMA SDK 可以从任何 与 VAST 兼容的广告服务器请求广告,并管理应用中的广告播放。借助 IMA DAI SDK,应用可以针对广告和内容视频(VOD 或直播内容)发出流式传输请求。然后,SDK 会返回一个合并的视频串流,这样您就不必在应用中管理广告视频和内容视频之间的切换。

选择您感兴趣的 DAI 解决方案

全方位 DAI

本指南介绍了如何将 IMA DAI SDK 集成到简单的视频播放器应用中。如果您想查看或跟随已完成的示例集成,请从 GitHub 下载 BasicExample

IMA DAI 概览

实现 IMA DAI 涉及四个主要 SDK 组件,如本指南所示:

  • IMAAdDisplayContainer - 位于视频播放元素之上并包含广告界面元素的容器对象。
  • 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 作为项目名称。

将 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

互动式媒体广告 SDK 支持 3.18.4 及更高版本的 Swift Package Manager。请按照以下步骤导入 Swift 软件包。

  1. 在 Xcode 中,依次前往 File(文件)> Add Packages(添加软件包),安装 IMA DAI SDK Swift 软件包。

  2. 在显示的提示中,搜索 IMA DAI SDK Swift 软件包的 GitHub 代码库:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
    
  3. 选择您要使用的 IMA DAI SDK Swift 软件包版本。对于新项目,我们建议使用 Up to Next Major Version

完成后,Xcode 会解析您的软件包依赖项,并在后台下载它们。如需详细了解如何添加软件包依赖项,请参阅 Apple 的文章

手动下载并安装 SDK

如果您不想使用 Swift Package Manager 或 CocoaPods,可以下载 IMA DAI SDK 并将其手动添加到您的项目中。

创建一个简单的视频播放器

使用封装在界面视图中的 AV 播放器,在主视图控制器中实现视频播放器。IMA SDK 使用界面视图来显示广告界面元素。

#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 导入到视图控制器中,并采用 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 类用于直播。对于 VOD 串流,请使用 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 上的示例