เริ่มต้นใช้งาน 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 4 อย่างดังที่แสดงใน คู่มือ

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

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

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

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

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

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

ใช้ 1 ใน 3 วิธีเหล่านี้เพื่อติดตั้ง 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 :ios, '14'
target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0'
end

  2. จากไดเรกทอรีที่มี Podfile ให้เรียกใช้

    pod install --repo-update`

  3. ยืนยันว่าการติดตั้งเสร็จสมบูรณ์โดยเปิด BasicExample.xcworkspace โปรเจ็กต์: BasicExample และ Pods (ทรัพยากร Dependency ที่ติดตั้งโดย CocoaPods)

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

SDK โฆษณาสื่ออินเทอร์แอกทีฟสนับสนุน Swift Package Manager เริ่มต้นในเวอร์ชัน 3.18.4 ทำตาม ขั้นตอนต่อไปนี้เพื่อนำเข้าแพ็กเกจ Swift

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

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

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

  3. เลือกเวอร์ชันของแพ็กเกจ IMA DAI SDK Swift ที่ต้องการใช้ สำหรับมือใหม่ เราขอแนะนำให้ใช้เวอร์ชันล่าสุดถัดไป

เมื่อดำเนินการเสร็จแล้ว 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