IMA SDK ช่วยให้ผสานรวมโฆษณามัลติมีเดียเข้ากับเว็บไซต์และแอปได้อย่างง่ายดาย IMA SDK สามารถ ขอโฆษณาจากเซิร์ฟเวอร์โฆษณา ที่รองรับ VAST และจัดการการเล่นโฆษณาในแอปได้ เมื่อใช้ IMA DAI SDK แอปจะส่งคำขอสตรีมสำหรับโฆษณาและเนื้อหาวิดีโอ ไม่ว่าจะเป็นเนื้อหา VOD หรือเนื้อหาสด จากนั้น SDK จะแสดงสตรีมวิดีโอที่รวมกัน เพื่อให้คุณไม่ต้องจัดการการสลับระหว่างโฆษณาและวิดีโอเนื้อหา ภายในแอป
เลือกโซลูชัน DAI ที่คุณสนใจ
DAI แบบบริการเต็มรูปแบบ
คู่มือนี้แสดงวิธีผสานรวม IMA DAI SDK เข้ากับแอปวิดีโอเพลเยอร์อย่างง่าย หากต้องการดูหรือทำตามตัวอย่างการผสานรวมที่เสร็จสมบูรณ์แล้ว ให้ดาวน์โหลด BasicExample จาก GitHub
ภาพรวม IMA DAI
การติดตั้งใช้งาน IMA DAI มีองค์ประกอบ SDK หลัก 3 อย่างดังที่แสดงในคำแนะนำนี้
IMAAdDisplayContainer
: ออบเจ็กต์คอนเทนเนอร์ที่อยู่เหนือองค์ประกอบการเล่นวิดีโอและมีองค์ประกอบ UI ของโฆษณาIMAAdsLoader
: ออบเจ็กต์ที่ขอสตรีมและจัดการเหตุการณ์ที่ทริกเกอร์โดยออบเจ็กต์การตอบกลับคำขอสตรีม คุณควรสร้างอินสแตนซ์ของ AdsLoader เพียงรายการเดียว ซึ่งสามารถนำกลับมาใช้ใหม่ได้ตลอดอายุการใช้งานของแอปพลิเคชันIMAStreamRequest
– either aIMAVODStreamRequest
or aIMALiveStreamRequest
: ออบเจ็กต์ที่กำหนดคำขอสตรีม คำขอสตรีมอาจเป็นคำขอสำหรับวิดีโอออนดีมานด์หรือไลฟ์สด คำขอไลฟ์สดจะระบุคีย์เนื้อหา ส่วนคำขอ VOD จะระบุรหัส CMS และรหัสวิดีโอ คำขอทั้ง 2 ประเภทอาจมีคีย์ API ที่จำเป็นต่อการเข้าถึงสตรีมที่ระบุ และรหัสเครือข่าย Google Ad Manager สำหรับ IMA SDK เพื่อจัดการตัวระบุโฆษณาตามที่ระบุในการตั้งค่า Google Ad ManagerIMAStreamManager
: ออบเจ็กต์ที่จัดการสตรีมการแทรกโฆษณาแบบไดนามิกและการโต้ตอบกับแบ็กเอนด์ DAI นอกจากนี้ ตัวจัดการสตรีมยังจัดการการติดตาม Ping และส่งต่อเหตุการณ์สตรีมและโฆษณาไปยัง ผู้เผยแพร่โฆษณาด้วย
ข้อกำหนดเบื้องต้น
ก่อนเริ่มต้น คุณต้องมีสิ่งต่อไปนี้
- Xcode 13 ขึ้นไป
- CocoaPods (แนะนำ), Swift Package Manager หรือสำเนาที่ดาวน์โหลดของ IMA DAI SDK สำหรับ tvOS
สร้างโปรเจ็กต์ Xcode ใหม่
ใน Xcode ให้สร้างโปรเจ็กต์ tvOS ใหม่โดยใช้ Objective-C ใช้ BasicExample เป็น ชื่อโปรเจ็กต์
เพิ่ม IMA DAI SDK ลงในโปรเจ็กต์ Xcode
ใช้วิธีใดวิธีหนึ่งต่อไปนี้เพื่อติดตั้ง IMA DAI SDK
ติดตั้ง SDK โดยใช้ CocoaPods (แนะนำ)
CocoaPods เป็นโปรแกรมจัดการทรัพยากร Dependency สำหรับโปรเจ็กต์ Xcode และเป็นวิธีที่แนะนำในการติดตั้ง IMA DAI SDK ดูข้อมูลเพิ่มเติมเกี่ยวกับการติดตั้งหรือการใช้ CocoaPods ได้ที่เอกสารประกอบของ CocoaPods เมื่อติดตั้ง CocoaPods แล้ว ให้ใช้วิธีการต่อไปนี้เพื่อติดตั้ง IMA DAI SDK
ในไดเรกทอรีเดียวกับไฟล์ BasicExample.xcodeproj ให้สร้างไฟล์ข้อความ ชื่อ Podfile แล้วเพิ่มการกำหนดค่าต่อไปนี้
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '14' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.15.1' end
จากไดเรกทอรีที่มี Podfile ให้เรียกใช้คำสั่งต่อไปนี้
pod install --repo-update`
ยืนยันว่าติดตั้งสำเร็จโดยเปิดไฟล์ BasicExample.xcworkspace แล้วตรวจสอบว่ามีโปรเจ็กต์ 2 รายการ ได้แก่ BasicExample และ Pods (ทรัพยากร Dependency ที่ติดตั้งโดย CocoaPods)
ติดตั้ง SDK โดยใช้ Swift Package Manager
Interactive Media Ads SDK รองรับ Swift Package Manager ตั้งแต่เวอร์ชัน 4.8.2 เป็นต้นไป ทำตาม ขั้นตอนต่อไปนี้เพื่อนำเข้าแพ็กเกจ Swift
ใน Xcode ให้ติดตั้งแพ็กเกจ Swift ของ GoogleInteractiveMediaAds โดยไปที่File > Add Packages
ในพรอมต์ที่ปรากฏขึ้น ให้ค้นหาที่เก็บ GitHub ของ GoogleInteractiveMediaAds Swift Package
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
เลือกเวอร์ชันของแพ็กเกจ Swift ของ GoogleInteractiveMediaAds ที่ต้องการใช้ สำหรับโปรเจ็กต์ใหม่ เราขอแนะนำให้ใช้อัปเดตเป็นเวอร์ชันหลักถัดไป
เมื่อดำเนินการเสร็จแล้ว Xcode จะแก้ไขการขึ้นต่อกันของแพ็กเกจและดาวน์โหลดไว้ในเบื้องหลัง ดูรายละเอียดเพิ่มเติมเกี่ยวกับวิธีเพิ่มการอ้างอิงแพ็กเกจได้ที่ บทความของ Apple
การดาวน์โหลดและติดตั้ง SDK ด้วยตนเอง
หากไม่ต้องการใช้ Swift Package Manager หรือ CocoaPods คุณสามารถดาวน์โหลด IMA DAI SDK และเพิ่มลงในโปรเจ็กต์ด้วยตนเองได้
สร้างวิดีโอเพลเยอร์แบบง่าย
ก่อนอื่น ให้ติดตั้งใช้งานวิดีโอเพลเยอร์พื้นฐาน ในตอนแรก โปรแกรมเล่นนี้ไม่ได้ใช้ IMA DAI SDK และไม่มีวิธีการใดๆ ที่จะทริกเกอร์การเล่น
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
นําเข้า SDK และเพิ่ม Stub สําหรับการโต้ตอบ IMA
หลังจากเพิ่ม IMA DAI SDK ลงในโปรเจ็กต์แล้ว ให้นำเข้า SDK และเพิ่ม Stub สำหรับ จุดหลักของการโต้ตอบ 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
ใช้ IMAAdsLoader
จากนั้นสร้างอินสแตนซ์ของ IMAAdsLoader
และแนบมุมมองคอนเทนเนอร์โฆษณากับ
ลำดับชั้นของมุมมอง
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;
}
ส่งคำขอสตรีม
สร้างค่าคงที่ 2-3 รายการเพื่อเก็บข้อมูลสตรีม แล้วใช้ฟังก์ชันคำขอสตรีมเพื่อส่งคำขอ
ViewController.m
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";
@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
networkCode:kNetworkCode
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
// networkCode:kNetworkCode
// adDisplayContainer:adDisplayContainer
// videoDisplay:videoDisplay];
[self.adsLoader requestStreamWithRequest:request];
}
จัดการเหตุการณ์สตรีม
IMAAdsLoader
และ IMAStreamManager
จะทริกเกอร์เหตุการณ์ที่ใช้เพื่อจัดการ
การเริ่มต้น ข้อผิดพลาด และการเปลี่ยนแปลงสถานะสตรีม เหตุการณ์เหล่านี้จะทริกเกอร์ผ่านโปรโตคอล IMAAdsLoaderDelegate
และ IMAStreamManagerDelegate
รอ
เหตุการณ์โฆษณาที่โหลดแล้วและเริ่มต้นสตรีม หากโฆษณาโหลดไม่สำเร็จ ให้เล่น
สตรีมสำรองแทน
ViewController.m
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";
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
จัดการเหตุการณ์การบันทึกและข้อผิดพลาด
มีเหตุการณ์หลายอย่างที่ตัวแทน Stream Manager จัดการได้ แต่ สำหรับการติดตั้งใช้งานขั้นพื้นฐาน การใช้งานที่สำคัญที่สุดคือการบันทึกเหตุการณ์ เพื่อป้องกันการดำเนินการค้นหาขณะที่โฆษณากำลังเล่น และเพื่อจัดการข้อผิดพลาด
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
เท่านี้ก็เรียบร้อย ตอนนี้คุณขอและแสดงโฆษณาด้วย IMA DAI SDK แล้ว หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับฟีเจอร์ SDK ขั้นสูงอื่นๆ โปรดดูคำแนะนำอื่นๆ หรือตัวอย่างใน GitHub