DAI 用 IMA SDK を設定する

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

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

フルサービス DAI

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

IMA DAI の概要

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

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

前提条件

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

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

また、IMA SDK からストリームをリクエストするために使用されるパラメータも必要です。リクエスト パラメータの例については、サンプル ストリームをご覧ください。

ライブストリーム パラメータ
アセットキー Google アド マネージャーでライブ配信を識別するアセットキー。
例: c-rArva4ShKVIAkNfy6HUQ
VOD ストリーム パラメータ
コンテンツ ソース ID Google アド マネージャーのコンテンツ ソース ID。
例: 2548831
動画 ID Google アド マネージャーの動画 ID。
例: tears-of-steel
共通(VOD とライブ配信)パラメータ
ネットワーク コード Google アド マネージャーのネットワーク コード。
例: 21775744923

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

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

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

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

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.27.4'
    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 をダウンロードして、プロジェクトに手動で追加できます。

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

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

Objective-C

#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

Swift

// Copyright 2024 Google LLC. All rights reserved.
//
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
// file except in compliance with the License. You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under
// the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
// ANY KIND, either express or implied. See the License for the specific language governing
// permissions and limitations under the License.

import AVFoundation
import UIKit

class ViewController: UIViewController {

  /// Content URL.
  static let backupStreamURLString =
    "http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8"

  /// Play button.
  @IBOutlet private weak var playButton: UIButton!

  @IBOutlet private weak var videoView: UIView!
  /// Video player.
  private var videoPlayer: AVPlayer?

  override func viewDidLoad() {
    super.viewDidLoad()

    playButton.layer.zPosition = CGFloat(MAXFLOAT)

    // Load AVPlayer with path to our content.
    // note: this unwrap is safe because the URL is a constant string.
    let contentURL = URL(string: ViewController.backupStreamURLString)!
    videoPlayer = AVPlayer(url: contentURL)

    // Create a player layer for the player.
    let playerLayer = AVPlayerLayer(player: videoPlayer)

    // Size, position, and display the AVPlayer.
    playerLayer.frame = videoView.layer.bounds
    videoView.layer.addSublayer(playerLayer)
  }

  @IBAction func onPlayButtonTouch(_ sender: Any) {
    videoPlayer?.play()
    playButton.isHidden = true
  }
}

広告ローダを初期化する

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

主要な IMA SDK コンポーネントを保存するために、次の非公開プロパティを追加します。

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

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

Objective-C

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

Swift

import GoogleInteractiveMediaAds
// ...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAStreamManagerDelegate {
  // ...

  /// The entry point for the IMA DAI SDK to make DAI stream requests.
  private var adsLoader: IMAAdsLoader?
  /// The container where the SDK renders each ad's user interface elements and companion slots.
  private var adDisplayContainer: IMAAdDisplayContainer?
  /// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
  /// metadata.
  private var imaVideoDisplay: IMAAVPlayerVideoDisplay!
  /// References the stream manager from the IMA DAI SDK after successfully loading the DAI stream.
  private var streamManager: IMAStreamManager?

  // ...

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    adsLoader = IMAAdsLoader(settings: nil)
    adsLoader?.delegate = self

    // Create an ad display container for rendering ad UI elements and the companion ad.
    adDisplayContainer = IMAAdDisplayContainer(
      adContainer: videoView,
      viewController: self,
      companionSlots: nil)

    // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
    imaVideoDisplay = IMAAVPlayerVideoDisplay(avPlayer: videoPlayer)
  }

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

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

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

Objective-C

- (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;
  if (kStreamType == StreamTypeLive) {
    // Live stream request. Replace the asset key with your value.
    request = [[IMALiveStreamRequest alloc] initWithAssetKey:kLiveStreamAssetKey
                                                 networkCode:kNetworkCode
                                          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:kVODContentSourceID
                                                           videoID:kVODVideoID
                                                       networkCode:kNetworkCode
                                                adDisplayContainer:self.adDisplayContainer
                                                      videoDisplay:self.imaVideoDisplay
                                                       userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}

Swift

@IBAction func onPlayButtonTouch(_ sender: Any) {
  requestStream()
  playButton.isHidden = true
}

func requestStream() {
  // Create a stream request. Use one of "Livestream request" or "VOD request".
  if ViewController.requestType == StreamType.live {
    // Livestream request.
    let request = IMALiveStreamRequest(
      assetKey: ViewController.assetKey,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: imaVideoDisplay,
      userContext: nil)
    adsLoader?.requestStream(with: request)
  } else {
    // VOD stream request.
    let request = IMAVODStreamRequest(
      contentSourceID: ViewController.contentSourceID,
      videoID: ViewController.videoID,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: imaVideoDisplay,
      userContext: nil)
    adsLoader?.requestStream(with: request)
  }
}

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

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

adsLoadedWithData デリゲート メソッドで、IMAStreamManagerDelegate を設定します。ストリーム マネージャーを初期化します。初期化時に、ストリーム マネージャーが再生を開始します。

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

Objective-C

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

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  print("DAI stream loaded. Stream session ID: \(adsLoadedData.streamManager!.streamId!)")
  streamManager = adsLoadedData.streamManager!
  streamManager!.delegate = self
  streamManager!.initialize(with: nil)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  print("Error loading DAI stream. Error message: \(adErrorData.adError.message!)")
  // Play the backup stream.
  videoPlayer.play()
}

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

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

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

Objective-C

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

Swift

func streamManager(_ streamManager: IMAStreamManager, didReceive event: IMAAdEvent) {
  print("Ad event \(event.typeString).")
  switch event.type {
  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:
    print("Ad break started.")
    break
  case IMAAdEventType.AD_BREAK_ENDED:
    print("Ad break ended.")
    break
  case IMAAdEventType.AD_PERIOD_STARTED:
    print("Ad period started.")
    break
  case IMAAdEventType.AD_PERIOD_ENDED:
    print("Ad period ended.")
    break
  default:
    break
  }
}

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

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