ตั้งค่า IMA SDK

เลือกแพลตฟอร์ม: HTML5 Android iOS tvOS

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

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

ภาพรวมฝั่งไคลเอ็นต์ของ IMA

การใช้ IMA ฝั่งไคลเอ็นต์เกี่ยวข้องกับคอมโพเนนต์ SDK หลัก 4 รายการ ซึ่งแสดงไว้ในคู่มือนี้

  • IMAAdDisplayContainer: ออบเจ็กต์คอนเทนเนอร์ที่ระบุตําแหน่งที่ IMA แสดงองค์ประกอบ UI ของโฆษณาและวัดการมองเห็นโฆษณา รวมถึงมุมมองแอ็กทีฟและ Open Measurement
  • IMAAdsLoader: ออบเจ็กต์ที่ขอโฆษณาและจัดการเหตุการณ์จากการตอบกลับคำขอโฆษณา คุณควร สร้างอินสแตนซ์ของ AdsLoader เพียงรายการเดียว ซึ่งสามารถนำกลับมาใช้ใหม่ได้ตลอดอายุการใช้งานของแอปพลิเคชัน
  • IMAAdsRequest: ออบเจ็กต์ที่กำหนดคำขอโฆษณา คำขอโฆษณาระบุ URL สำหรับแท็กโฆษณา VAST รวมถึง พารามิเตอร์เพิ่มเติม เช่น ขนาดโฆษณา
  • IMAAdsManager: ออบเจ็กต์ที่มีการตอบกลับคำขอโฆษณา ควบคุมการเล่นโฆษณา และรอฟังเหตุการณ์โฆษณา ที่ SDK เรียกใช้

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

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

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

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

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

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

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

  1. ใน Xcode ให้ติดตั้งแพ็กเกจ Swift ของ IMA SDK โดยไปที่File > Add Packages...

  2. ในพรอมต์ที่ปรากฏขึ้น ให้ค้นหาที่เก็บ IMA SDK Swift Package GitHub

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

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

ติดตั้ง IMA SDK โดยใช้ CocoaPods

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

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

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

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

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

หากไม่ต้องการใช้ CocoaPods คุณสามารถดาวน์โหลด IMA SDK และเพิ่มลงในโปรเจ็กต์ด้วยตนเองได้

3. นำเข้า IMA SDK

เพิ่มเฟรมเวิร์ก IMA โดยใช้คำสั่งนำเข้า

Objective-C

#import "ViewController.h"
#import <AVKit/AVKit.h>

@import GoogleInteractiveMediaAds;

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

4. สร้างวิดีโอเพลเยอร์และผสานรวม IMA SDK

ตัวอย่างต่อไปนี้เริ่มต้น IMA SDK

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

ในตัวอย่างนี้ viewDidLoad() จะเริ่มต้น IMAAdsLoader และ viewDidAppear() จะขอโฆษณาเมื่อมุมมองปรากฏ เมธอด Helper showContentPlayer() และ hideContentPlayer() สลับระดับการมองเห็นเนื้อหาระหว่าง การเล่นโฆษณา

ตัวอย่างนี้ใช้ตัวแปรค่าคงที่ adTagURLString เพื่อกำหนดแท็กโฆษณา VAST สำหรับคำขอโฆษณา และใช้คอมโพเนนต์ต่อไปนี้เพื่อจัดการ IMA SDK

  • adsLoader: จัดการคำขอโฆษณาและการตอบกลับ เราขอแนะนำให้ใช้ อินสแตนซ์เดียวสำหรับวงจรของแอป
  • adDisplayContainer: ระบุมุมมองสำหรับการแสดงโฆษณา
  • adsManager: จัดการการเล่นโฆษณาและรอเหตุการณ์โฆษณา
  • contentPlayhead: ติดตามความคืบหน้าของเนื้อหาเพื่อเรียกช่วงพักโฆษณาตอนกลาง
  • adBreakActive: ระบุว่าช่วงพักโฆษณากำลังเล่นอยู่เพื่อป้องกันไม่ให้ ข้ามโฆษณา

5. ใช้เครื่องมือติดตามหัวอ่านเนื้อหาและเครื่องมือสังเกตการณ์ตอนท้ายของสตรีม

