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 DAI của IMA, các ứng dụng sẽ đưa ra yêu cầu về luồng cho quảng cáo và video nội dung – có thể là nội dung VOD hoặc nội dung trực tiếp. Sau đó, SDK sẽ trả về một luồng video kết hợp, nhờ đó bạn không phải quản lý việc chuyển đổi giữa quảng cáo và video nội dung trong ứng dụng của mình.
Chọn giải pháp DAI mà bạn quan tâm
DAI trọn gói
Hướng dẫn này minh hoạ cách tích hợp SDK DAI của IMA vào một ứng dụng trình phát video đơn giản. Nếu 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ề DAI của IMA
Việc triển khai DAI của IMA bao gồm 3 thành phần SDK chính như minh hoạ trong hướng dẫn này:
IMAAdDisplayContainer
: Một đối tượng vùng chứa nằm phía trên phần tử phát video và chứa các phần tử giao diện người dùng quảng cáo.IMAAdsLoader
: Một đối tượng yêu cầu luồng và xử lý các sự kiện do đối tượng phản hồi yêu cầu luồng kích hoạt. Bạn chỉ nên khởi tạo một trình tải quảng cáo và có thể dùng lại trình tải này trong suốt thời gian hoạt động của ứng dụng.IMAStreamRequest
–IMAVODStreamRequest
hoặcIMALiveStreamRequest
: Một đối tượng xác định yêu cầu phát trực tuyến. Yêu cầu phát trực tuyến có thể là yêu cầu phát video theo yêu cầu hoặc phát trực tiếp. Yêu cầu phát trực tiếp chỉ định một khoá thành phần, trong khi yêu cầu VOD chỉ định một mã CMS và mã video. Cả hai loại yêu cầu đều có thể bao gồm một khoá API (không bắt buộc) cần thiết để truy cập vào các luồng truyền phát được chỉ định và mã mạng Google Ad Manager để SDK IMA xử lý mã nhận dạng quảng cáo như được chỉ định trong phần cài đặt Google Ad Manager.IMAStreamManager
: Một đối tượng xử lý các luồng chèn quảng cáo động và các lượt tương tác với phần phụ trợ DAI. Trình quản lý luồng phát cũng xử lý các ping theo dõi và chuyển tiếp các sự kiện luồng phát và quảng cáo đến nhà xuất bản.
Đ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
- CocoaPods (ưu tiên), Trình quản lý gói Swift hoặc bản sao đã tải xuống của SDK IMA DAI cho tvOS
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. Sử dụng BasicExample làm tên dự án.
Thêm SDK IMA DAI vào dự án Xcode
Hãy sử dụng một trong 3 phương thức sau để cài đặt IMA DAI SDK.
Cài đặt SDK bằng CocoaPods (nên dùng)
CocoaPods là một trình quản lý phần phụ thuộc cho các dự án Xcode và là phương thức được đề xuất để cài đặt IMA DAI SDK. Để 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 cài đặt CocoaPods, hãy làm theo hướng dẫn sau để cài đặt IMA DAI SDK:
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, '14' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.15.1' end
Từ thư mục chứa Podfile, hãy chạy:
pod install --repo-update`
Xá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).
Cài đặt SDK bằng Trình quản lý gói Swift
SDK quảng cáo trên phương tiện truyền thông tương tác 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 GoogleInteractiveMediaAds bằng cách chuyển đến File (Tệp) > Add Packages (Thêm gói).
Trong thông báo nhắc xuất hiện, hãy tìm kiếm kho lưu trữ GitHub cho Gói Swift GoogleInteractiveMediaAds:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
Chọn phiên bản của Gói Swift GoogleInteractiveMediaAds 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.
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.
Tải xuống và cài đặt SDK theo cách thủ công
Nếu không muốn sử dụng Trình quản lý gói Swift hoặc CocoaPods, bạn có thể tải SDK IMA DAI xuống và thêm SDK này vào dự án theo cách thủ công.
Tạo một trình phát video đơn giản
Trước tiên, hãy triển khai một trình phát video cơ bản. Ban đầu, trình phát này không sử dụng SDK IMA DAI và cũng không chứa phương thức nào để kích hoạt quá trình phát.
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
Nhập SDK và thêm các phần giữ chỗ cho hoạt động tương tác với IMA
Sau khi bạn thêm SDK IMA DAI vào dự án, hãy nhập SDK và thêm các phần giữ chỗ cho các điểm tương tác chính của 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
Triển khai IMAAdsLoader
Tiếp theo, hãy khởi tạo IMAAdsLoader
và đính kèm khung hiển thị vùng chứa quảng cáo vào hệ phân cấp khung hiển thị.
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;
}
Đưa ra yêu cầu phát trực tuyến
Tạo một vài hằng số để lưu giữ thông tin về luồng phát, sau đó triển khai hàm yêu cầu luồng phát để đưa ra yêu cầu.
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];
}
Xử lý sự kiện luồng
IMAAdsLoader
và IMAStreamManager
kích hoạt các sự kiện dùng để xử lý quá trình khởi chạy, lỗi và các thay đổi về trạng thái luồng. Các sự kiện này được kích hoạt qua giao thức IMAAdsLoaderDelegate
và IMAStreamManagerDelegate
. Theo dõi sự kiện quảng cáo đã tải và khởi chạy luồng. Nếu quảng cáo không tải được, hãy phát một luồng dự phòng.
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
Xử lý sự kiện ghi nhật ký và lỗi
Có một số sự kiện mà uỷ quyền của trình quản lý luồng phát có thể xử lý, nhưng đối với các hoạt động triển khai cơ bản, những mục đích quan trọng nhất là thực hiện ghi nhật ký sự kiện, ngăn chặn các thao tác tìm kiếm trong khi quảng cáo đang phát và xử lý lỗi.
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
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 DAI. Để tìm hiểu về các tính năng nâng cao khác của SDK, hãy xem các hướng dẫn khác hoặc các mẫu trên GitHub.