IMA SDK memudahkan pengintegrasian iklan multimedia ke dalam situs dan aplikasi Anda. IMA SDK dapat minta iklan dari mana pun 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.
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]; }</span> @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.