Menyiapkan IMA SDK

Pilih platform: HTML5 Android iOS tvOS

IMA SDK memudahkan integrasi iklan multimedia ke dalam situs dan aplikasi Anda. IMA SDK dapat meminta iklan dari server iklan yang kompatibel dengan VAST dan mengelola pemutaran iklan di aplikasi Anda. Dengan SDK sisi klien IMA, Anda tetap memegang kontrol pemutaran video konten, sementara SDK menangani pemutaran iklan. Iklan diputar di pemutar video terpisah yang diposisikan di atas pemutar video konten aplikasi.

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

Catatan: Untuk mengetahui informasi tentang cara berintegrasi dengan platform lain, atau tentang cara menggunakan IMA DAI SDK, lihat Interactive Media Ads SDK.

Ringkasan sisi klien IMA

Penerapan sisi klien IMA melibatkan empat komponen SDK utama, yang ditunjukkan dalam panduan ini:

• IMAAdDisplayContainer: Objek penampung yang menentukan tempat IMA merender elemen UI iklan dan mengukur visibilitas, termasuk Tampilan Aktif dan Open Measurement.
• IMAAdsLoader: Objek yang meminta iklan dan menangani peristiwa dari respons permintaan iklan. Anda hanya boleh meng-instansiasi satu pemuat iklan, yang dapat digunakan kembali selama masa aktif aplikasi.
• IMAAdsRequest: Objek yang menentukan permintaan iklan. Permintaan iklan menentukan URL untuk tag iklan VAST, serta parameter tambahan, seperti dimensi iklan.
• IMAAdsManager: Objek yang berisi respons terhadap permintaan iklan, mengontrol pemutaran iklan, dan memproses peristiwa iklan yang diaktifkan oleh SDK.

Prasyarat

Sebelum memulai, Anda memerlukan hal berikut:

• Xcode 13 atau yang lebih baru
• CocoaPods (paling direkomendasikan), Swift Package Manager, atau salinan IMA SDK untuk iOS yang didownload

1. Buat project Xcode baru

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

2. Menambahkan IMA SDK ke project Xcode

Instal SDK menggunakan CocoaPods (direkomendasikan)

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

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

   Objective-C

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '12'
   
   target "BasicExample" do
     pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1'
   end
   Podfile
   

   Swift

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '12'
   
   target "BasicExample" do
     pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1'
   end
   Podfile
   

2. Dari direktori yang berisi Podfile, jalankan pod install --repo-update.

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

Menginstal SDK menggunakan Swift Package Manager

Interactive Media Ads SDK mendukung Swift Package Manager mulai dari versi 3.18.4. Untuk mengimpor paket Swift, selesaikan langkah-langkah berikut:

Catatan: Jika bermigrasi dari project berbasis CocoaPods, jalankan pod deintegrate untuk menghapus CocoaPods dari project Xcode Anda. File .xcworkspace yang dihasilkan CocoaPods dapat dihapus dengan aman setelahnya. Jika Anda menambahkan SDK Iklan Media Interaktif ke project untuk pertama kalinya, Anda dapat mengabaikan langkah ini.

1. Di Xcode, instal Paket Swift IMA SDK dengan membuka File > Add Package Dependencies....

2. Di perintah, telusuri repositori GitHub Paket Swift IMA iOS SDK: swift-package-manager-google-interactive-media-ads-ios.

3. Pilih versi Paket Swift IMA SDK yang ingin Anda gunakan. Untuk project baru, sebaiknya gunakan Up to Next Major Version.

Setelah selesai, Xcode akan menyelesaikan dependensi paket Anda dan mendownloadnya di latar belakang. Untuk mengetahui detail selengkapnya tentang cara menambahkan dependensi paket, lihat artikel Apple.

Mendownload dan menginstal SDK secara manual

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

Tampilkan/sembunyikan petunjuk

1. Dari halaman Download IMA iOS, download dan ekstrak IMA SDK iOS versi terbaru.
2. Buka BasicExample.xcodeproj.
3. Di panel kiri, klik nama project.
   
4. Di panel tengah, klik Build Phases.
   
