プロダクトに関するご意見やフィードバックをお寄せいただくには、Google 広告および測定のコミュニティサーバーの公式アドマネージャー Discord チャンネルにご参加ください。

DAI 用 IMA SDK を設定する

プラットフォームを選択: HTML5 Android iOS tvOS Cast Roku

IMA SDK を使用すると、マルチメディア広告をウェブサイトやアプリに簡単に統合できます。IMA SDK は、 VAST 準拠のあらゆる広告サーバーから広告をリクエストし、アプリでの広告再生を管理できます。IMA DAI SDK を使用すると、アプリは広告とコンテンツ動画（VOD またはライブコンテンツ）のストリームリクエストを行います。SDK は結合された動画ストリームを返すため、アプリ内で広告とコンテンツの動画を切り替える処理を管理する必要はありません。

関心のある DAI ソリューションを選択する

フルサービス DAI

このガイドでは、IMA DAI SDK を動画プレーヤーアプリに統合する方法について説明します。完成したサンプル統合を表示または実行する場合は、GitHub から BasicExample をダウンロードしてください。

IMA DAI の概要

このガイドで説明するように、IMA DAI の実装には 3 つの主要な SDK コンポーネントが含まれます。

IMAAdDisplayContainer: 動画再生要素の上に配置され、広告の UI 要素を格納するコンテナオブジェクト。
IMAAdsLoader: ストリームをリクエストし、ストリームリクエストレスポンスオブジェクトによってトリガーされたイベントを処理するオブジェクト。広告ローダは 1 つだけインスタンス化し、アプリケーションのライフサイクル全体で再利用する必要があります。
IMAStreamRequest - IMAVODStreamRequest または IMALiveStreamRequest: ストリームリクエストを定義するオブジェクト。ストリームリクエストは、ビデオオンデマンドまたはライブストリームのいずれかになります。ライブストリームのリクエストではアセットキーが指定され、VOD のリクエストでは CMS ID と動画 ID が指定されます。どちらのリクエストタイプにも、指定されたストリームへのアクセスに必要な API キーと、Google Ad Manager の設定で指定された広告 ID を IMA SDK が処理するための Google Ad Manager ネットワークコードを任意で含めることができます。
IMAStreamManager: ダイナミック広告挿入ストリームと DAI バックエンドとのやり取りを処理するオブジェクト。ストリームマネージャーは、トラッキング ping を処理し、ストリームイベントと広告イベントをパブリッシャーに転送します。

前提条件

始める前に、次のものが必要になります。

Xcode 13 以降
IMA SDK のインストール方法:
- Swift Package Manager（推奨）
- CocoaPods
- tvOS 向け IMA SDK のダウンロードコピー

新しい Xcode プロジェクトを作成する

Xcode で、Objective-C を使用して新しい tvOS プロジェクトを作成します。プロジェクト名として BasicExample を使用します。

Xcode プロジェクトに IMA DAI SDK を追加する

IMA SDK をインストールするには、ご希望の方法を選択してください。

推奨: Swift Package Manager を使用して SDK をインストールする

Interactive Media Ads SDK はバージョン 4.8.2 から Swift Package Manager に対応しています。Swift パッケージをインポートする手順は次のとおりです。

Xcode で、[File] > [Add Packages] の順に移動して、GoogleInteractiveMediaAds Swift パッケージをインストールします。
表示されたプロンプトで、GoogleInteractiveMediaAds の Swift パッケージの GitHub リポジトリ（下記）を検索します。
```
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
```
使用する GoogleInteractiveMediaAds の Swift パッケージのバージョンを選択します。新しいプロジェクトの場合は、[Up to Next Major Version] を選択することをおすすめします。

完了すると、Xcode はパッケージの依存関係を解決し、バックグラウンドでダウンロードします。パッケージの依存関係の追加について詳しくは、Apple の記事を参照してください。

CocoaPods を使用して SDK をインストールする

CocoaPods は Xcode プロジェクトの依存関係マネージャーであり、IMA DAI SDK をインストールする推奨の方法です。CocoaPods のインストールと使用の詳細については、CocoaPods のドキュメントをご覧ください。CocoaPods をインストールしたら、次の手順で IMA DAI SDK をインストールします。

