Halaman ini diterjemahkan oleh Cloud Translation API.

Memulai

IMA SDK memudahkan pengintegrasian iklan multimedia ke dalam situs dan aplikasi Anda. IMA SDK dapat minta iklan dari semua server iklan yang sesuai dengan VAST dan mengelola pemutaran iklan di aplikasi Anda. Dengan SDK sisi klien IMA, Anda mempertahankan kontrol atas pemutaran video konten, sedangkan 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 pemutar video sederhana . Jika Anda ingin melihat atau mengikuti contoh yang telah selesai integrasi, download BasicExample dari GitHub.

Ringkasan sisi klien IMA

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

IMAAdDisplayContainer: Objek penampung tempat iklan dirender.
IMAAdsLoader: Objek yang meminta iklan dan menangani peristiwa dari respons permintaan iklan. Anda hanya boleh membuat instance satu loader iklan, yang dapat digunakan kembali selama masa pakai 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 iklan yang diaktifkan oleh SDK.

Prasyarat

Sebelum memulai, Anda memerlukan hal berikut:

Xcode 13 atau yang lebih baru
CocoaPods (lebih disukai), Swift Package Manager, atau salinan yang diunduh dari IMA SDK untuk tvOS

1. Membuat project Xcode baru

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

2. Menambahkan IMA SDK ke project Xcode

Menginstal SDK menggunakan CocoaPods (lebih disukai)

CocoaPods adalah pengelola dependensi untuk proyek Xcode dan direkomendasikan penginstalan 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:

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

source 'https://github.com/CocoaPods/Specs.git'
platform :tvos, '14'
target "BasicExample" do
  pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.13.0'
end

Dari direktori yang berisi Podfile, jalankan pod install --repo-update
Verifikasi bahwa instalasi berhasil dengan membuka 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 versi 4.8.2. Ikuti langkah-langkah di bawah ini untuk mengimpor paket Swift.

Di Xcode, instal IMA SDK Swift Package dengan membuka File > Tambahkan Paket....

Pada perintah yang muncul, telusuri GitHub Paket Swift IMA SDK repositori:

https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos

Pilih versi Paket Swift IMA SDK yang ingin Anda gunakan. Untuk project baru, sebaiknya gunakan Versi Utama Berikutnya.

Setelah selesai, Xcode menyelesaikan dependensi paket Anda dan mengunduhnya di latar belakang. Untuk detail selengkapnya tentang cara menambahkan paket dependensi, lihat Artikel Apple.

Mendownload dan menginstal SDK secara manual

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

Tampilkan/sembunyikan petunjuk

Dari halaman Download IMA tvOS, download dan ekstrak versi terbaru IMA SDK tvOS.
Buka BasicExample.xcodeproj.
Di panel kiri, klik nama project.
Di panel tengah, klik Build Phases.
Luaskan bagian Link Binary With Libraries.
Di bagian bawah daftar library, klik ikon plus [+].
Klik Tambahkan Lainnya.
Di direktori tempat Anda mengekstrak SDK yang didownload, pilih GoogleInteractiveMediaAds.framework dan klik Buka.
Di bagian bawah daftar library, klik ikon plus [+] lagi.
Di kolom Status, pastikan bahwa GoogleInteractiveMediaAds.framework disetel ke Required.
Sertakan flag linker -ObjC dalam setelan build Anda. Sebagai informasi selengkapnya, lihat Apple QA1490.

3. Membuat pemutar video sederhana

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

ViewController.m

Objective-C

#import "ViewController.h"

#import <AVKit/AVKit.h>

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";

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

@implementation ViewController

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

- (void)setupContentPlayer {
  // Create a content video player.
  NSURL *contentURL = [NSURL URLWithString:kContentURLString];
  AVPlayer *player = [AVPlayer playerWithURL:contentURL];
  self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
  self.contentPlayerViewController.player = player;
  self.contentPlayerViewController.view.frame = self.view.bounds;

  // Attach content video player to view hierarchy.
  [self showContentPlayer];
}

// Add the content video player as a child view controller.
- (void)showContentPlayer {
  [self addChildViewController:self.contentPlayerViewController];
  self.contentPlayerViewController.view.frame = self.view.bounds;
  [self.view insertSubview:self.contentPlayerViewController.view atIndex:0];
  [self.contentPlayerViewController didMoveToParentViewController:self];
}

// Remove and detach the content video player.
- (void)hideContentPlayer {
  // The whole controller needs to be detached so that it doesn't capture events from the remote.
  [self.contentPlayerViewController willMoveToParentViewController:nil];
  [self.contentPlayerViewController.view removeFromSuperview];
  [self.contentPlayerViewController removeFromParentViewController];
}