IMA SDK ต้องติดตามตำแหน่งปัจจุบัน ของเนื้อหาวิดีโอเพื่อเล่นโฆษณาตอนกลาง โดยสร้างคลาสที่ใช้IMAContentPlayhead หากคุณใช้ AVPlayer ดังที่แสดงในตัวอย่างนี้ SDK จะมีคลาส IMAAVPlayerContentPlayhead ที่ทำสิ่งนี้ให้คุณ หากไม่ได้ใช้ AVPlayer คุณจะต้องใช้ IMAContentPlayhead ใน คลาสของคุณเอง

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

นอกจากนี้ คุณยังต้องแจ้งให้ SDK ทราบเมื่อเนื้อหาเล่นจบแล้วเพื่อให้ SDK แสดงโฆษณาหลังม้วนฟิล์มได้ โดยทำได้ด้วยการเรียกใช้ contentComplete ใน IMAAdsLoader โดยใช้ AVPlayerItemDidPlayToEndTimeNotification

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. เริ่มต้นเครื่องมือโหลดโฆษณาและส่งคำขอโฆษณา

หากต้องการขอชุดโฆษณา คุณต้องสร้างอินสแตนซ์ IMAAdsLoader คุณสามารถใช้โปรแกรมโหลดนี้เพื่อประมวลผลออบเจ็กต์ IMAAdsRequest ที่เชื่อมโยงกับ URL แท็กโฆษณาที่ระบุ

แนวทางปฏิบัติแนะนำคือให้คงอินสแตนซ์ของ IMAAdsLoader ไว้เพียงอินสแตนซ์เดียวตลอดวงจรของแอป หากต้องการส่งคำขอโฆษณาเพิ่มเติม ให้สร้างออบเจ็กต์ IMAAdsRequest ใหม่ แต่ให้ใช้ IMAAdsLoader เดิม ดูข้อมูลเพิ่มเติมได้ที่คำถามที่พบบ่อยเกี่ยวกับ IMA SDK

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. ตั้งค่าผู้มอบสิทธิ์โปรแกรมโหลดโฆษณา

ในเหตุการณ์การโหลดที่สำเร็จ IMAAdsLoader จะเรียกใช้เมธอด adsLoadedWithData ของตัวแทนที่กำหนด โดยส่งอินสแตนซ์ของ IMAAdsManager ไปให้ จากนั้นคุณ จะเริ่มต้นใช้งานเครื่องมือจัดการโฆษณาได้ ซึ่งจะโหลดโฆษณาแต่ละรายการตามที่กำหนด โดยการตอบกลับ URL ของแท็กโฆษณา

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

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. ตั้งค่าผู้รับมอบสิทธิ์ของ Ads Manager

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

เริ่มเล่น

didReceiveAdEvent สามารถใช้จัดการกิจกรรมได้หลายอย่าง สำหรับตัวอย่างพื้นฐานนี้ ให้รอเหตุการณ์ LOADED เพื่อบอกให้ Ad Manager เริ่มเล่นเนื้อหาและโฆษณา IMA SDK จะทริกเกอร์เหตุการณ์ ICON_FALLBACK_IMAGE_CLOSED เมื่อผู้ใช้ปิดกล่องโต้ตอบไอคอนสำรอง หลังจากแตะไอคอน หลังจากดำเนินการนี้แล้ว การเล่นโฆษณาจะกลับมาทำงานอีกครั้ง

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

การจัดการข้อผิดพลาด

เพิ่มตัวแฮนเดิลสำหรับข้อผิดพลาดเกี่ยวกับโฆษณาด้วย หากเกิดข้อผิดพลาด เช่น ในขั้นตอนก่อนหน้า ให้เล่นเนื้อหาต่อ

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

ทริกเกอร์เหตุการณ์การเล่นและการหยุดชั่วคราว

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

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

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

ขั้นตอนถัดไป

หากต้องการเพิ่มรายได้จากโฆษณาในแพลตฟอร์ม tvOS ให้ได้สูงสุด ขอสิทธิ์ความโปร่งใสและการติดตามของแอปเพื่อใช้ IDFA