SDK IMA giúp bạn dễ dàng tích hợp quảng cáo đa phương tiện vào trang web và ứng dụng của mình. SDK IMA có thể yêu cầu quảng cáo từ bất kỳ máy chủ quảng cáo tuân thủ VAST nào và quản lý việc phát quảng cáo trong ứng dụng của bạn. Với SDK phía máy khách IMA, bạn vẫn có quyền kiểm soát việc phát video nội dung, trong khi SDK xử lý việc phát quảng cáo. Quảng cáo phát trong một trình phát video riêng biệt nằm phía trên trình phát video nội dung của ứng dụng.
Hướng dẫn này minh hoạ cách tích hợp IMA SDK vào một ứng dụng trình phát video. Nếu bạn muốn xem hoặc làm theo một mẫu tích hợp hoàn chỉnh, hãy tải BasicExample xuống từ GitHub.
Tổng quan về phía máy khách IMA
Việc triển khai phía máy khách IMA bao gồm 4 thành phần SDK chính được minh hoạ trong hướng dẫn này:
IMAAdDisplayContainer: Một đối tượng vùng chứa chỉ định vị trí mà IMA hiển thị các phần tử giao diện người dùng của quảng cáo và đo lường khả năng xem, bao gồm cả Chế độ xem đang kích hoạt và Đo lường mở.IMAAdsLoader: Một đối tượng yêu cầu quảng cáo và xử lý các sự kiện từ phản hồi yêu cầu quảng cáo. Bạn chỉ nên tạo một trình tải quảng cáo và có thể sử dụng lại trình tải này trong suốt thời gian hoạt động của ứng dụng.IMAAdsRequest: Một đối tượng xác định yêu cầu quảng cáo. Các yêu cầu về quảng cáo chỉ định URL cho thẻ quảng cáo VAST, cũng như các thông số bổ sung, chẳng hạn như kích thước quảng cáo.IMAAdsManager: Một đối tượng chứa phản hồi cho yêu cầu quảng cáo, kiểm soát việc phát quảng cáo và theo dõi các sự kiện quảng cáo do SDK kích hoạt.
Điều kiện tiên quyết
Trước khi bắt đầu, bạn cần có những thông tin sau:
- Xcode 13 trở lên
- Trình quản lý gói Swift, CocoaPods hoặc bản sao đã tải xuống của SDK IMA dành cho tvOS
1. Tạo một dự án Xcode mới
Trong Xcode, hãy tạo một dự án tvOS mới bằng Objective-C hoặc Swift. Sử dụng BasicExample làm tên dự án.
2. Thêm IMA SDK vào dự án Xcode
Cài đặt IMA SDK bằng Trình quản lý gói Swift
SDK Quảng cáo tương tác trên phương tiện truyền thông hỗ trợ Trình quản lý gói Swift kể từ phiên bản 4.8.2. Hãy làm theo các bước sau để nhập gói Swift.
Trong Xcode, hãy cài đặt Gói Swift SDK IMA bằng cách chuyển đến File (Tệp) > Add Packages (Thêm gói)....
Trong lời nhắc xuất hiện, hãy tìm kiếm kho lưu trữ GitHub cho Gói Swift SDK IMA:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosChọn phiên bản của Gói Swift IMA SDK mà bạn muốn sử dụng. Đối với các dự án mới, bạn nên sử dụng Phiên bản lớn tiếp theo.
Sau khi bạn hoàn tất, Xcode sẽ phân giải các phần phụ thuộc của gói và tải các phần phụ thuộc đó xuống ở chế độ nền. Để biết thêm thông tin chi tiết về cách thêm các phần phụ thuộc của gói, hãy xem bài viết của Apple.
Cài đặt IMA SDK bằng CocoaPods
Để cài đặt IMA SDK, hãy sử dụng CocoaPods. Để biết thêm thông tin về cách cài đặt hoặc sử dụng CocoaPods, hãy xem tài liệu về CocoaPods. Sau khi bạn cài đặt CocoaPods, hãy làm như sau:
Trong cùng thư mục với tệp BasicExample.xcodeproj, hãy tạo một tệp văn bản có tên là Podfile rồi thêm cấu hình sau:
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '15' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0' endTừ thư mục chứa Podfile, hãy chạy
pod install --repo-updateXác minh rằng quá trình cài đặt đã thành công bằng cách mở tệp BasicExample.xcworkspace và xác nhận rằng tệp này chứa 2 dự án: BasicExample và Pods (các phần phụ thuộc do CocoaPods cài đặt).
Tải và cài đặt IMA SDK theo cách thủ công
Nếu không muốn sử dụng CocoaPods, bạn có thể tải IMA SDK xuống và thêm SDK này vào dự án theo cách thủ công.
3. Nhập IMA SDK
Thêm khung IMA bằng câu lệnh nhập.
Objective-C
#import "ViewController.h"
#import <AVKit/AVKit.h>
@import GoogleInteractiveMediaAds;
Swift
import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
4. Tạo trình phát video và tích hợp SDK IMA
Ví dụ sau đây khởi chạy 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()
}
Trong ví dụ này, viewDidLoad() khởi tạo IMAAdsLoader và viewDidAppear() yêu cầu quảng cáo khi khung hiển thị xuất hiện. Các phương thức hỗ trợ showContentPlayer() và hideContentPlayer() bật/tắt chế độ hiển thị nội dung trong quá trình phát quảng cáo.
Ví dụ này sử dụng biến hằng số adTagURLString để xác định thẻ quảng cáo VAST cho yêu cầu quảng cáo và các thành phần sau để quản lý SDK IMA:
adsLoader: Xử lý các yêu cầu và phản hồi về quảng cáo. Bạn nên sử dụng một phiên bản duy nhất cho vòng đời của ứng dụng.adDisplayContainer: Chỉ định khung hiển thị để hiển thị quảng cáo.adsManager: Quản lý việc phát quảng cáo và theo dõi các sự kiện quảng cáo.contentPlayhead: Theo dõi tiến trình nội dung để kích hoạt các điểm chèn quảng cáo trong video.adBreakActive: Cho biết liệu một điểm chèn quảng cáo có đang phát hay không để ngăn người dùng tua qua quảng cáo.
5. Triển khai trình theo dõi vị trí phát nội dung và trình quan sát cuối luồng phát
Để phát quảng cáo trong luồng phát, SDK IMA cần theo dõi vị trí hiện tại của nội dung video. Để thực hiện việc này, hãy tạo một lớp triển khai IMAContentPlayhead. Nếu bạn đang sử dụng AVPlayer, như minh hoạ trong ví dụ này, SDK sẽ cung cấp lớp IMAAVPlayerContentPlayhead để thực hiện việc này cho bạn.
Nếu không sử dụng AVPlayer, bạn cần triển khai IMAContentPlayhead trên một lớp của riêng mình.
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()
}
Bạn cũng cần cho SDK biết khi nào nội dung của bạn phát xong để SDK có thể hiển thị quảng cáo cuối video. Bạn có thể thực hiện việc này bằng cách gọi contentComplete trên IMAAdsLoader, bằng cách sử dụng AVPlayerItemDidPlayToEndTimeNotification.
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. Khởi chạy trình tải quảng cáo và đưa ra yêu cầu quảng cáo
Để yêu cầu một nhóm quảng cáo, bạn cần tạo một thực thể IMAAdsLoader.
Bạn có thể dùng trình tải này để xử lý các đối tượng IMAAdsRequest được liên kết với một URL thẻ quảng cáo cụ thể.
Theo phương pháp hay nhất, bạn chỉ nên duy trì một phiên bản IMAAdsLoader cho toàn bộ vòng đời của ứng dụng. Để đưa ra các yêu cầu quảng cáo bổ sung, hãy tạo một đối tượng IMAAdsRequest mới, nhưng sử dụng lại cùng một IMAAdsLoader. Để biết thêm thông tin, hãy xem Câu hỏi thường gặp về SDK IMA.
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. Thiết lập một đại biểu của trình tải quảng cáo
Trong một sự kiện tải thành công, IMAAdsLoader sẽ gọi phương thức adsLoadedWithData của uỷ quyền được chỉ định, truyền cho phương thức này một thực thể của IMAAdsManager. Sau đó, bạn có thể khởi chạy trình quản lý quảng cáo, trình này sẽ tải các quảng cáo riêng lẻ, như được xác định theo phản hồi đối với URL thẻ quảng cáo.
Ngoài ra, hãy nhớ xử lý mọi lỗi có thể xảy ra trong quá trình tải. Nếu quảng cáo không tải, hãy đảm bảo rằng quá trình phát nội dung nghe nhìn vẫn tiếp tục mà không có quảng cáo để không ảnh hưởng đến trải nghiệm của người dùng.
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. Thiết lập người đại diện quản lý quảng cáo
Cuối cùng, để quản lý các sự kiện và thay đổi trạng thái, trình quản lý quảng cáo cần có một uỷ quyền riêng. IMAAdManagerDelegate có các phương thức để xử lý các sự kiện và lỗi quảng cáo, cũng như các phương thức để kích hoạt chế độ phát và tạm dừng trên nội dung video của bạn.
Bắt đầu phát
Có nhiều sự kiện mà bạn có thể dùng phương thức didReceiveAdEvent để xử lý.
Đối với ví dụ cơ bản này, hãy theo dõi sự kiện LOADED để yêu cầu trình quản lý quảng cáo bắt đầu phát nội dung và quảng cáo. SDK IMA kích hoạt sự kiện ICON_FALLBACK_IMAGE_CLOSED khi người dùng đóng hộp thoại dự phòng biểu tượng sau khi nhấn vào một biểu tượng. Sau thao tác này, quảng cáo sẽ tiếp tục phát.
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
}
}
Xử lý lỗi
Thêm một trình xử lý cho lỗi quảng cáo. Nếu xảy ra lỗi, chẳng hạn như ở bước trước, hãy tiếp tục phát nội dung.
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()
}
Kích hoạt sự kiện phát và tạm dừng
Hai phương thức uỷ nhiệm cuối cùng mà bạn cần triển khai được dùng để kích hoạt các sự kiện phát và tạm dừng trên nội dung video cơ bản, khi được IMA SDK yêu cầu. Việc kích hoạt chế độ tạm dừng và phát khi được yêu cầu sẽ giúp người dùng không bỏ lỡ các phần của nội dung video khi quảng cáo xuất hiện.
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()
}
Vậy là xong! Giờ đây, bạn đang yêu cầu và hiển thị quảng cáo bằng SDK IMA. Để tìm hiểu về các tính năng bổ sung của SDK, hãy xem các hướng dẫn khác hoặc các mẫu trên GitHub.
Các bước tiếp theo
Để tối đa hoá doanh thu từ quảng cáo trên nền tảng tvOS, hãy yêu cầu quyền Minh bạch và theo dõi ứng dụng để sử dụng IDFA.