Thiết lập IMA SDK

Chọn nền tảng: HTML5 Android iOS tvOS

SDK IMA giúp bạn dễ dàng tích hợp quảng cáo đa phương tiện vào các trang web và ứng dụng. SDK IMA có thể yêu cầu quảng cáo từ mọi tuân thủ VAST máy chủ quảng cáo và quản lý việc phát quảng cáo trong ứng dụng. Với SDK IMA phía máy khách, bạn vẫn có thể kiểm soát việc phát nội dung video, 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 ở trên cùng trình phát video nội dung của ứng dụng.

Hướng dẫn này trình bày cách tích hợp SDK IMA vào một ứng dụng trình phát video. Để 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ề IMA phía máy khách

Việc triển khai IMA phía máy khách bao gồm 4 thành phần SDK chính. Hướng dẫn này trình bày các thành phần đó:

  • 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 quảng cáo và đo lường khả năng xem, bao gồm cả Active ViewOpen Measurement.
  • 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 thực thể cho một trình tải quảng cáo. Trình tải này có thể được sử dụng lại 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. Yêu cầu quảng cáo chỉ định URL cho thẻ quảng cáo VAST, cũng như các tham 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 điều sau:

1. Tạo 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 SDK IMA vào dự án Xcode

Để cài đặt SDK IMA, hãy chọn một phương thức ưu tiên.

Đề xuất: Cài đặt SDK IMA 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 phiên bản 4.8.2 trở lên. Hãy làm theo các bước sau để nhập gói Swift.

  1. 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)....

  2. Khi 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 SDK IMA:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
    
  3. Chọn phiên bản của Gói Swift SDK IMA 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 đọc bài viết của Apple.

Cài đặt SDK IMA bằng CocoaPods

Để cài đặt SDK IMA, 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 cài đặt CocoaPods, hãy làm như sau:

  1. Trong cùng một 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'
    end
    
    
  2. Từ thư mục chứa Podfile, hãy chạy pod install --repo-update

  3. 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: BasicExamplePods (các phần phụ thuộc do CocoaPods cài đặt).

Tải xuống và cài đặt SDK IMA theo cách thủ công

Nếu không muốn sử dụng Trình quản lý gói Swift, hãy tải xuống và thêm SDK IMA vào dự án của bạn theo cách thủ công.

3. Nhập SDK IMA

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 SDK IMA:

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 chạy IMAAdsLoaderviewDidAppear() yêu cầu quảng cáo khi khung hiển thị hiển thị. Các phương thức trợ giúp showContentPlayer()hideContentPlayer() chuyển đổi 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 đây để quản lý IMA SDK:

  • adsLoader: Xử lý các yêu cầu và phản hồi quảng cáo. Bạn nên sử dụng một thực thể 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 giữa 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 việc tìm kiếm trên quảng cáo.

5. Triển khai trình theo dõi con trỏ vị trí nội dung và trình quan sát cuối luồng

Để phát quảng cáo chèn giữa, SDK IMA phải theo dõi vị trí hiện tại của nội dung video. Để truyền vị trí hiện tại đến IMA, hãy tạo một lớp triển khai IMAContentPlayhead. Nếu bạn sử dụng một AVPlayer, như ví dụ này cho thấy, IMA SDK sẽ cung cấp lớp IMAAVPlayerContentPlayhead để truyền thông tin vị trí hiện tại cho bạn. Nếu bạn không sử dụng AVPlayer, hãy triển khai IMAContentPlayhead trên một lớp của riêng bạn.

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()
}

Thiết lập trình nghe để gọi contentComplete trên IMAAdsLoader khi nội dung của bạn kết thúc, bằng cách sử dụng AVPlayerItemDidPlayToEndTimeNotification. Việc gọi contentComplete cho phép IMA SDK biết thời điểm nội dung của bạn phát xong để hiển thị quảng cáo chèn sau.

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à tạo yêu cầu quảng cáo

Để yêu cầu một tập hợp quảng cáo, hãy tạo một thực thể IMAAdsLoader. 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 chỉ định.

Theo phương pháp hay nhất, bạn chỉ nên duy trì một thực thể IMAAdsLoader cho toàn bộ vòng đời của ứng dụng. Để tạo 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 đạ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 đại biểu được chỉ định, truyền cho phương thức này một thực thể IMAAdsManager. Sau khi có thực thể IMAAdsManager, hãy khởi chạy trình quản lý quảng cáo. Trình quản lý này sẽ tải từng quảng cáo dựa trên phản hồi của URL thẻ quảng cáo.

Đối với các sự kiện tải không thành công, hãy thiết lập một đại biểu IMAAdsLoader để xử lý các lỗi 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 tiếp tục mà không có quảng cáo để người dùng có thể xem nội dung nghe nhìn.

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 được uỷ quyền của Ad Manager

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 người được 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 việc phát và tạm dừng nội dung video.

Bắt đầu phát

Phương thức didReceiveAdEvent xử lý tất cả các sự kiện IMAAdEvent. Đối với ví dụ cơ bản này, hãy theo dõi sự kiện LOADED để cho trình quản lý quảng cáo biết thời điểm 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 hành động này, quá trình phát quảng cáo sẽ tiếp tục.

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 trình xử lý cho lỗi quảng cáo. Nếu xảy ra lỗi, như trong 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 đại biểu cuối cùng mà bạn triển khai sẽ 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 IMA SDK yêu cầu. Việc kích hoạt tạm dừng và phát khi SDK IMA yêu cầu sẽ ngăn người dùng bỏ lỡ các phần của nội dung video khi quảng cáo hiển thị.

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.