5. Luaskan bagian Link Binary With Libraries.
6. Di bagian bawah daftar pustaka, klik ikon plus [+].
7. Klik Tambahkan Lainnya.
8. Di direktori tempat Anda mengekstrak SDK yang didownload, pilih GoogleInteractiveMediaAds.framework, lalu klik Open.
9. Di bagian bawah daftar pustaka, klik ikon plus [+] lagi.
10. Di kolom Status, verifikasi bahwa GoogleInteractiveMediaAds.framework disetel ke Required.
11. Sertakan flag linker -ObjC dalam setelan build Anda. Untuk informasi selengkapnya, lihat Apple QA1490.

3. Membuat pemutar video

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

Objective-C

Impor dependensi pemutar:

#import "ViewController.h"

@import AVFoundation;
ViewController.m

Siapkan variabel pemutar:

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>

/// Content video player.
@property(nonatomic, strong) AVPlayer *contentPlayer;

/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

/// UIView in which we will render our AVPlayer for content.
@property(nonatomic, weak) IBOutlet UIView *videoView;
ViewController.m

Mulai pemutar video saat tampilan dimuat:

@implementation ViewController

// The content URL to play.
NSString *const kTestAppContentUrl_MP4 =
    @"https://storage.googleapis.com/gvabox/media/samples/stock.mp4";

// Ad tag
NSString *const kTestAppAdTagUrl = @"https://pubads.g.doubleclick.net/gampad/ads?"
  @"iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&"
  @"ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&"
  @"correlator=";

- (void)viewDidLoad {
  [super viewDidLoad];

  self.playButton.layer.zPosition = MAXFLOAT;

  [self setupAdsLoader];
  [self setUpContentPlayer];
}

#pragma mark Content Player Setup

- (void)setUpContentPlayer {
  // Load AVPlayer with path to our content.
  NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];
  self.contentPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.contentPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];

  // Set up our content playhead and contentComplete callback.
  self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:self.contentPlayer.currentItem];
}

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

Swift

Impor dependensi pemutar:

import AVFoundation
PlayerContainerViewController.swift

Siapkan variabel pemutar:

class PlayerContainerViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
  static let contentURL = URL(
    string: "https://storage.googleapis.com/gvabox/media/samples/stock.mp4")!

  private var contentPlayer = AVPlayer(url: PlayerContainerViewController.contentURL)

  private lazy var playerLayer: AVPlayerLayer = {
    AVPlayerLayer(player: contentPlayer)
  }()
PlayerContainerViewController.swift

Mulai pemutar video saat tampilan dimuat:

private lazy var videoView: UIView = {
  let videoView = UIView()
  videoView.translatesAutoresizingMaskIntoConstraints = false
  view.addSubview(videoView)

  NSLayoutConstraint.activate([
    videoView.bottomAnchor.constraint(
      equalTo: view.safeAreaLayoutGuide.bottomAnchor),
    videoView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
    videoView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),
    videoView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
  ])
  return videoView
}()

// MARK: - View controller lifecycle methods

override func viewDidLoad() {
  super.viewDidLoad()

  videoView.layer.addSublayer(playerLayer)
  adsLoader.delegate = self

  NotificationCenter.default.addObserver(
    self,
    selector: #selector(contentDidFinishPlaying(_:)),
    name: .AVPlayerItemDidPlayToEndTime,
    object: contentPlayer.currentItem)
}

override func viewDidAppear(_ animated: Bool) {
  super.viewDidAppear(animated)
  playerLayer.frame = videoView.layer.bounds
}

override func viewWillTransition(
  to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator
) {
  coordinator.animate { _ in
    // do nothing
  } completion: { _ in
    self.playerLayer.frame = self.videoView.layer.bounds
  }
}

// MARK: - Public methods

func playButtonPressed() {
  requestAds()
}
PlayerContainerViewController.swift

4. Mengimpor IMA SDK

Untuk mengimpor IMA SDK, lakukan hal berikut:

Objective-C

1. Impor IMA SDK:

   @import GoogleInteractiveMediaAds;
   ViewController.m
   

2. Buat variabel untuk class IMAAdsLoader, IMAAVPlayerContentPlayhead, dan IMAAdsManager yang digunakan dalam aplikasi:

   // SDK
   /// Entry point for the SDK. Used to make ad requests.
   @property(nonatomic, strong) IMAAdsLoader *adsLoader;
   
   /// Playhead used by the SDK to track content video progress and insert mid-rolls.
   @property(nonatomic, strong) IMAAVPlayerContentPlayhead *contentPlayhead;
   
   /// Main point of interaction with the SDK. Created by the SDK as the result of an ad request.
   @property(nonatomic, strong) IMAAdsManager *adsManager;
   ViewController.m
   

