IMA SDK memudahkan integrasi iklan multimedia ke dalam 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 SDK sisi klien, Anda tetap dapat mengontrol pemutaran video konten, sementara SDK menangani pemutaran iklan. Iklan diputar di a pemutar video terpisah yang ditempatkan di atas pemutar video konten aplikasi.
Panduan ini menunjukkan cara mengintegrasikan IMA SDK ke dalam aplikasi pemutar video. Untuk melihat atau mengikuti integrasi contoh yang telah selesai, download BasicExampledari GitHub.
Ringkasan sisi klien IMA
Penerapan sisi klien IMA melibatkan empat komponen SDK utama. Panduan ini menunjukkan komponen-komponen tersebut:
IMAAdDisplayContainer: Objek penampung yang menentukan tempat IMA merender elemen UI iklan dan mengukur visibilitas, termasuk Active View dan Open Measurement.IMAAdsLoader: Objek yang meminta iklan dan menangani peristiwa dari respons permintaan iklan. Anda hanya boleh membuat satu instance loader 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
- Metode untuk menginstal IMA SDK:
- Direkomendasikan: Swift Package Manager
- CocoaPods
- Salinan download 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
Untuk menginstal IMA SDK, pilih metode yang diinginkan.
Direkomendasikan: Menginstal IMA SDK menggunakan Swift Package Manager
Interactive Media Ads SDK mendukung Swift Package Manager mulai versi 4.8.2. Ikuti langkah-langkah berikut untuk mengimpor paket Swift.
Di Xcode, instal IMA SDK Swift Package dengan membuka File > Add Packages....
Pada perintah yang muncul, telusuri repositori GitHub IMA SDK Swift Package:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosPilih versi IMA SDK Swift Package 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.
Menginstal IMA SDK menggunakan CocoaPods
Untuk menginstal IMA SDK, gunakan CocoaPods. Untuk mengetahui informasi selengkapnya tentang cara menginstal atau menggunakan CocoaPods, lihat dokumentasi CocoaPods. Setelah menginstal CocoaPods, lakukan hal berikut:
Di direktori yang sama dengan file BasicExample.xcodeproj Anda, buat file teks bernama Podfile, lalu tambahkan konfigurasi berikut:
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '15' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0' endDari direktori yang berisi Podfile, jalankan
pod install --repo-updatePastikan penginstalan berhasil dengan membuka file BasicExample.xcworkspace dan mengonfirmasi bahwa file tersebut berisi dua project: BasicExample dan Pods (dependensi yang diinstal oleh CocoaPods).
Mendownload dan menginstal IMA SDK secara manual
Jika tidak ingin menggunakan Swift Package Manager, download dan tambahkan IMA SDK ke project Anda secara manual.
3. Mengimpor IMA SDK
Tambahkan framework IMA menggunakan pernyataan impor.
Objective-C
#import "ViewController.h"
#import <AVKit/AVKit.h>
@import GoogleInteractiveMediaAds;
Swift
import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
4. Membuat pemutar video dan mengintegrasikan IMA SDK
Contoh berikut melakukan inisialisasi IMA SDK:
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&cmsid=496&vid=short_onecue&correlator=";
@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
[self setupAdsLoader];
[self setupContentPlayer];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self requestAds];
}
// 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 resume events from the
// remote and play content underneath the ad.
[self.contentPlayerViewController willMoveToParentViewController:nil];
[self.contentPlayerViewController.view removeFromSuperview];
[self.contentPlayerViewController removeFromParentViewController];
}
Swift
class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
static let contentURLString =
"https://devstreaming-cdn.apple.com/videos/streaming/examples/"
+ "img_bipbop_adv_example_fmp4/master.m3u8"
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="
var adsLoader: IMAAdsLoader!
var adDisplayContainer: IMAAdDisplayContainer!
var adsManager: IMAAdsManager!
var contentPlayhead: IMAAVPlayerContentPlayhead?
var playerViewController: AVPlayerViewController!
var adBreakActive = false
deinit {
NotificationCenter.default.removeObserver(self)
}
override func viewDidLoad() {
super.viewDidLoad()
self.view.backgroundColor = UIColor.black
setUpContentPlayer()
setUpAdsLoader()
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
requestAds()
}
Dalam contoh ini, viewDidLoad() melakukan inisialisasi IMAAdsLoader, dan viewDidAppear() meminta iklan setelah tampilan terlihat. Metode helper showContentPlayer() dan hideContentPlayer() mengalihkan visibilitas konten selama pemutaran iklan.
Contoh ini menggunakan variabel konstanta adTagURLString untuk menentukan tag iklan VAST untuk permintaan iklan, dan komponen berikut untuk mengelola IMA SDK:
adsLoader: Menangani permintaan dan respons iklan. Sebaiknya gunakan satu instance untuk siklus proses aplikasi.adDisplayContainer: Menentukan tampilan untuk merender iklan.adsManager: Mengelola pemutaran iklan dan memproses peristiwa iklan.contentPlayhead: Melacak progres konten untuk memicu jeda iklan mid-roll.adBreakActive: Menunjukkan apakah jeda iklan sedang diputar untuk mencegah pencarian iklan.
5. Menerapkan pelacak playhead konten dan pengamat akhir streaming
Untuk memutar iklan mid-roll, IMA SDK harus melacak posisi konten video Anda saat ini. Untuk meneruskan posisi saat ini ke IMA, buat class yang menerapkan IMAContentPlayhead. Jika Anda menggunakan AVPlayer, seperti yang ditunjukkan contoh
ini, IMA SDK menyediakan class IMAAVPlayerContentPlayhead untuk meneruskan info posisi saat ini
bagi Anda. Jika Anda tidak menggunakan AVPlayer, terapkan IMAContentPlayhead pada class Anda sendiri.
Objective-C
- (void)setupContentPlayer {
// Create a content video player. Create a playhead to track content progress so the SDK knows
// when to play ads in a VMAP playlist.
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];
}
Swift
func setUpContentPlayer() {
// Load AVPlayer with path to our content.
let contentURL = URL(string: ViewController.contentURLString)!
let player = AVPlayer(url: contentURL)
playerViewController = AVPlayerViewController()
playerViewController.player = player
// Set up our 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()
}
Siapkan pemroses untuk memanggil contentComplete di IMAAdsLoader saat konten Anda berakhir, menggunakan AVPlayerItemDidPlayToEndTimeNotification. Dengan memanggil contentComplete, IMA SDK akan mengetahui kapan konten Anda selesai diputar untuk menampilkan iklan post-roll.
Objective-C
- (void)contentDidFinishPlaying:(NSNotification *)notification {
// Notify the SDK that the postrolls should be played.
[self.adsLoader contentComplete];
}
- (void)dealloc {
[[NSNotificationCenter defaultCenter] removeObserver:self];
}
Swift
@objc func contentDidFinishPlaying(_ notification: Notification) {
adsLoader.contentComplete()
}
6. Melakukan inisialisasi loader iklan dan membuat permintaan iklan
Untuk meminta kumpulan iklan, buat instance IMAAdsLoader.
Loader ini 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] init];
self.adsLoader.delegate = self;
}
- (void)requestAds {
// Pass the main view as the container for ad display.
self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view
viewController:self];
IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
adDisplayContainer:self.adDisplayContainer
contentPlayhead:self.contentPlayhead
userContext:nil];
[self.adsLoader requestAdsWithRequest:request];
}
Swift
func setUpAdsLoader() {
adsLoader = IMAAdsLoader(settings: nil)
adsLoader.delegate = self
}
func requestAds() {
// Create ad display container for ad rendering.
adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view, viewController: self)
// Create an ad request with our ad tag, display container, and optional user context.
let request = IMAAdsRequest(
adTagUrl: ViewController.adTagURLString,
adDisplayContainer: adDisplayContainer,
contentPlayhead: contentPlayhead,
userContext: nil)
adsLoader.requestAds(with: request)
}
7. Menyiapkan delegasi loader iklan
Pada peristiwa pemuatan yang berhasil, IMAAdsLoader akan memanggil metode adsLoadedWithData dari delegasi yang ditetapkan, dan meneruskan instance IMAAdsManager.
Setelah memiliki instance IMAAdsManager, lakukan inisialisasi pengelola iklan, yang memuat iklan individual berdasarkan respons URL tag iklan.
Untuk peristiwa pemuatan yang tidak berhasil, siapkan delegasi IMAAdsLoader untuk menangani error yang terjadi selama proses pemuatan. Jika iklan tidak dimuat, pastikan pemutaran media berlanjut tanpa iklan agar pengguna dapat melihat konten media.
Objective-C
#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.delegate = self;
[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];
}
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
adsManager.initialize(with: nil)
}
func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
print("Error loading ads: \(adErrorData.adError.message ?? "No error message available.")")
showContentPlayer()
playerViewController.player?.play()
}
8. Menyiapkan delegasi pengelola iklan
Terakhir, untuk mengelola peristiwa dan perubahan status, pengelola iklan memerlukan delegasinya sendiri. IMAAdManagerDelegate memiliki metode untuk menangani peristiwa dan error iklan, serta metode untuk memicu pemutaran dan jeda pada konten video Anda.
Memulai pemutaran
Metode didReceiveAdEvent menangani semua peristiwa IMAAdEvent.
Untuk contoh dasar ini, proses peristiwa LOADED untuk memberi tahu pengelola iklan agar memulai pemutaran konten dan iklan. IMA SDK memicu peristiwa ICON_FALLBACK_IMAGE_CLOSED saat pengguna menutup dialog penggantian ikon setelah mengetuk ikon. Setelah tindakan ini, pemutaran iklan akan dilanjutkan.
Objective-C
#pragma mark - IMAAdsManagerDelegate
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
switch (event.type) {
case kIMAAdEvent_LOADED: {
// Play each ad once it has loaded.
[adsManager start];
break;
}
case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
// Resume ad after user has closed dialog.
[adsManager resume];
break;
}
default:
break;
}
}
Swift
func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
switch event.type {
case IMAAdEventType.LOADED:
// Play each ad once it has been loaded.
adsManager.start()
case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
// Resume playback after the user has closed the dialog.
adsManager.resume()
default:
break
}
}
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 {
// Fall back to playing content.
NSLog(@"AdsManager error: %@", error.message);
[self showContentPlayer];
[self.contentPlayerViewController.player play];
}
Swift
func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
// Fall back to playing content
print("AdsManager error: \(error.message ?? "No error message available.")")
showContentPlayer()
playerViewController.player?.play()
}
Memicu peristiwa putar dan jeda
Dua metode delegasi terakhir yang Anda terapkan akan memicu peristiwa putar dan jeda pada konten video yang mendasarinya saat IMA SDK memintanya. Memicu jeda dan putar saat IMA SDK memintanya akan mencegah pengguna melewatkan bagian konten video saat iklan ditampilkan.
Objective-C
- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
// Pause the content for the SDK to play ads.
[self.contentPlayerViewController.player pause];
[self hideContentPlayer];
// Trigger an update to send focus to the ad display container.
self.adBreakActive = YES;
[self setNeedsFocusUpdate];
}
- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
// Resume the content since the SDK is done playing ads (at least for now).
[self showContentPlayer];
[self.contentPlayerViewController.player play];
// Trigger an update to send focus to the content player.
self.adBreakActive = NO;
[self setNeedsFocusUpdate];
}
Swift
func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
// Pause the content for the SDK to play ads.
playerViewController.player?.pause()
hideContentPlayer()
// Trigger an update to send focus to the ad display container.
adBreakActive = true
setNeedsFocusUpdate()
}
func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
// Resume the content since the SDK is done playing ads (at least for now).
showContentPlayer()
playerViewController.player?.play()
// Trigger an update to send focus to the content player.
adBreakActive = false
setNeedsFocusUpdate()
}
Selesai! Anda kini meminta dan menampilkan iklan dengan IMA SDK. Untuk mempelajari fitur SDK tambahan, lihat panduan lain atau contoh di GitHub.
Langkah Berikutnya
Untuk memaksimalkan pendapatan iklan di platform tvOS, minta izin App Transparency and Tracking untuk menggunakan IDFA.