开始使用 IMA DAI SDK

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

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

Pod Serving DAI

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

IMA DAI 概览

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

  • IMAAdDisplayContainer - 位于视频播放元素之上并包含广告界面元素的容器对象。
  • IMAAdsLoader - 用于请求数据流并处理由数据流请求响应对象触发的事件的对象。您应仅实例化一个广告加载器,该加载器可在应用的整个生命周期内重复使用。
  • IMAStreamRequest - IMAPodVODStreamRequest IMAPodStreamRequest
  • IMAStreamManager - 用于处理动态广告插播数据流和与 DAI 后端的互动的对象。直播管理器还会处理跟踪 ping,并将直播和广告事件转发给发布商。

此外,如需播放 pod 广告投放串流,您必须实现自定义 VTP 处理程序。此自定义 VTP 处理脚本会将直播 ID 以及 VTP 需要的任何其他信息发送给 VTP,以便 VTP 返回包含内容和接缝广告的直播清单。VTP 将提供有关如何实现自定义 VTP 处理程序的说明。

前提条件

在开始之前,您需要做好以下准备:

您还需要用于向 IMA SDK 请求直播的参数。

直播参数
广告资源网代码 您的 Ad Manager 360 账号的广告资源网代码。
示例:51636543
自定义素材资源键 用于在 Campaign Manager 360 中标识广告连播投放事件的自定义素材资源键。此文件可以由清单操纵器或第三方广告连播投放合作伙伴创建。
示例:google-sample
VOD 视频流参数
广告资源网代码 您的 Ad Manager 360 账号的广告资源网代码。
示例:51636543

创建新的 Xcode 项目

在 Xcode 中,使用 Objective-C 创建一个名为“PodServingExample”的新 iOS 项目。

将 IMA DAI SDK 添加到 Xcode 项目

您可以使用以下三种方法之一安装 IMA DAI SDK。

使用 CocoaPods 安装 SDK(首选)

CocoaPods 是 Xcode 项目的依赖项管理器,是安装 IMA DAI SDK 的推荐方法。如需详细了解如何安装或使用 CocoaPods,请参阅 CocoaPods 文档。安装 CocoaPods 后,请按照以下说明安装 IMA DAI SDK:

  1. PodServingExample.xcodeproj 文件所在的目录中,创建一个名为 Podfile 的文本文件,并添加以下配置:

    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '14'
    
    target 'PodServingExample' do
      pod 'GoogleAds-IMA-iOS-SDK'
    end
    

  2. 在包含 Podfile 的目录中,运行以下命令:

    pod install --repo-update

使用 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];
}

发出流式请求

当用户按下播放按钮时,发出新的串流请求。 将 IMAPodStreamRequest 类用于直播。对于 VOD 串流,请使用 IMAPodVODStreamRequest 类。

流式传输请求需要您的流式传输参数,以及对广告展示容器和视频显示的引用。

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

- (void)requestStream {
  // Create a stream request.
  IMAStreamRequest *request;
  if (kStreamType == StreamTypeLive) {
    // Live stream request. Replace the network code and custom asset key with your values.
    request = [[IMAPodStreamRequest alloc] initWithNetworkCode:kNetworkCode
                                                customAssetKey:kCustomAssetKey
                                            adDisplayContainer:adDisplayContainer
                                                  videoDisplay:self.videoDisplay
                                         pictureInPictureProxy:nil
                                                   userContext:nil];
  } else {
    // VOD request. Replace the network code with your value.
    request = [[IMAPodVODStreamRequest alloc] initWithNetworkCode:@kNetworkCode
                                               adDisplayContainer:adDisplayContainer
                                                     videoDisplay:self.videoDisplay
                                            pictureInPictureProxy:nil
                                                      userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}

监听数据流加载事件

在流式请求成功初始化或失败时,IMAAdsLoader 类会调用 IMAAdsLoaderDelegate 方法。

adsLoadedWithData 委托方法中,设置 IMAStreamManagerDelegate。 将直播 ID 传递给自定义 VTP 处理程序,然后检索直播清单网址。对于直播,请将清单网址加载到视频显示屏中,然后开始播放。对于 VOD 串流,请将清单网址传递给串流管理器的 loadThirdPartyStream 方法。此方法会从 Ad Manager 360 请求广告事件数据,然后加载清单网址并开始播放。

failedWithErrorData 委托方法中,记录错误。(可选)播放备用串流。请参阅 DAI 最佳实践

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

  // Build the Pod serving Stream URL.
  NSString *streamID = adsLoadedData.streamManager.streamId;
  // Your custom VTP handler takes the stream ID and returns the stream manifest URL.
  NSString *urlString = gCustomVTPHandler(streamID);
  NSURL *streamUrl = [NSURL URLWithString:urlString];
  if (kStreamType == StreamTypeLive) {
    // Load live streams directly into the AVPlayer.
    [self.videoDisplay loadStream:streamUrl withSubtitles:@[]];
    [self.videoDisplay play];
  } else {
    // Load VOD streams using the `loadThirdPartyStream` method in IMA SDK's stream manager.
    // The stream manager loads the stream, requests metadata, and starts playback.
    [self.streamManager loadThirdPartyStream:streamUrl streamSubtitles:@[]];
  }
}

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

实现自定义 VTP 处理脚本

自定义 VTP 处理程序会将观看者的直播 ID 以及 VTP 需要的任何其他信息发送给您的视频技术合作伙伴 (VTP),以便 VTP 返回包含内容和接缝广告的直播清单。VTP 会提供有关如何实现自定义 VTP 处理程序的具体说明。

例如,VTP 可能包含包含宏 [[STREAMID]] 的清单模板网址。在此示例中,处理脚本会插入直播 ID 来替换宏,并返回生成的清单网址。

/// Custom VTP Handler.
///
/// Returns the stream manifest URL from the video technical partner or manifest manipulator.
static NSString *(^gCustomVTPHandler)(NSString *) = ^(NSString *streamID) {
  // Insert synchronous code here to retrieve a stream manifest URL from your video tech partner
  // or manifest manipulation server.
  // This example uses a hardcoded URL template, containing a placeholder for the stream
  // ID and replaces the placeholder with the stream ID.
  NSString *manifestUrl = @"YOUR_MANIFEST_URL_TEMPLATE";
  return [manifestUrl stringByReplacingOccurrencesOfString:@"[[STREAMID]]"
                                                withString:streamID];
};

监听广告事件

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 DAI 素材资源

如需停止流式传输播放、停止所有广告跟踪并释放所有已加载的流式传输资产,请调用 IMAStreamManager.destroy()

运行您的应用,如果成功,您就可以使用 IMA SDK 请求和播放 Google DAI 广告串流。如需了解更高级的 SDK 功能,请参阅左侧边栏中列出的其他指南或 GitHub 上的示例