เริ่มต้นใช้งาน IMA DAI SDK

IMA SDK ช่วยให้ผสานรวมโฆษณามัลติมีเดียลงในเว็บไซต์และแอปได้อย่างง่ายดาย IMA SDK สามารถ ส่งคำขอโฆษณาจาก เซิร์ฟเวอร์โฆษณาที่ปฏิบัติตามข้อกำหนดของ VAST และจัดการการเล่นโฆษณาในแอปของคุณ ด้วย IMA DAI SDK แอปจะสร้าง คำขอสตรีมสำหรับโฆษณาและวิดีโอเนื้อหา ไม่ว่าจะเป็น VOD หรือเนื้อหาสด จากนั้น SDK จะแสดงผลสตรีมวิดีโอแบบรวม คุณจึงไม่ต้องจัดการการสลับระหว่างวิดีโอโฆษณากับวิดีโอเนื้อหาภายในแอป

เลือกโซลูชัน DAI ที่คุณสนใจ

DAI แบบครบวงจร

คู่มือนี้สาธิตวิธีผสานรวม IMA DAI SDK เข้ากับโปรแกรมเล่นวิดีโอแบบง่าย แอป หากคุณต้องการดูหรือติดตามไปพร้อมกับตัวอย่างที่สมบูรณ์ การผสานรวม ให้ดาวน์โหลด BasicExample จาก GitHub

ภาพรวม IMA DAI

การติดตั้งใช้งาน IMA DAI เกี่ยวข้องกับองค์ประกอบหลักของ SDK 3 อย่างดังที่แสดงใน คู่มือ

  • IMAAdDisplayContainer: ออบเจ็กต์คอนเทนเนอร์ที่วางอยู่ด้านบนขององค์ประกอบการเล่นวิดีโอและเป็นที่เก็บองค์ประกอบ UI ของโฆษณา
  • IMAAdsLoader: ออบเจ็กต์ที่ขอสตรีมและจัดการเหตุการณ์ที่ทริกเกอร์โดยออบเจ็กต์การตอบกลับของคำขอสตรีม คุณควรสร้างอินสแตนซ์ของเครื่องมือโหลดโฆษณาเพียงรายการเดียว ซึ่งนํามาใช้ซ้ำได้ตลอดอายุการใช้งานของแอปพลิเคชัน
  • IMAStreamRequest – อาจเป็น IMAVODStreamRequest หรือ IMALiveStreamRequest: ออบเจ็กต์ที่กำหนดคำขอสตรีม คำขอสตรีมจะเป็นวิดีโอออนดีมานด์หรือแบบสดก็ได้ สตรีม คำขอระบุรหัสเนื้อหา รวมทั้งคีย์ API หรือโทเค็นการตรวจสอบสิทธิ์ และอื่นๆ พารามิเตอร์
  • IMAStreamManager: ออบเจ็กต์ที่จัดการสตรีมการแทรกโฆษณาแบบไดนามิกและการโต้ตอบกับแบ็กเอนด์ DAI เครื่องมือจัดการสตรีมยังจัดการคําสั่ง ping ในการติดตาม รวมถึงส่งต่อเหตุการณ์ของสตรีมและโฆษณาไปยัง ผู้เผยแพร่โฆษณา

ข้อกำหนดเบื้องต้น

ก่อนเริ่มต้น คุณต้องมีสิ่งต่อไปนี้

สร้างโปรเจ็กต์ Xcode ใหม่

ใน Xcode ให้สร้างโปรเจ็กต์ tvOS ใหม่โดยใช้ Objective-C ใช้ BasicExample เป็น ชื่อโปรเจ็กต์

เพิ่ม IMA DAI SDK ลงในโปรเจ็กต์ Xcode

ใช้วิธีใดวิธีหนึ่งต่อไปนี้เพื่อติดตั้ง IMA DAI SDK

ติดตั้ง SDK โดยใช้ CocoaPods (แนะนำ)