Swift

1. Impor IMA SDK:

   import GoogleInteractiveMediaAds
   PlayerContainerViewController.swift
   

2. Buat variabel untuk class IMAAdsLoader, IMAAVPlayerContentPlayhead, dan IMAAdsManager yang digunakan dalam aplikasi:

   static let adTagURLString =
     "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/"
     + "single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&"
     + "gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&correlator="
   
   private let adsLoader = IMAAdsLoader()
   private var adsManager: IMAAdsManager?
   
   private lazy var contentPlayhead: IMAAVPlayerContentPlayhead = {
     IMAAVPlayerContentPlayhead(avPlayer: contentPlayer)
   }()
   PlayerContainerViewController.swift
   

5. Menerapkan pelacak penunjuk putar konten dan pengamat akhir streaming

Untuk memutar iklan mid-roll, IMA SDK perlu melacak posisi saat ini konten video Anda. Untuk melakukannya, buat class yang mengimplementasikan IMAContentPlayhead. Jika Anda menggunakan AVPlayer, seperti yang ditunjukkan dalam contoh ini, SDK menyediakan class IMAAVPlayerContentPlayhead yang melakukan hal ini untuk Anda. Jika tidak menggunakan AVPlayer, Anda harus menerapkan IMAContentPlayhead di class Anda sendiri.

Anda juga perlu memberi tahu SDK saat konten Anda selesai diputar agar SDK dapat menampilkan iklan post-roll. Hal ini dilakukan dengan memanggil metode contentComplete di IMAAdsLoader, menggunakan AVPlayerItemDidPlayToEndTimeNotification.

Objective-C

Buat instance IMAAVPlayerContentPlayhead dalam penyiapan pemutar:

// Set up our content playhead and contentComplete callback.
self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(contentDidFinishPlaying:)
                                             name:AVPlayerItemDidPlayToEndTimeNotification
                                           object:self.contentPlayer.currentItem];
ViewController.m

Buat metode contentDidFinishPlaying() untuk memanggil IMAAdsLoader.contentComplete() saat konten selesai diputar:

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if (notification.object == self.contentPlayer.currentItem) {
    [self.adsLoader contentComplete];
  }
}
ViewController.m

Swift

Buat pengamat akhir konten dalam penyiapan pemutar:

NotificationCenter.default.addObserver(
  self,
  selector: #selector(contentDidFinishPlaying(_:)),
  name: .AVPlayerItemDidPlayToEndTime,
  object: contentPlayer.currentItem)
PlayerContainerViewController.swift

Buat metode contentDidFinishPlaying() untuk memanggil IMAAdsLoader.contentComplete() saat konten selesai diputar:

@objc func contentDidFinishPlaying(_ notification: Notification) {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if notification.object as? AVPlayerItem == contentPlayer.currentItem {
    adsLoader.contentComplete()
  }
}
PlayerContainerViewController.swift

6. Lakukan inisialisasi loader iklan dan buat permintaan iklan

Untuk meminta serangkaian iklan, Anda harus membuat instance IMAAdsLoader. Loader ini dapat digunakan untuk memproses objek IMAAdsRequest yang terkait dengan URL tag iklan tertentu.

Sebagai praktik terbaik, pertahankan hanya satu instance IMAAdsLoader untuk seluruh siklus proses aplikasi Anda. Untuk membuat permintaan iklan tambahan, buat objek IMAAdsRequest baru, tetapi gunakan kembali IMAAdsLoader yang sama. Untuk mengetahui informasi selengkapnya, lihat FAQ IMA SDK.

Objective-C

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

- (void)requestAds {
  // Create an ad display container for ad rendering.
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];
  // Create an ad request with our ad tag, display container, and optional user context.
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl
                                                adDisplayContainer:adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}
ViewController.m

Swift