@end

Swift

import AVFoundation
import UIKit

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

  var playerViewController: AVPlayerViewController!

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

  func setUpContentPlayer() {
    // Load AVPlayer with path to your content.
    let contentURL! = URL(string: ViewController.ContentURLString)
    let player = AVPlayer(url: contentURL)
    playerViewController = AVPlayerViewController()
    playerViewController.player = player

    showContentPlayer()
  }

  func showContentPlayer() {
    self.addChild(playerViewController)
    playerViewController.view.frame = self.view.bounds
    self.view.insertSubview(playerViewController.view, at: 0)
    playerViewController.didMove(toParent:self)
  }

  func hideContentPlayer() {
    // The whole controller needs to be detached so that it doesn't capture  events from the remote.
    playerViewController.willMove(toParent:nil)
    playerViewController.view.removeFromSuperview()
    playerViewController.removeFromParent()
  }
}

4. Mengimpor IMA SDK

Berikutnya, tambahkan kerangka kerja IMA menggunakan pernyataan impor di bawah data.

ViewController.m

Objective-C

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

5. Mengimplementasikan pelacak pemutaran konten dan pengamat akhir streaming

Untuk memutar iklan mid-roll, IMA SDK harus melacak posisi saat ini dari 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 akan melakukannya untuk Anda. Jika tidak menggunakan AVPlayer, Anda perlu menerapkan IMAContentPlayhead di kelas Anda sendiri.

Anda juga harus memberi tahu SDK saat konten telah selesai diputar sehingga menampilkan iklan post-roll. Hal ini dilakukan dengan memanggil contentComplete di IMAAdsLoader, menggunakan AVPlayerItemDidPlayToEndTimeNotification.

ViewController.m

Objective-C

...

@interface ViewController ()
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

...

- (void)setupContentPlayer {
  // Create a content video player.
  NSURL *contentURL = [NSURL URLWithString:kContentURLString];
  AVPlayer *player = [AVPlayer playerWithURL:contentURL];
  self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
  self.contentPlayerViewController.player = player;
  self.contentPlayerViewController.view.frame = self.view.bounds;
  self.contentPlayhead =
      [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayerViewController.player];

  // Track end of content.
  AVPlayerItem *contentPlayerItem = self.contentPlayerViewController.player.currentItem;
  [NSNotificationCenter.defaultCenter addObserver:self
                                         selector:@selector(contentDidFinishPlaying:)
                                             name:AVPlayerItemDidPlayToEndTimeNotification
                                           object:contentPlayerItem];

  // Attach content video player to view hierarchy.
  [self showContentPlayer];
}

...

- (void)contentDidFinishPlaying:(NSNotification *)notification {}

- (void)dealloc {
  [NSNotificationCenter.defaultCenter removeObserver:self];
}

@end

Swift

...

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

  deinit {
    NotificationCenter.default.removeObserver(self)
  }

...

  func setUpContentPlayer() {
    // Load AVPlayer with path to your content.
    let contentURL! = URL(string: ViewController.ContentURLString)
    let player = AVPlayer(url: contentURL)
    playerViewController = AVPlayerViewController()
    playerViewController.player = player

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

    showContentPlayer()
  }

...

  @objc func contentDidFinishPlaying(_ notification: Notification) {
    adsLoader.contentComplete()
  }
}

6. Melakukan inisialisasi loader iklan dan membuat permintaan iklan

Untuk meminta kumpulan iklan, Anda perlu membuat instance IMAAdsLoader. Loader ini dapat digunakan untuk memproses objek IMAAdsRequest yang terkait dengan URL tag iklan yang ditentukan.

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

ViewController.m

Objective-C

...

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
NSString *const kAdTagURLString = @"https://pubads.g.doubleclick.net/gampad/ads?"
    @"iu=/21775744923/external/vmap_ad_samples&sz=640x480&"
    @"cust_params=sample_ar%3Dpremidpostlongpod&"
    @"ciu_szs=300x250&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&"
    @"env=vp&impl=s&cmsid=496&vid=short_onecue&correlator=";

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

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

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

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

- (void)requestAds {
  // Pass the main view as the container for ad display.
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view];
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
                                                adDisplayContainer:adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}

...

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Notify the SDK that the postrolls should be played.
  [self.adsLoader contentComplete];
}

...

@end

Swift

...

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"
  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&impl=s&correlator="

  var adsLoader: IMAAdsLoader!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

...

  override func viewDidLoad() {
    super.viewDidLoad()
    self.view.backgroundColor = UIColor.black;
    setUpContentPlayer()
    setUpAdsLoader()
  }

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