CocoaPods เป็นเครื่องมือจัดการทรัพยากร Dependency สําหรับโปรเจ็กต์ Xcode และเป็นวิธีที่เราแนะนําสําหรับการติดตั้ง IMA DAI SDK สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการติดตั้งหรือการใช้ CocoaPods โปรดดูเอกสารประกอบของ CocoaPods เมื่อติดตั้ง CocoaPods แล้ว ให้ทําตามวิธีการต่อไปนี้เพื่อติดตั้ง IMA DAI SDK

  1. ในไดเรกทอรีเดียวกับไฟล์ BasicExample.xcodeproj ให้สร้างไฟล์ข้อความชื่อ Podfile และเพิ่มการกําหนดค่าต่อไปนี้

    source 'https://github.com/CocoaPods/Specs.git'
    platform :tvos, '14'
    target "BasicExample" do
      pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.13.0'
    end
    
  2. จากไดเรกทอรีที่มี Podfile ให้เรียกใช้

    pod install --repo-update`
  3. ยืนยันว่าการติดตั้งสำเร็จโดยเปิดไฟล์ BasicExample.xcworkspace และตรวจสอบว่ามีโปรเจ็กต์ 2 รายการ ได้แก่ BasicExample และ Pods (Dependency ที่ CocoaPods ติดตั้ง)

ติดตั้ง SDK โดยใช้ Swift Package Manager

Interactive Media Ads SDK รองรับ Swift Package Manager ตั้งแต่เวอร์ชัน 4.8.2 เป็นต้นไป ทำตาม ขั้นตอนการนำเข้าแพ็กเกจ Swift

  1. ใน Xcode ให้ติดตั้งแพ็กเกจ Swift ของ GoogleInteractiveMediaAds โดยไปที่ไฟล์ > เพิ่มแพ็กเกจ

  2. ในข้อความแจ้งที่ปรากฏขึ้น ให้ค้นหา GoogleInteractiveMediaAds Swift ที่เก็บแพ็กเกจ GitHub:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
    
  3. เลือกเวอร์ชันของ GoogleInteractiveMediaAds Swift Package ที่ต้องการใช้ สำหรับมือใหม่ เราขอแนะนำให้ใช้เวอร์ชันล่าสุดถัดไป

เมื่อดำเนินการเสร็จแล้ว Xcode จะจับคู่ข้อมูลและดาวน์โหลดทรัพยากร Dependency ของแพ็กเกจในเบื้องหลัง ดูรายละเอียดเพิ่มเติมเกี่ยวกับวิธีเพิ่มทรัพยากร Dependency ของแพ็กเกจได้ที่ สำหรับ Apple บทความ

การดาวน์โหลดและติดตั้ง SDK ด้วยตนเอง

หากไม่ต้องการใช้ Swift Package Manager หรือ CocoaPods ให้ดาวน์โหลด IMA DAI SDK แล้วเพิ่มลงในโปรเจ็กต์ด้วยตนเอง

สร้างวิดีโอเพลเยอร์ง่ายๆ

ก่อนอื่น ให้ติดตั้งใช้งานวิดีโอเพลเยอร์พื้นฐาน ในช่วงแรก โปรแกรมเล่นนี้ไม่ได้ใช้ IMA DAI SDK และไม่มีวิธีการเรียกให้เล่น

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

นําเข้า SDK และเพิ่มสแต็บสําหรับการโต้ตอบ IMA

หลังจากที่เพิ่ม IMA DAI SDK ลงในโปรเจ็กต์แล้ว ให้นำเข้า SDK และเพิ่มสตับสำหรับ ประเด็นหลักๆ ในการโต้ตอบกับ 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

ติดตั้ง IMAAdsLoader

ถัดไป สร้างอินสแตนซ์ IMAAdsLoader และแนบมุมมองคอนเทนเนอร์โฆษณาเข้ากับ ลำดับชั้นการแสดงผล

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

ส่งคำขอสตรีม

สร้างค่าคงตัว 2-3 รายการเพื่อเก็บข้อมูลของสตรีม แล้วติดตั้งใช้งาน ฟังก์ชันคำขอสตรีม เพื่อสร้างคำขอ

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";

@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];
}

จัดการเหตุการณ์สตรีม

เหตุการณ์ไฟไหม้ของ IMAAdsLoader และ IMAStreamManager ที่ใช้จัดการ การเริ่มต้น ข้อผิดพลาด และการเปลี่ยนแปลงในสถานะของสตรีม เหตุการณ์เหล่านี้เริ่มทำงานใน โปรโตคอล IMAAdsLoaderDelegate และ IMAStreamManagerDelegate คอยฟังเหตุการณ์ที่โฆษณาโหลดแล้วและเริ่มต้นสตรีม หากโฆษณาโหลดไม่สำเร็จ ให้เล่นสตรีมสำรองแทน

ViewController.m

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

จัดการการบันทึกและเหตุการณ์ข้อผิดพลาด

เหตุการณ์หลายรายการที่ตัวแทนผู้จัดการสตรีมจัดการได้ แต่สำหรับการใช้งานขั้นพื้นฐาน การใช้งานที่สำคัญที่สุดคือการบันทึกเหตุการณ์ เพื่อป้องกันการกรอขณะที่โฆษณาเล่นอยู่ และเพื่อจัดการข้อผิดพลาด

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

เท่านี้ก็เรียบร้อย ตอนนี้คุณกำลังขอและแสดงโฆษณาด้วย IMA DAI SDK หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับฟีเจอร์ขั้นสูงของ SDK โปรดดูคู่มืออื่นๆ หรือตัวอย่างใน GitHub