BasicExample.xcodeproj ファイルと同じディレクトリに、Podfile という名前のテキストファイルを作成し、次の構成を追加します。

source 'https://github.com/CocoaPods/Specs.git'

platform :tvos, '15'
project 'BasicExample.xcodeproj'

target "BasicExample" do
  pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0'
end
Podfile

Podfile が含まれているディレクトリから、次のコマンドを実行します。
```
pod install --repo-update
```
BasicExample.xcworkspace ファイルを開き、BasicExample と Pods（CocoaPods によってインストールされた依存関係）の 2 つのプロジェクトが含まれていることを確認して、インストールが成功したことを確認します。

SDK を手動でダウンロードしてインストールする

Swift Package Manager を使用しない場合は、IMA SDK をダウンロードして、プロジェクトに手動で追加します。

手順を表示

ダウンロードページから、IMA DAI SDK の最新バージョンをダウンロードして解凍します。
BasicExample.xcodeproj を開きます。
左側のペインで、プロジェクト名をクリックします。
中央のペインで [Build Phases] をクリックします。
[Link Binary With Libraries] セクションを開きます。
ライブラリリストの下部にあるプラスアイコン [+] をクリックします。
[その他を追加] をクリックします。
ダウンロードした SDK を展開したディレクトリで、GoogleInteractiveMediaAds.framework を選択し、[開く] をクリックします。
ライブラリリストの下部にあるプラスアイコン [+] をもう一度クリックします。
[ステータス] 列で、GoogleInteractiveMediaAds.framework が Required であることを確認します。
ビルド設定に -ObjC リンカーフラグを含めます。詳しくは、 Apple QA1490 をご覧ください。

IMA SDK をインポートする

import ステートメントを使用して IMA フレームワークを追加します。

Objective-C

#import "ViewController.h"
#import <AVKit/AVKit.h>

@import GoogleInteractiveMediaAds;ViewController.m

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
ViewController.swift

動画プレーヤーを作成して IMA SDK を統合する

次の例では、IMA SDK を初期化しています。

Objective-C

// Live stream asset key, VOD content source and video IDs, and backup content URL.
static NSString *const kAssetKey = @"c-rArva4ShKVIAkNfy6HUQ";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";
static NSString *const kBackupStreamURLString =
    @"http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/"
    @"master.m3u8";
static const StreamType kDefaultStreamType = StreamTypeLive;

@interface ViewController () <IMAAdsLoaderDelegate,
                              IMAStreamManagerDelegate,
                              AVPlayerViewControllerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) id<IMAVideoDisplay> videoDisplay;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];
  self.streamType = kDefaultStreamType;
  [self setupAdsLoader];
  [self setupPlayer];
  [self setupAdContainer];
}

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestStream];
}

- (void)setupPlayer {
  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach video player to view hierarchy.
  [self addChildViewController:self.playerViewController];
  [self.view addSubview:self.playerViewController.view];
  self.playerViewController.view.frame = self.view.bounds;
  [self.playerViewController didMoveToParentViewController:self];
}ViewController.m

Swift

