Bắt đầu

IMA SDK 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 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 nào tuân thủ VAST và quản lý hoạt động phát quảng cáo trong ứng dụng của bạn. Với SDK IMA DAI, ứng dụng sẽ đưa ra yêu cầu phát trực tiếp cho video quảng cáo và nội dung, kể cả video theo yêu cầu 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 video quảng cáo và video nội dung trong ứng dụng của mình.

Hướng dẫn này minh hoạ cách tích hợp SDK IMA vào một ứng dụng trình phát video đơn giản. Nếu bạn muốn xem hoặc làm theo quá trình tích hợp mẫu hoàn chỉnh, hãy tải BasicExample xuống từ GitHub.

Tổng quan về IMA DAI

Quá trình triển khai IMA DAI bao gồm 4 thành phần SDK chính, như được 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ử trên 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 được kích hoạt bởi các đối tượng phản hồi yêu cầu luồng. Bạn chỉ nên tạo bản sao một trình tải quảng cáo. Bạn 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.
  • IMAStreamRequest – IMAVODStreamRequest hoặc IMALiveStreamRequest: Đối tượng xác định yêu cầu truyền trực tuyến. Yêu cầu phát trực tiếp có thể là video theo yêu cầu hoặc sự kiện phát trực tiếp. Các yêu cầu chỉ định một mã nội dung, cũng như khoá API hoặc mã thông báo xác thực và các tham số khác.
  • IMAStreamManager: Đối tượng xử lý 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ý sự kiện phát trực tiếp cũng xử lý các ping theo dõi, đồng thời chuyển tiếp các sự kiện trong luồng và sự kiện 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ó:

1. Tạo dự án Xcode mới

Trong Xcode, hãy tạo một dự án iOS mới bằng Objective-C. Sử dụng BasicExample làm tên dự án.

2. Thêm IMA SDK vào dự án Xcode

Cài đặt SDK bằng CocoaPods (ưu tiên)

CocoaPods là trình quản lý phần phụ thuộc cho các dự án Xcode và là phương thức nên dùng để cài đặt SDK IMA. Để 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 theo hướng dẫn sau để cài đặt SDK IMA:

  1. Trong cùng thư mục với tệp BasicExample.xcodeproj của bạn, hãy tạo một tệp văn bản có tên Podfile và thêm cấu hình sau:

    source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10'
target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.11.4'
end

  2. Trong 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 hai 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 3.18.4. Hãy làm theo các bước bên dưới để nhập gói Swift.

  1. Trong Xcode, hãy cài đặt Gói IMA SDK Swift bằng cách chuyển đến File > Add Packages... (Tệp > Thêm gói...).

  2. Khi lời nhắc xuất hiện, hãy tìm kiếm kho lưu trữ GitHub của Gói IMA SDK Swift:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios

  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 tính năng Lên phiên bản chính 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 trong 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 xuống và tự thêm SDK này vào dự án của mình.

3. 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 và chưa 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

4. Nhập SDK và thêm mã giả lập cho tương tác IMA

Sau khi bạn thêm SDK IMA vào dự án của mình, hãy nhập SDK và thêm mã giả lập cho các điểm chính của hoạt động tương tác 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

5. Triển khai IMAAdsLoader

Tiếp theo, hãy tạo thực thể IMAAdsLoader và đính kèm chế độ xem vùng chứa quảng cáo vào hệ phân cấp chế độ xem.

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;
}
...

6. Tạo một yêu cầu phát trực tiếp

Tạo một vài hằng số để lưu giữ thông tin luồng rồi triển khai hàm yêu cầu luồng để đưa ra yêu cầu.

ViewController.m

...
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
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];
}
...

7. Xử lý sự kiện phát trực tiếp

IMAAdsLoader và IMAStreamManager kích hoạt các sự kiện dùng để xử lý hoạt động khởi chạy, lỗi và các thay đổi về trạng thái truyền trực tuyến. Những 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 động luồng. Nếu quảng cáo không tải được, hãy phát luồng dự phòng.

ViewController.m

...
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
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

8. Xử lý việc ghi nhật ký và các sự kiện lỗi

Có một số sự kiện mà trình quản lý luồng truyền phát có thể xử lý, nhưng đối với các hoạt động triển khai cơ bản, mục đích sử dụng quan trọng nhất là thực hiện ghi nhật ký sự kiện, để ngăn các hành động 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! Bạn đang yêu cầu và hiển thị quảng cáo bằng SDK IMA. Để tìm hiểu 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 mẫu trên GitHub.

Các bước tiếp theo

Để tăng tối đa doanh thu quảng cáo trên nền tảng iOS, hãy yêu cầu Quyền minh bạch trong ứng dụng và Theo dõi để sử dụng IDFA.