private func requestAds() {
  // Create ad display container for ad rendering.
  let adDisplayContainer = IMAAdDisplayContainer(
    adContainer: videoView, viewController: self, companionSlots: nil)
  // Create an ad request with our ad tag, display container, and optional user context.
  let request = IMAAdsRequest(
    adTagUrl: PlayerContainerViewController.adTagURLString,
    adDisplayContainer: adDisplayContainer,
    contentPlayhead: contentPlayhead,
    userContext: nil)

  adsLoader.requestAds(with: request)
}
PlayerContainerViewController.swift

7. Menyiapkan delegasi loader iklan

Pada peristiwa pemuatan yang berhasil, IMAAdsLoader memanggil metode adsLoadedWithData dari delegasi yang ditetapkan, dengan meneruskan instance IMAAdsManager. Kemudian, Anda dapat melakukan inisialisasi pengelola iklan, yang memuat masing-masing iklan, seperti yang ditentukan oleh respons terhadap URL tag iklan.

Selain itu, pastikan untuk menangani error apa pun yang mungkin terjadi selama proses pemuatan. Jika iklan tidak dimuat, pastikan pemutaran media berlanjut tanpa iklan, agar tidak mengganggu pengalaman pengguna.

Objective-C

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  // Create ads rendering settings to tell the SDK to use the in-app browser.
  IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];
  adsRenderingSettings.linkOpenerPresentingController = self;
  // Initialize the ads manager.
  [self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Something went wrong loading ads. Log the error and play the content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayer play];
}
ViewController.m

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  adsManager = adsLoadedData.adsManager
  adsManager?.delegate = self

  // Create ads rendering settings and tell the SDK to use the in-app browser.
  let adsRenderingSettings = IMAAdsRenderingSettings()
  adsRenderingSettings.linkOpenerPresentingController = self

  // Initialize the ads manager.
  adsManager?.initialize(with: adsRenderingSettings)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  if let message = adErrorData.adError.message {
    print("Error loading ads: \(message)")
  }
  contentPlayer.play()
}
PlayerContainerViewController.swift

8. Menyiapkan delegasi pengelola iklan

Terakhir, untuk mengelola peristiwa dan perubahan status, pengelola iklan memerlukan delegasi sendiri. IMAAdManagerDelegate memiliki metode untuk menangani peristiwa dan error iklan, serta metode untuk memicu pemutaran dan jeda pada konten video Anda.

Mulai pemutaran

Dengarkan peristiwa LOADED untuk memulai pemutaran konten dan iklan. Untuk detail selengkapnya, lihat didReceiveAdEvent.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // When the SDK notified us that ads have been loaded, play them.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}
ViewController.m

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
  // When the SDK notifies us the ads have been loaded, play them.
  if event.type == IMAAdEventType.LOADED {
    adsManager.start()
  }
}
PlayerContainerViewController.swift

Menangani error

Tambahkan juga pengendali untuk error iklan. Jika terjadi error, seperti pada langkah sebelumnya, lanjutkan pemutaran konten.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Something went wrong with the ads manager after ads were loaded. Log the error and play the
  // content.
  NSLog(@"AdsManager error: %@", error.message);
  [self.contentPlayer play];
}
ViewController.m

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
  // Something went wrong with the ads manager after ads were loaded.
  // Log the error and play the content.
  if let message = error.message {
    print("AdsManager error: \(message)")
  }
  contentPlayer.play()
}
PlayerContainerViewController.swift

Memproses peristiwa putar dan jeda

Dua metode delegasi terakhir yang perlu Anda terapkan digunakan untuk memicu peristiwa pemutaran dan jeda pada konten video yang mendasarinya, saat diminta oleh IMA SDK. Memicu jeda dan putar saat diminta mencegah pengguna melewatkan sebagian konten video saat iklan ditampilkan.

Objective-C

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // The SDK is going to play ads, so pause the content.
  [self.contentPlayer pause];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // The SDK is done playing ads (at least for now), so resume the content.
  [self.contentPlayer play];
}
ViewController.m

Swift

func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
  // The SDK is going to play ads, so pause the content.
  contentPlayer.pause()
}

func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
  // The SDK is done playing ads (at least for now), so resume the content.
  contentPlayer.play()
}
PlayerContainerViewController.swift

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

Langkah Berikutnya

Untuk memaksimalkan pendapatan iklan di platform iOS, minta izin App Tracking Transparency untuk menggunakan IDFA.