class ViewController:
  UIViewController,
  IMAAdsLoaderDelegate,
  IMAStreamManagerDelegate,
  AVPlayerViewControllerDelegate
{
  // Live stream asset key, VOD content source and video IDs, Google Ad Manager network code, and
  // backup content URL.
  static let assetKey = "c-rArva4ShKVIAkNfy6HUQ"
  static let contentSourceID = "2548831"
  static let videoID = "tears-of-steel"
  static let networkCode = "21775744923"
  static let backupStreamURLString =
    "http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/master.m3u8"

  var adsLoader: IMAAdsLoader?
  var videoDisplay: IMAAVPlayerVideoDisplay!
  var adDisplayContainer: IMAAdDisplayContainer?
  var adContainerView: UIView?
  private var streamManager: IMAStreamManager?
  private var contentPlayhead: IMAAVPlayerContentPlayhead?
  private var playerViewController: AVPlayerViewController!
  private var userSeekTime = 0.0
  private var adBreakActive = false

  private enum StreamType {
    case live
    /// Video on demand.
    case vod
  }

  /// Set the stream type here.
  private let currentStreamType: StreamType = .live

  deinit {
    NotificationCenter.default.removeObserver(self)
  }

  override func viewDidLoad() {
    super.viewDidLoad()
    self.view.backgroundColor = UIColor.black

    setupAdsLoader()
    setupPlayer()
    setupAdContainer()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    requestStream()
  }

  func setupPlayer() {
    let player = AVPlayer()
    let playerViewController = AVPlayerViewController()
    playerViewController.delegate = self
    playerViewController.player = player

    // Set up our content playhead and contentComplete callback.
    contentPlayhead = IMAAVPlayerContentPlayhead(avPlayer: player)
    NotificationCenter.default.addObserver(
      self,
      selector: #selector(ViewController.contentDidFinishPlaying(_:)),
      name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
      object: player.currentItem)

    self.addChild(playerViewController)
    playerViewController.view.frame = self.view.bounds
    self.view.insertSubview(playerViewController.view, at: 0)
    playerViewController.didMove(toParent: self)
    self.playerViewController = playerViewController
  }ViewController.swift

viewDidLoad() では、setupAdsLoader() が IMAAdsLoader を作成し、setupPlayer() が AVPlayerViewController を作成し、setupAdContainer() が広告表示用の UIView を準備します。ビューが表示されると、viewDidAppear() は requestStream() を呼び出して DAI ストリームをリクエストします。

ストリームリクエストパラメータを定義するために、この例では、ライブストリームの asset key や、VOD ストリームの content source ID や video ID などの定数を使用しています。この例では、次のコンポーネントを使用して IMA SDK を管理します。

adsLoader: Google アドマネージャーへのストリームリクエストを処理します。アプリのライフサイクルには単一のインスタンスを使用することをおすすめします。
videoDisplay: IMA が AVPlayer を使用して動画再生を制御し、再生イベントをトラッキングできるようにする IMAVideoDisplay 実装。
adDisplayContainer: 広告 UI 要素のレンダリングと広告ブレーク中の UI フォーカスの処理に使用されるビューを管理します。
streamManager: 広告とコンテンツの結合ストリームの再生を管理し、デリゲートを使用して広告ライフサイクルイベントを送信します。
playerViewController: IMA SDK によって管理される動画ストリームを表示するために使用される tvOS プレーヤー。
adBreakActive: 広告ブレークが再生中かどうかを示すブール値のフラグ。広告をスキップしないようにし、UI フォーカスを管理するために使用されます。

IMAAdsLoader を実装する

次に、IMAAdsLoader をインスタンス化し、広告コンテナビューをビュー階層にアタッチします。

Objective-C

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] init];
  self.adsLoader.delegate = self;
}

- (void)setupAdContainer {
  // Attach the ad container to the view hierarchy on top of the player.
  self.adContainerView = [[UIView alloc] init];
  [self.view addSubview:self.adContainerView];
  self.adContainerView.frame = self.view.bounds;
  // Keep hidden initially, until an ad break.
  self.adContainerView.hidden = YES;
}ViewController.m

Swift

func setupAdsLoader() {
  let adsLoader = IMAAdsLoader(settings: nil)
  adsLoader.delegate = self
  self.adsLoader = adsLoader
}

func setupAdContainer() {
  // Attach the ad container to the view hierarchy on top of the player.
  let adContainerView = UIView()
  self.view.addSubview(adContainerView)
  adContainerView.frame = self.view.bounds
  // Keep hidden initially, until an ad break.
  adContainerView.isHidden = true
  self.adContainerView = adContainerView
}ViewController.swift

ストリームリクエストを行う

ストリーム情報を保持する定数をいくつか作成し、ストリームリクエスト関数を実装してリクエストを行います。

Objective-C

