このページは Cloud Translation API によって翻訳されました。

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 の実装には、このガイドで説明するように、4 つの主要な SDK コンポーネントが関与します。

IMAAdDisplayContainer - 動画再生要素の上に配置され、広告 UI 要素を格納するコンテナオブジェクト。
IMAAdsLoader - ストリームをリクエストし、ストリームリクエストレスポンスオブジェクトによってトリガーされたイベントを処理するオブジェクト。インスタンス化すべき広告ローダは 1 つだけです。この広告ローダは、アプリの存続期間中ずっと再利用できます。
IMAStreamRequest - IMAPodVODStreamRequest または IMAPodStreamRequest。
IMAStreamManager - ダイナミック広告挿入ストリームと DAI バックエンドとのインタラクションを処理するオブジェクト。ストリームマネージャーは、トラッキングピングも処理し、ストリームイベントと広告イベントをパブリッシャーに転送します。

また、Pod サービングストリームを再生するには、カスタム VTP ハンドラを実装する必要があります。このカスタム VTP ハンドラは、コンテンツとステッチされた広告の両方を含むストリームマニフェストを返すために必要なその他の情報とともに、ストリーム ID を動画技術パートナー（VTP）に送信します。VTP から、カスタム VTP ハンドラを実装する手順が提供されます。

前提条件

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

Xcode 13 以降
CocoaPods（推奨）、Swift パッケージマネージャー、または iOS 用 IMA DAI SDK のダウンロードコピー

また、IMA SDK からストリームをリクエストするために使用するパラメータも必要です。

ライブ配信のパラメータ
ネットワークコード	アドマネージャー 360 アカウントのネットワークコード。例: `51636543`
カスタムアセットキー	キャンペーンマネージャー 360 で Pod 配信イベントを識別するカスタムアセットキー。これは、マニフェストマニピュレータまたはサードパーティの Pod Serving パートナーによって作成できます。例: `google-sample`
VOD ストリームパラメータ
ネットワークコード	アドマネージャー 360 アカウントのネットワークコード。例: `51636543`

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

Xcode で、Objective-C を使用して「PodServingExample」という名前の新しい iOS プロジェクトを作成します。

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

次の 3 つの方法のいずれかを使用して IMA DAI SDK をインストールします。

CocoaPods を使用して SDK をインストールする（推奨）

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

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

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

platform :ios, '14'

target 'PodServingExample' do
  pod 'GoogleAds-IMA-iOS-SDK'
end
Podfile
```
Podfile が含まれているディレクトリから、次のコマンドを実行します。
```
pod install --repo-update
```

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

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

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

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

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

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

手順を表示

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

シンプルな動画プレーヤーを作成する

UI ビューにラップされた AV プレーヤーを使用して、メインビューコントローラに動画プレーヤーを実装します。IMA SDK は、UI ビューを使用して広告 UI 要素を表示します。

ViewController.m

#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
ViewController.m

広告ローダを初期化する

IMA SDK をビューコントローラにインポートし、IMAAdsLoaderDelegate プロトコルと IMAStreamManagerDelegate プロトコルを実装して、広告ローダーとストリームマネージャーのイベントを処理します。

次のプライベートプロパティを追加して、重要な IMA SDK コンポーネントを保存します。

IMAAdsLoader - アプリのライフサイクル全体でストリームリクエストを管理します。
IMAAdDisplayContainer - 広告のユーザーインターフェース要素の挿入と管理を処理します。
IMAAVPlayerVideoDisplay - IMA SDK とメディアプレーヤーの間で通信し、タイミング付きメタデータを処理します。
IMAStreamManager - ストリームの再生を管理し、広告関連のイベントを発生させます。

ビューの読み込み後に、広告ローダ、広告表示コンテナ、動画表示を初期化します。

ViewController.m

@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];
}ViewController.m

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

ユーザーが再生ボタンを押したら、新しいストリーミングリクエストを行います。ライブ配信には IMAPodStreamRequest クラスを使用します。VOD ストリームの場合は、IMAPodVODStreamRequest クラスを使用します。

ストリームリクエストには、ストリームパラメータと、広告ディスプレイコンテナと動画ディスプレイへの参照が必要です。

ViewController.m

- (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];
}ViewController.m

ストリーム読み込みイベントをリッスンする

IMAAdsLoader クラスは、ストリームリクエストの初期化が成功した場合または失敗した場合に、IMAAdsLoaderDelegate メソッドを呼び出します。

adsLoadedWithData デリゲートメソッドで、IMAStreamManagerDelegate を設定します。ストリーム ID をカスタム VTP ハンドラに渡し、ストリームマニフェストの URL を取得します。ライブ配信の場合は、マニフェスト URL を動画ディスプレイに読み込み、再生を開始します。VOD ストリームの場合は、マニフェスト URL をストリームマネージャーの loadThirdPartyStream メソッドに渡します。このメソッドは、アドマネージャー 360 から広告イベントデータをリクエストし、マニフェスト URL を読み込んで再生を開始します。

failedWithErrorData デリゲートメソッドで、エラーをログに記録します。必要に応じて、バックアップストリームを再生します。DAI のベストプラクティスをご覧ください。

ViewController.m

- (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];
}ViewController.m

カスタム VTP ハンドラを実装する

カスタム VTP ハンドラは、コンテンツとステッチされた広告の両方を含むストリームマニフェストを返すために VTP が必要とするその他の情報とともに、視聴者のストリーム ID を動画技術パートナー（VTP）に送信します。VTP には、カスタム VTP ハンドラを実装する方法に関する具体的な手順が記載されています。

たとえば、VTP には、マクロ [[STREAMID]] を含むマニフェストテンプレートの URL が含まれている場合があります。この例では、ハンドラはマクロの代わりにストリーム ID を挿入し、結果のマニフェスト URL を返します。

ViewController.m

/// 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];
};ViewController.m

広告イベントをリッスンする

IMAStreamManager は IMAStreamManagerDelegate メソッドを呼び出して、ストリームイベントとエラーをアプリに渡します。

この例では、メインの広告イベントをコンソールに記録します。

ViewController.m

- (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];
}ViewController.m

IMA DAI アセットをクリーンアップする

ストリームの再生を停止し、すべての広告トラッキングを停止し、読み込まれたすべてのストリームアセットを解放するには、IMAStreamManager.destroy() を呼び出します。

アプリを実行します。成功した場合は、IMA SDK を使用して Google DAI ストリームをリクエストして再生できます。SDK の高度な機能について詳しくは、左側のサイドバーに表示されている他のガイドまたは GitHub のサンプルをご覧ください。

IMA DAI SDK スタートガイド

Pod Serving DAI

IMA DAI の概要

前提条件

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

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

CocoaPods を使用して SDK をインストールする（推奨）

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

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

手順を表示

シンプルな動画プレーヤーを作成する

広告ローダを初期化する

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

ストリーム読み込みイベントをリッスンする

カスタム VTP ハンドラを実装する

広告イベントをリッスンする

IMA DAI アセットをクリーンアップする

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