Mulai

IMA SDK memudahkan integrasi iklan multimedia ke situs dan aplikasi Anda. IMA SDK dapat meminta iklan dari server iklan yang sesuai dengan VAST dan mengelola pemutaran iklan di aplikasi Anda. Dengan IMA DAI SDK, aplikasi membuat permintaan streaming untuk iklan dan video konten, baik VOD maupun konten live. SDK kemudian menampilkan streaming video gabungan, sehingga Anda tidak perlu mengelola peralihan antara video iklan dan konten dalam aplikasi.

Panduan ini menunjukkan cara mengintegrasikan IMA SDK ke dalam aplikasi pemutar video sederhana. Jika Anda ingin melihat atau mengikuti integrasi contoh yang telah selesai, download BasicExample dari GitHub.

Ringkasan DAI DAI

Untuk menerapkan IMA DAI melibatkan empat komponen SDK utama, yang ditunjukkan dalam panduan ini:

  • IMAAdDisplayContainer: Objek penampung yang berada di atas elemen pemutaran video dan menampung elemen UI iklan.
  • IMAAdsLoader: Objek yang meminta streaming dan menangani peristiwa yang dipicu oleh objek respons permintaan streaming. Anda hanya boleh membuat satu loader iklan, yang dapat digunakan kembali selama masa aktif aplikasi.
  • IMAStreamRequest IMAVODStreamRequest atau IMALiveStreamRequest: Objek yang menentukan permintaan streaming. Permintaan streaming dapat berupa untuk video on demand atau live stream. Permintaan menentukan Content ID, serta kunci API atau token autentikasi dan parameter lainnya.
  • IMAStreamManager: Objek yang menangani streaming penyisipan iklan dinamis dan interaksi dengan backend DAI. Pengelola streaming juga menangani pelacakan ping dan meneruskan streaming dan peristiwa iklan ke penayang.

Prasyarat

Sebelum memulai, Anda memerlukan hal berikut:

1. Membuat project Xcode baru

Di Xcode, buat project iOS baru menggunakan Objective-C. Gunakan BasicExample sebagai nama project.

2. Menambahkan IMA SDK ke project Xcode

Menginstal SDK menggunakan CocoaPods (lebih disarankan)

CocoaPods merupakan pengelola dependensi untuk project Xcode dan merupakan metode yang direkomendasikan untuk menginstal IMA SDK. Untuk informasi selengkapnya tentang cara menginstal atau menggunakan CocoaPods, lihat dokumentasi CocoaPods. Setelah Anda menginstal CocoaPods, gunakan petunjuk berikut untuk menginstal IMA SDK:

  1. Dalam direktori yang sama dengan file BasicExample.xcodeproj, buat file teks bernama Podfile, dan tambahkan konfigurasi berikut:

    source 'https://github.com/CocoaPods/Specs.git'
    platform :ios, '10'
    target "BasicExample" do
      pod 'GoogleAds-IMA-iOS-SDK', '~> 3.11.4'
    end
    
  2. Dari direktori yang berisi Podfile, jalankan pod install --repo-update

  3. Pastikan penginstalan berhasil dengan membuka file BasicExample.xcworkspace dan mengonfirmasi bahwa penginstalan berisi dua project: BasicExample dan Pods (dependensi yang diinstal oleh CocoaPods).

Mendownload dan menginstal SDK secara manual

Jika tidak ingin menggunakan CocoaPods, Anda dapat mendownload IMA SDK dan menambahkannya secara manual ke project Anda.

3. Membuat pemutar video sederhana

Pertama, implementasikan pemutar video dasar. Awalnya, pemutar ini tidak menggunakan IMA SDK dan belum berisi metode apa pun untuk memicu pemutaran.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

@interface ViewController ()
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

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

@end

4. Mengimpor SDK dan menambahkan stub untuk interaksi IMA

Setelah menambahkan IMA SDK ke project Anda, impor SDK dan tambahkan stub untuk titik utama interaksi IMA.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  [self setupAdsLoader];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

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

  [self attachAdContainer];
}

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

- (void)setupAdsLoader {}

- (void)attachAdContainer {}

- (void)requestStream {}

@end

5. Menerapkan IMAAdsLoader

Selanjutnya, buat instance IMAAdsLoader dan lampirkan tampilan penampung iklan ke hierarki tampilan.

ViewController.m

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

- (void)attachAdContainer {
  self.adContainerView = [[UIView alloc] init];
  [self.view addSubview:self.adContainerView];
  self.adContainerView.frame = self.view.bounds;
}
...

6. Membuat permintaan streaming

Buat beberapa konstanta untuk menyimpan informasi streaming, lalu implementasikan fungsi permintaan streaming untuk membuat permintaan.

ViewController.m

...
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
static NSString *const kVideoID = @"tears-of-steel";

@interface ViewController ()
...

- (void)requestStream {
  IMAAVPlayerVideoDisplay *videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
  IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                                              adDisplayContainer:adDisplayContainer
                                                                    videoDisplay:videoDisplay];
  // VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
  // to switch from a livestream to a VOD stream.
  // IMAVODStreamRequest *request =
  //     [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
  //                                                  videoId:kVideoID
  //                                       adDisplayContainer:adDisplayContainer
  //                                             videoDisplay:videoDisplay];
  [self.adsLoader requestStreamWithRequest:request];
}
...

7. Menangani peristiwa streaming

Peristiwa IMAAdsLoader dan IMAStreamManager diaktifkan yang digunakan untuk menangani inisialisasi, error, dan perubahan status streaming. Peristiwa ini diaktifkan melalui protokol IMAAdsLoaderDelegate dan IMAStreamManagerDelegate. Proses peristiwa iklan yang dimuat dan inisialisasi aliran data. Jika iklan gagal dimuat, putar streaming cadangan.

ViewController.m

...
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kBackupStreamURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>

...
  [self.adsLoader requestStreamWithRequest:request];
}

- (void)playBackupStream {
  NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
  AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
  [self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
  [self.playerViewController.player play];
}


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


#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}

- (void)streamManager:(IMAStreamManager *)streamManager
  adDidProgressToTime:(NSTimeInterval)time
           adDuration:(NSTimeInterval)adDuration
           adPosition:(NSInteger)adPosition
             totalAds:(NSInteger)totalAds
      adBreakDuration:(NSTimeInterval)adBreakDuration {}

@end

8. Menangani peristiwa logging dan error

Ada beberapa peristiwa yang dapat ditangani oleh delegasi pengelola streaming, tetapi untuk penerapan dasar, penggunaan yang paling penting adalah melakukan logging peristiwa, untuk mencegah tindakan pencarian saat iklan diputar, dan menangani error.

ViewController.m

...
#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"StreamManager event (%@).", event.typeString);
  switch (event.type) {
    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: {
      // Prevent user seek through when an ad starts and show the ad controls.
      self.adContainerView.hidden = NO;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow user seek through after an ad ends and hide the ad controls.
      self.adContainerView.hidden = YES;
      break;
    }
    default:
      break;
  }
}

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

@end

Selesai. Sekarang Anda meminta dan menampilkan iklan dengan IMA SDK. Untuk mempelajari fitur SDK lanjutan lainnya, lihat panduan lainnya atau contoh di GitHub.

Langkah Berikutnya

Untuk memaksimalkan pendapatan iklan pada platform iOS, minta izin Transparansi dan Pelacakan Aplikasi untuk menggunakan IDFA.