- (void)requestStream {
  self.videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
  self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView
                                                                viewController:self];

  // Use the streamType property to determine which request to create.
  IMAStreamRequest *request;

  switch (self.streamType) {
    case StreamTypeLive: {
      request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                                   networkCode:kNetworkCode
                                            adDisplayContainer:self.adDisplayContainer
                                                  videoDisplay:self.videoDisplay
                                                   userContext:nil];
      NSLog(@"IMA: Requesting Live Stream with Asset Key: %@.", kAssetKey);
      break;
    }
    case StreamTypeVOD: {
      request = [[IMAVODStreamRequest alloc] initWithContentSourceID:kContentSourceID
                                                             videoID:kVideoID
                                                         networkCode:kNetworkCode
                                                  adDisplayContainer:self.adDisplayContainer
                                                        videoDisplay:self.videoDisplay
                                                         userContext:nil];
      NSLog(@"IMA: Requesting VOD Stream with Video ID: %@.", kVideoID);
      break;
    }
  }

  if (request) {
    [self.adsLoader requestStreamWithRequest:request];
  } else {
    // Fallback or error handling if no request object was created
    NSLog(@"IMA Error: Could not create stream request for unknown type.");
    [self playBackupStream];
  }
}ViewController.m

Swift

func requestStream() {
  guard let playerViewController = self.playerViewController else { return }
  guard let adContainerView = self.adContainerView else { return }
  guard let adsLoader = self.adsLoader else { return }

  self.videoDisplay = IMAAVPlayerVideoDisplay(avPlayer: playerViewController.player!)
  let adDisplayContainer = IMAAdDisplayContainer(
    adContainer: adContainerView, viewController: self)
  self.adDisplayContainer = adDisplayContainer

  // Variable to hold the specific stream request object.
  let request: IMAStreamRequest

  switch self.currentStreamType {
  case .live:
    // Create a live stream request.
    request = IMALiveStreamRequest(
      assetKey: ViewController.assetKey,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer,
      videoDisplay: self.videoDisplay,
      pictureInPictureProxy: nil,
      userContext: nil)
    print("IMA: Requesting Live Stream with asset key \(ViewController.assetKey)")

  case .vod:
    // Create a VOD stream request.
    request = IMAVODStreamRequest(
      contentSourceID: ViewController.contentSourceID,
      videoID: ViewController.videoID,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer,
      videoDisplay: self.videoDisplay,
      pictureInPictureProxy: nil,
      userContext: nil)
    print(
      "IMA: Requesting VOD Stream with content source ID \(ViewController.contentSourceID) and "
        + "video ID \(ViewController.videoID)")
  }

  adsLoader.requestStream(with: request)
}ViewController.swift

ストリームイベントを処理する

IMAAdsLoader と IMAStreamManager は、初期化、エラー、ストリーム状態の変化を処理するイベントを発生させます。これらのイベントは IMAAdsLoaderDelegate プロトコルと IMAStreamManagerDelegate プロトコルで発生します。広告読み込みイベントをリッスンして、ストリームを初期化します。広告の読み込みに失敗した場合は、代わりにバックアップストリームを再生します。

Objective-C

- (void)playBackupStream {
  NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
  [self.videoDisplay loadStream:backupStreamURL withSubtitles:@[]];
  [self.videoDisplay play];
  [self startMediaSession];
}

- (void)startMediaSession {
  [[AVAudioSession sharedInstance] setActive:YES error:nil];
  [[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryPlayback error:nil];
}

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to stream manager's events.
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
  NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing the backup stream.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self playBackupStream];
}ViewController.m

Swift

@objc func contentDidFinishPlaying(_ notification: Notification) {
  guard let adsLoader = self.adsLoader else { return }
  adsLoader.contentComplete()
}

func startMediaSession() {
  try? AVAudioSession.sharedInstance().setActive(true, options: [])
  try? AVAudioSession.sharedInstance().setCategory(.playback)
}

// MARK: - IMAAdsLoaderDelegate

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  let streamManager = adsLoadedData.streamManager!
  streamManager.delegate = self
  streamManager.initialize(with: nil)
  self.streamManager = streamManager
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  print("Error loading ads: \(adErrorData.adError.message)")
  let streamUrl = URL(string: ViewController.backupStreamURLString)
  self.videoDisplay.loadStream(streamUrl!, withSubtitles: [])
  self.videoDisplay.play()
  playerViewController.player?.play()
}ViewController.swift