...

  func setUpAdsLoader() {
    adsLoader = IMAAdsLoader(settings: nil)
  }

  func requestAds() {
    // Create ad display container for ad rendering.
    let adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view)
    // Create an ad request with your ad tag, display container, and optional user context.
    let request = IMAAdsRequest(
        adTagUrl: ViewController.AdTagURLString,
        adDisplayContainer: adDisplayContainer,
        contentPlayhead: contentPlayhead,
        userContext: nil)

    adsLoader.requestAds(with: request)
  }

  @objc func contentDidFinishPlaying(_ notification: Notification) {
    adsLoader.contentComplete()
  }
}

7. Menyiapkan delegasi loader iklan

Pada peristiwa pemuatan yang berhasil, IMAAdsLoader akan memanggil adsLoadedWithData dari delegasi yang ditetapkan, dengan meneruskan instance IMAAdsManager ke sini. Anda selanjutnya dapat melakukan inisialisasi pengelola iklan, yang memuat tiap iklan, seperti yang ditentukan dengan respons terhadap URL tag iklan.

Selain itu, pastikan untuk menangani error yang mungkin terjadi selama pemuatan {i>checkout<i}. Jika iklan tidak dimuat, pastikan pemutaran media dilanjutkan, tanpa iklan agar tidak mengganggu pengalaman pengguna.

ViewController.m

Objective-C

...

@interface ViewController () <IMAAdsLoaderDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

...

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

...

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to the ads manager loaded for this request.
  self.adsManager = adsLoadedData.adsManager;
  [self.adsManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayerViewController.player play];
}

@end

Swift

...

class ViewController: UIViewController, IMAAdsLoaderDelegate {

...

  var adsLoader: IMAAdsLoader!
  var adsManager: IMAAdsManager!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

...

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

...

  // MARK: - IMAAdsLoaderDelegate

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

  func adsLoader(_ loader: IMAAdsLoader!, failedWith adErrorData: IMAAdLoadingErrorData!) {
    print("Error loading ads: " + adErrorData.adError.message)
    showContentPlayer()
    playerViewController.player?.play()
  }
}

8. Menyiapkan delegasi pengelola iklan

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

Memulai pemutaran

Ada banyak peristiwa yang dapat ditangani dengan metode didReceiveAdEvent, tetapi untuk contoh dasar ini, cukup proses peristiwa LOADED untuk memberi tahu iklan untuk memulai pemutaran konten dan iklan.

ViewController.m

Objective-C

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>

...

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to the ads manager loaded for this request.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  [self.adsManager initializeWithAdsRenderingSettings:nil];
}

...

#pragma mark - IMAAdsManagerDelegate

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // Play each ad once it has loaded.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}

...

Swift

...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {

...

  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    // Grab the instance of the IMAAdsManager and set yourself as the delegate.
    adsManager = adsLoadedData.adsManager
    adsManager.delegate = self
    adsManager.initialize(with: nil)
  }

...

  // MARK: - IMAAdsManagerDelegate

  func adsManager(_ adsManager: IMAAdsManager!, didReceive event: IMAAdEvent!) {
    // Play each ad once it has been loaded
    if event.type == IMAAdEventType.LOADED {
      adsManager.start()
    }
  }

...

Menangani error

Menambahkan juga pengendali untuk error iklan. Jika terjadi error, seperti pada contoh melanjutkan pemutaran konten.

ViewController.m

Objective-C


...

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing content.
  NSLog(@"AdsManager error: %@", error.message);
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}
@end

Swift

...

  func adsManager(_ adsManager: IMAAdsManager!, didReceive error: IMAAdError!) {
    // Fall back to playing content
    print("AdsManager error: " + error.message)
    showContentPlayer()
    playerViewController.player?.play()
  }

Memicu peristiwa putar dan jeda

Dua metode delegasi terakhir yang perlu Anda implementasikan digunakan untuk memicu pemutaran dan menjeda peristiwa di konten video yang mendasarinya, jika diminta oleh IMA SDK. Memicu jeda dan putar saat diminta akan mencegah pengguna kehilangan bagian konten video saat iklan ditampilkan.

ViewController.m

Objective-C

...

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // Pause the content for the SDK to play ads.
  [self.contentPlayerViewController.player pause];
  [self hideContentPlayer];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // Resume the content since the SDK is done playing ads (at least for now).
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}

@end

Swift

...

  func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager!) {
    // Pause the content for the SDK to play ads.
    playerViewController.player?.pause()
    hideContentPlayer()
  }

  func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager!) {
    // Resume the content since the SDK is done playing ads (at least for now).
    showContentPlayer()
    playerViewController.player?.play()
  }
}

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

Langkah Berikutnya

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