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
: ออบเจ็กต์ที่ขอสตรีมและจัดการเหตุการณ์ที่ทริกเกอร์โดยออบเจ็กต์การตอบกลับของคำขอสตรีม คุณควรสร้างอินสแตนซ์ของเครื่องมือโหลดโฆษณาเพียงรายการเดียว ซึ่งนํามาใช้ซ้ำได้ตลอดอายุการใช้งานของแอปพลิเคชันIMAStreamRequest
– อาจเป็นIMAVODStreamRequest
หรือIMALiveStreamRequest
: ออบเจ็กต์ที่กำหนดคำขอสตรีม คำขอสตรีมจะเป็นวิดีโอออนดีมานด์หรือแบบสดก็ได้ สตรีม คำขอระบุรหัสเนื้อหา รวมทั้งคีย์ API หรือโทเค็นการตรวจสอบสิทธิ์ และอื่นๆ พารามิเตอร์IMAStreamManager
: ออบเจ็กต์ที่จัดการสตรีมการแทรกโฆษณาแบบไดนามิกและการโต้ตอบกับแบ็กเอนด์ 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.13.0' 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 โดยไปที่ไฟล์ > เพิ่มแพ็กเกจ
ในข้อความแจ้งที่ปรากฏขึ้น ให้ค้นหา GoogleInteractiveMediaAds Swift ที่เก็บแพ็กเกจ GitHub:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
เลือกเวอร์ชันของ GoogleInteractiveMediaAds Swift Package ที่ต้องการใช้ สำหรับมือใหม่ เราขอแนะนำให้ใช้เวอร์ชันล่าสุดถัดไป
เมื่อดำเนินการเสร็จแล้ว Xcode จะจับคู่ข้อมูลและดาวน์โหลดทรัพยากร Dependency ของแพ็กเกจในเบื้องหลัง ดูรายละเอียดเพิ่มเติมเกี่ยวกับวิธีเพิ่มทรัพยากร Dependency ของแพ็กเกจได้ที่ สำหรับ 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 และเพิ่มสแต็บสําหรับการโต้ตอบ IMA
หลังจากที่เพิ่ม IMA DAI SDK ลงในโปรเจ็กต์แล้ว ให้นำเข้า SDK และเพิ่มสตับสำหรับ ประเด็นหลักๆ ในการโต้ตอบกับ 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";
@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
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
// 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 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
จัดการการบันทึกและเหตุการณ์ข้อผิดพลาด
เหตุการณ์หลายรายการที่ตัวแทนผู้จัดการสตรีมจัดการได้ แต่สำหรับการใช้งานขั้นพื้นฐาน การใช้งานที่สำคัญที่สุดคือการบันทึกเหตุการณ์ เพื่อป้องกันการกรอขณะที่โฆษณาเล่นอยู่ และเพื่อจัดการข้อผิดพลาด
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