ロギングイベントとエラーイベントを処理する

ストリームマネージャーのデリゲートは複数のイベントを処理できますが、基本的な実装では、イベントのロギング、広告再生中のシークアクションの防止、エラーの処理が最も重要な用途となります。

Objective-C

#pragma mark - IMAStreamManagerDelegate

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

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      self.adContainerView.hidden = NO;
      // Trigger an update to send focus to the ad display container.
      self.adBreakActive = YES;
      [self setNeedsFocusUpdate];
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      self.adContainerView.hidden = YES;
      // Trigger an update to send focus to the content player.
      self.adBreakActive = NO;
      [self setNeedsFocusUpdate];
      break;
    }
    case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
      // Resume playback after the user has closed the dialog.
      [self.videoDisplay play];
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing the backup stream.
  NSLog(@"StreamManager error: %@", error.message);
  [self playBackupStream];
}ViewController.m

Swift

// MARK: - IMAStreamManagerDelegate
func streamManager(_ streamManager: IMAStreamManager, didReceive event: IMAAdEvent) {
  print("StreamManager event \(event.typeString).")
  switch event.type {
  case IMAAdEventType.STREAM_STARTED:
    self.startMediaSession()
  case IMAAdEventType.STARTED:
    // Log extended data.
    if let ad = event.ad {
      let extendedAdPodInfo = String(
        format: "Showing ad %zd/%zd, bumper: %@, title: %@, "
          + "description: %@, contentType:%@, pod index: %zd, "
          + "time offset: %lf, max duration: %lf.",
        ad.adPodInfo.adPosition,
        ad.adPodInfo.totalAds,
        ad.adPodInfo.isBumper ? "YES" : "NO",
        ad.adTitle,
        ad.adDescription,
        ad.contentType,
        ad.adPodInfo.podIndex,
        ad.adPodInfo.timeOffset,
        ad.adPodInfo.maxDuration)

      print("\(extendedAdPodInfo)")
    }
    break
  case IMAAdEventType.AD_BREAK_STARTED:
    if let adContainerView = self.adContainerView {
      adContainerView.isHidden = false
    }
    // Trigger an update to send focus to the ad display container.
    adBreakActive = true
    setNeedsFocusUpdate()
    break
  case IMAAdEventType.AD_BREAK_ENDED:
    if let adContainerView = self.adContainerView {
      adContainerView.isHidden = true
    }
    // Trigger an update to send focus to the content player.
    adBreakActive = false
    setNeedsFocusUpdate()
    break
  case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
    // Resume playback after the user has closed the dialog.
    self.videoDisplay.play()
    break
  default:
    break
  }
}

func streamManager(_ streamManager: IMAStreamManager, didReceive error: IMAAdError) {
  print("StreamManager error: \(error.message ?? "Unknown Error")")
}ViewController.swift

これで、これで、IMA DAI SDK を使用して広告をリクエストし、表示できるようになりました。SDK の高度な機能について詳しくは、他のガイドまたは GitHub のサンプルをご覧ください。

DAI 用 IMA SDK を設定する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

フルサービス DAI

IMA DAI の概要

前提条件

新しい Xcode プロジェクトを作成する

Xcode プロジェクトに IMA DAI SDK を追加する

推奨: Swift Package Manager を使用して SDK をインストールする

CocoaPods を使用して SDK をインストールする

SDK を手動でダウンロードしてインストールする

手順を表示

IMA SDK をインポートする

Objective-C

Swift

動画プレーヤーを作成して IMA SDK を統合する

Objective-C

Swift

IMAAdsLoader を実装する

Objective-C

Swift

ストリーム リクエストを行う

Objective-C

Swift

ストリーム イベントを処理する

Objective-C

Swift

ロギング イベントとエラーイベントを処理する

Objective-C

Swift

DAI 用 IMA SDK を設定する

ストリームリクエストを行う

ストリームイベントを処理する

ロギングイベントとエラーイベントを処理する