IMA SDK ช่วยให้คุณผสานรวมโฆษณามัลติมีเดียเข้ากับเว็บไซต์และแอปได้อย่างง่ายดาย IMA SDK สามารถ ขอโฆษณาจาก เซิร์ฟเวอร์โฆษณาที่สอดคล้องกับ VAST และจัดการการเล่นโฆษณาในแอปได้ SDK ฝั่งไคลเอ็นต์ IMA ช่วยให้คุณควบคุมการเล่นวิดีโอเนื้อหาได้ ขณะที่ SDK จะจัดการการเล่นโฆษณา โฆษณาจะเล่นในโปรแกรมเล่นวิดีโอแยกต่างหาก ซึ่งวางอยู่เหนือโปรแกรมเล่นวิดีโอเนื้อหาของแอป
คู่มือนี้แสดงวิธีผสานรวม IMA SDK เข้ากับแอปโปรแกรมเล่นวิดีโอ หากต้องการดูหรือทำตามการผสานรวมตัวอย่างที่เสร็จสมบูรณ์แล้ว ให้ดาวน์โหลด BasicExample จาก GitHub
ภาพรวมฝั่งไคลเอ็นต์ IMA
การติดตั้งใช้งานฝั่งไคลเอ็นต์ IMA เกี่ยวข้องกับคอมโพเนนต์ SDK หลัก 4 รายการ คู่มือนี้จะแสดงคอมโพเนนต์ต่อไปนี้
IMAAdDisplayContainer: ออบเจ็กต์คอนเทนเนอร์ที่ระบุตำแหน่งที่ IMA แสดงผลองค์ประกอบ UI ของโฆษณาและวัดการมองเห็นโฆษณา ซึ่งรวมถึง มุมมองแอ็กทีฟ และ การวัดแบบเปิดIMAAdsLoader: ออบเจ็กต์ที่ขอโฆษณาและจัดการเหตุการณ์จากการตอบสนองต่อคำขอโฆษณา คุณควรสร้างอินสแตนซ์ของตัวโหลดโฆษณาเพียงรายการเดียว ซึ่งสามารถนำกลับมาใช้ใหม่ได้ตลอดอายุการใช้งานของแอปพลิเคชันIMAAdsRequest: ออบเจ็กต์ที่กำหนดคำขอโฆษณา คำขอโฆษณาระบุ URL สำหรับแท็กโฆษณา VAST รวมถึงพารามิเตอร์เพิ่มเติม เช่น ขนาดโฆษณาIMAAdsManager: ออบเจ็กต์ที่มีการตอบสนองต่อคำขอโฆษณา ควบคุมการเล่นโฆษณา และรับฟังเหตุการณ์โฆษณาที่ SDK เริ่มทำงาน
ข้อกำหนดเบื้องต้น
ก่อนเริ่มต้น คุณต้องมีสิ่งต่อไปนี้
- Xcode 13 ขึ้นไป
- วิธีติดตั้ง IMA SDK
- แนะนำ: Swift Package Manager
- CocoaPods
- สำเนาที่ดาวน์โหลดของ IMA SDK สำหรับ tvOS
1. สร้างโปรเจ็กต์ Xcode ใหม่
สร้างโปรเจ็กต์ tvOS ใหม่ใน Xcode โดยใช้ Objective-C หรือ Swift ใช้ BasicExample เป็นชื่อโปรเจ็กต์
2. เพิ่ม IMA SDK ลงในโปรเจ็กต์ Xcode
หากต้องการติดตั้ง IMA SDK ให้เลือกวิธีที่ต้องการ
แนะนำ: ติดตั้ง IMA SDK โดยใช้ Swift Package Manager
Interactive Media Ads SDK รองรับ Swift Package Manager ตั้งแต่เวอร์ชัน 4.8.2 เป็นต้นไป ทำตามขั้นตอนต่อไปนี้เพื่อนำเข้าแพ็กเกจ Swift
ใน Xcode ให้ติดตั้งแพ็กเกจ IMA SDK Swift โดยไปที่ File > Add Packages...
ในข้อความแจ้งที่ปรากฏขึ้น ให้ค้นหาที่เก็บ IMA SDK Swift Package GitHub ดังนี้
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosเลือกเวอร์ชันของแพ็กเกจ IMA SDK Swift ที่ต้องการใช้ สำหรับโปรเจ็กต์ใหม่ เราขอแนะนำให้ใช้สูงสุดถึงเวอร์ชันหลักถัดไป
เมื่อเสร็จแล้ว Xcode จะแก้ไขการขึ้นต่อกันของแพ็กเกจและดาวน์โหลดไว้ในเบื้องหลัง ดูรายละเอียดเพิ่มเติมเกี่ยวกับวิธีเพิ่มการขึ้นต่อกันของแพ็กเกจได้ในบทความของ Apple
ติดตั้ง IMA SDK โดยใช้ CocoaPods
หากต้องการติดตั้ง IMA SDK ให้ใช้ CocoaPods ดูข้อมูลเพิ่มเติมเกี่ยวกับการติดตั้งหรือการใช้ CocoaPods ได้ใน เอกสารประกอบของ CocoaPods หลังจากติดตั้ง CocoaPods แล้ว ให้ทำดังนี้
สร้างไฟล์ข้อความชื่อ Podfile ในไดเรกทอรีเดียวกับไฟล์ BasicExample.xcodeproj แล้วเพิ่มการกำหนดค่าต่อไปนี้
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '15' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.17.0' endจากไดเรกทอรีที่มี Podfile ให้เรียกใช้
pod install --repo-updateยืนยันว่าการติดตั้งสำเร็จโดยเปิดไฟล์ BasicExample.xcworkspace และยืนยันว่ามี 2 โปรเจ็กต์ ได้แก่ BasicExample และ Pods (การขึ้นต่อกันที่ CocoaPods ติดตั้งไว้)
ดาวน์โหลดและติดตั้ง IMA SDK ด้วยตนเอง
หากไม่ต้องการใช้ Swift Package Manager ให้ดาวน์โหลดและเพิ่ม IMA SDK ลงในโปรเจ็กต์ด้วยตนเอง
3. นำเข้า IMA SDK
เพิ่มเฟรมเวิร์ก IMA โดยใช้คำสั่งนำเข้า
Objective-C
#import "ViewController.h"
#import <AVKit/AVKit.h>
@import GoogleInteractiveMediaAds;
Swift
import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
4. สร้างโปรแกรมเล่นวิดีโอและผสานรวม IMA SDK
ตัวอย่างต่อไปนี้แสดงการเริ่มต้น 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()
}
ในตัวอย่างนี้ viewDidLoad() จะเริ่มต้น IMAAdsLoader และ viewDidAppear() จะขอโฆษณาเมื่อมุมมองปรากฏขึ้น เมธอดตัวช่วย showContentPlayer() และ hideContentPlayer() จะสลับการแสดงเนื้อหาในระหว่างการเล่นโฆษณา
ตัวอย่างนี้ใช้ตัวแปรค่าคงที่ adTagURLString เพื่อกำหนดแท็กโฆษณา VAST สำหรับคำขอโฆษณา และใช้คอมโพเนนต์ต่อไปนี้เพื่อจัดการ IMA SDK
adsLoader: จัดการคำขอและการตอบสนองต่อคำขอโฆษณา เราขอแนะนำให้ใช้เพียงอินสแตนซ์เดียวตลอดอายุการใช้งานของแอปadDisplayContainer: ระบุมุมมองสำหรับการแสดงโฆษณาadsManager: จัดการการเล่นโฆษณาและรับฟังเหตุการณ์โฆษณาcontentPlayhead: ติดตามความคืบหน้าของเนื้อหาเพื่อเริ่มช่วงพักโฆษณาตอนกลางadBreakActive: ระบุว่าช่วงพักโฆษณากำลังเล่นอยู่หรือไม่ เพื่อป้องกันไม่ให้ผู้ใช้ข้ามโฆษณา
5. ติดตั้งใช้งานตัวติดตาม Playhead ของเนื้อหาและ Observer ของการสิ้นสุดสตรีม
หากต้องการเล่นโฆษณาตอนกลาง IMA SDK ต้องติดตามตำแหน่งปัจจุบันของเนื้อหาวิดีโอ หากต้องการส่งตำแหน่งปัจจุบันไปยัง IMA ให้สร้างคลาสที่ติดตั้งใช้งาน IMAContentPlayhead หากคุณใช้ AVPlayer ดังที่ตัวอย่างนี้
แสดง IMA SDK จะมีคลาส IMAAVPlayerContentPlayhead เพื่อส่งข้อมูลตำแหน่งปัจจุบัน
ให้คุณ หากไม่ได้ใช้ AVPlayer ให้ติดตั้งใช้งาน IMAContentPlayhead ในคลาสของคุณเอง
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()
}
ตั้งค่า Listener เพื่อเรียก contentComplete ใน IMAAdsLoader เมื่อเนื้อหาสิ้นสุด โดยใช้ AVPlayerItemDidPlayToEndTimeNotification การเรียก contentComplete จะช่วยให้ IMA SDK ทราบว่าเนื้อหาของคุณเล่นจบแล้วเมื่อใด เพื่อแสดงโฆษณาตอนท้าย
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. เริ่มต้นตัวโหลดโฆษณาและส่งคำขอโฆษณา
หากต้องการขอโฆษณาชุดหนึ่ง ให้สร้างอินสแตนซ์ IMAAdsLoader
ตัวโหลดนี้จะประมวลผลออบเจ็กต์ IMAAdsRequest ที่เชื่อมโยงกับ URL แท็กโฆษณาที่ระบุ
แนวทางปฏิบัติแนะนำคือให้เก็บอินสแตนซ์ IMAAdsLoader ไว้เพียงอินสแตนซ์เดียวตลอดอายุการใช้งานของแอป หากต้องการส่งคำขอโฆษณาเพิ่มเติม ให้สร้างออบเจ็กต์ IMAAdsRequest ใหม่ แต่ใช้ IMAAdsLoader เดิม ดูข้อมูลเพิ่มเติมได้ที่
คำถามที่พบบ่อยเกี่ยวกับ 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. ตั้งค่าผู้รับมอบสิทธิ์ของตัวโหลดโฆษณา
ในเหตุการณ์การโหลดสำเร็จ IMAAdsLoader จะเรียกใช้เมธอด adsLoadedWithData ของผู้รับมอบสิทธิ์ที่กำหนด โดยส่งอินสแตนซ์ IMAAdsManager ไปด้วย
หลังจากมีอินสแตนซ์ IMAAdsManager แล้ว ให้เริ่มต้นตัวจัดการโฆษณา ซึ่งจะโหลดโฆษณาแต่ละรายการตามการตอบสนองของ URL แท็กโฆษณา
สำหรับเหตุการณ์การโหลดไม่สำเร็จ ให้ตั้งค่าผู้รับมอบสิทธิ์ IMAAdsLoader เพื่อจัดการข้อผิดพลาดที่เกิดขึ้นในระหว่างกระบวนการโหลด หากโฆษณาไม่โหลด ให้ตรวจสอบว่าการเล่นสื่อยังคงดำเนินต่อไปโดยไม่มีโฆษณา เพื่อให้ผู้ใช้ดูเนื้อหาสื่อได้
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. ตั้งค่าผู้รับมอบสิทธิ์ของตัวจัดการโฆษณา
สุดท้ายนี้ ตัวจัดการโฆษณาต้องมีผู้รับมอบสิทธิ์ของตัวเองเพื่อจัดการเหตุการณ์และการเปลี่ยนแปลงสถานะ IMAAdManagerDelegate มีเมธอดสำหรับจัดการเหตุการณ์และข้อผิดพลาดของโฆษณา รวมถึงเมธอดสำหรับเริ่มและหยุดเนื้อหาวิดีโอชั่วคราว
การเริ่มเล่น
เมธอด didReceiveAdEvent จะจัดการเหตุการณ์ IMAAdEvent ทั้งหมด
สำหรับตัวอย่างพื้นฐานนี้ ให้รับฟังเหตุการณ์ LOADED เพื่อบอกให้ตัวจัดการโฆษณาเริ่มเล่นเนื้อหาและโฆษณา IMA SDK จะเริ่มเหตุการณ์ ICON_FALLBACK_IMAGE_CLOSED เมื่อผู้ใช้ปิดกล่องโต้ตอบรูปภาพสำรองของไอคอนหลังจากแตะไอคอน หลังจากดำเนินการนี้แล้ว การเล่นโฆษณาจะกลับมาทำงานต่อ
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
}
}
การจัดการข้อผิดพลาด
เพิ่มตัวแฮนเดิลสำหรับข้อผิดพลาดของโฆษณาด้วย หากเกิดข้อผิดพลาด ให้เล่นเนื้อหาต่อ ดังเช่นในขั้นตอนก่อนหน้า
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()
}
การเริ่มเหตุการณ์เล่นและหยุดชั่วคราว
เมธอดผู้รับมอบสิทธิ์ 2 รายการสุดท้ายที่คุณติดตั้งใช้งานจะเริ่มเหตุการณ์เล่นและหยุดชั่วคราวในเนื้อหาวิดีโอพื้นฐานเมื่อ IMA SDK ขอ การเริ่มเหตุการณ์หยุดชั่วคราวและเล่นเมื่อ IMA SDK ขอจะช่วยไม่ให้ผู้ใช้พลาดส่วนต่างๆ ของเนื้อหาวิดีโอเมื่อโฆษณาแสดง
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()
}
เท่านี้ก็เรียบร้อย ตอนนี้คุณขอและแสดงโฆษณาด้วย IMA SDK ได้แล้ว หากต้องการดูข้อมูล เกี่ยวกับฟีเจอร์เพิ่มเติมของ SDK โปรดดูคู่มืออื่นๆ หรือ ตัวอย่างใน GitHub
ขั้นตอนถัดไป
หากต้องการเพิ่มรายได้จากโฆษณาในแพลตฟอร์ม tvOS ให้ขอสิทธิ์ App Transparency and Tracking เพื่อใช้ IDFA