Konfigurowanie pakietu IMA SDK

Wybierz platformę: HTML5 Android iOS tvOS

Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą wysyłać żądania reklam do dowolnego serwera reklam zgodnego z VAST i zarządzać odtwarzaniem reklam w aplikacjach. Dzięki pakietom IMA SDK po stronie klienta zachowujesz kontrolę nad odtwarzaniem treści wideo, a pakiet SDK obsługuje odtwarzanie reklam. Reklamy są odtwarzane w osobnym odtwarzaczu wideo umieszczonym nad odtwarzaczem wideo z treściami aplikacji.

W tym przewodniku pokazujemy, jak zintegrować pakiet IMA SDK z aplikacją odtwarzacza wideo. Aby wyświetlić gotową przykładową integrację lub postępować zgodnie z nią, pobierz BasicExample z GitHub.

Omówienie IMA po stronie klienta

Wdrażanie pakietu IMA SDK po stronie klienta obejmuje 4 główne komponenty SDK. W tym przewodniku znajdziesz informacje o tych komponentach:

  • IMAAdDisplayContainer: obiekt kontenera, który określa, gdzie IMA renderuje elementy interfejsu reklamy i mierzy widoczność, w tym Widok aktywny i Open Measurement.
  • IMAAdsLoader: obiekt, który wysyła żądania reklam i obsługuje zdarzenia z odpowiedzi na żądania reklam. Powinieneś utworzyć tylko jeden moduł wczytywania reklam, którego można używać przez cały okres działania aplikacji.
  • IMAAdsRequest: obiekt, który definiuje żądanie reklamy. Żądania reklam określają adres URL tagu reklamy VAST, a także dodatkowe parametry, takie jak wymiary reklamy.
  • IMAAdsManager: Obiekt, który zawiera odpowiedź na żądanie reklamy, kontroluje odtwarzanie reklam i nasłuchuje zdarzeń reklamowych wywoływanych przez pakiet SDK.

Wymagania wstępne

Zanim zaczniesz, musisz mieć:

1. Tworzenie nowego projektu Xcode

W Xcode utwórz nowy projekt tvOS w języku Objective-C lub Swift. Użyj nazwy projektu BasicExample.

2. Dodawanie pakietu IMA SDK do projektu w Xcode

Aby zainstalować pakiet IMA SDK, wybierz preferowaną metodę.

Zalecane: instalowanie pakietu IMA SDK za pomocą menedżera pakietów Swift

Pakiet SDK do wyświetlania interaktywnych reklam medialnych obsługuje Swift Package Manager od wersji 4.8.2. Aby zaimportować pakiet Swift, wykonaj te czynności.

  1. W Xcode zainstaluj pakiet IMA SDK Swift, klikając kolejno File > Add Packages... (Plik > Dodaj pakiety...).

  2. W wyświetlonym wierszu polecenia wyszukaj repozytorium pakietu IMA SDK Swift Package GitHub:

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

  3. Wybierz wersję pakietu IMA SDK Swift, której chcesz używać. W przypadku nowych projektów zalecamy używanie opcji Do następnej wersji głównej.

Gdy skończysz, Xcode przetworzy zależności pakietu i pobierze je w tle. Więcej informacji o dodawaniu zależności pakietów znajdziesz w artykule Apple.

Instalowanie pakietu IMA SDK za pomocą CocoaPods

Aby zainstalować pakiet IMA SDK, użyj CocoaPods. Więcej informacji o instalowaniu i używaniu CocoaPods znajdziesz w dokumentacji CocoaPods. Po zainstalowaniu CocoaPods wykonaj te czynności:

  1. W tym samym katalogu, w którym znajduje się plik BasicExample.xcodeproj, utwórz plik tekstowy o nazwie Podfile i dodaj tę konfigurację:

    source 'https://github.com/CocoaPods/Specs.git'

platform :tvos, '15'

target "BasicExample" do
  pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0'
end

    Podfile

  2. W katalogu zawierającym plik Podfile uruchom pod install --repo-update

  3. Sprawdź, czy instalacja się powiodła. W tym celu otwórz plik BasicExample.xcworkspace i upewnij się, że zawiera 2 projekty: BasicExample i Pods (zależności zainstalowane przez CocoaPods).

Ręczne pobieranie i instalowanie pakietu IMA SDK

Jeśli nie chcesz używać menedżera pakietów Swift, pobierz i ręcznie dodaj do projektu pakiet IMA SDK.

3. Importowanie pakietu IMA SDK

Dodaj platformę IMA za pomocą instrukcji importu.

Objective-C

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

@import GoogleInteractiveMediaAds;
ViewController.m

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

ViewController.swift

4. Tworzenie odtwarzacza wideo i integrowanie pakietu IMA SDK

W tym przykładzie pokazujemy, jak zainicjować pakiet 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];
}
ViewController.m

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()
  }
ViewController.swift

W tym przykładzie viewDidLoad() inicjuje IMAAdsLoader, a viewDidAppear() wysyła żądanie reklam, gdy widok jest widoczny. Metody pomocnicze showContentPlayer() i hideContentPlayer() przełączają widoczność treści podczas odtwarzania reklamy.

W tym przykładzie zmienna stała adTagURLString służy do zdefiniowania tagu reklamy VAST na potrzeby żądania reklamy, a do zarządzania pakietem IMA SDK używane są te komponenty:

  • adsLoader: obsługuje żądania reklam i odpowiedzi na nie. Zalecamy używanie jednej instancji przez cały cykl życia aplikacji.
  • adDisplayContainer: określa widok do renderowania reklam.
  • adsManager: zarządza odtwarzaniem reklam i nasłuchuje zdarzeń związanych z reklamami.
  • contentPlayhead: śledzi postęp odtwarzania treści, aby włączać przerwy na reklamy w trakcie filmu.
  • adBreakActive: wskazuje, czy odtwarzana jest przerwa na reklamę, aby zapobiec przewijaniu reklam.

5. Wdrożenie narzędzia do śledzenia pozycji odtwarzania treści i obserwatora końca transmisji

Aby wyświetlać reklamy w trakcie filmu, pakiet IMA SDK musi śledzić bieżącą pozycję treści wideo. Aby przekazać bieżącą pozycję do IMA, utwórz klasę, która implementuje interfejs IMAContentPlayhead. Jeśli używasz znaku AVPlayer, jak w tym przykładzie, pakiet IMA SDK udostępnia klasę IMAAVPlayerContentPlayhead, która przekazuje informacje o bieżącej pozycji. Jeśli nie używasz AVPlayer, zaimplementuj IMAContentPlayhead w klasie własnej.

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];
}
ViewController.m

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()
}
ViewController.swift

Skonfiguruj detektor, który będzie wywoływać contentComplete w obiekcie IMAAdsLoader po zakończeniu treści, używając AVPlayerItemDidPlayToEndTimeNotification. Wywołanie funkcji contentComplete informuje pakiet IMA SDK o zakończeniu odtwarzania treści, aby można było wyświetlić reklamy po filmie.

Objective-C

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Notify the SDK that the postrolls should be played.
  [self.adsLoader contentComplete];
}

- (void)dealloc {
  [[NSNotificationCenter defaultCenter] removeObserver:self];
}
ViewController.m

Swift

@objc func contentDidFinishPlaying(_ notification: Notification) {
  adsLoader.contentComplete()
}
ViewController.swift

6. Zainicjuj moduł wczytywania reklam i wyślij żądanie reklamy.

Aby poprosić o zestaw reklam, utwórz instancję IMAAdsLoader. Ten moduł wczytujący przetwarza obiekty IMAAdsRequest powiązane z określonym adresem URL tagu reklamy.

Zalecamy utrzymywanie tylko jednej instancji IMAAdsLoader przez cały cykl życia aplikacji. Aby wysłać dodatkowe żądania reklamy, utwórz nowy obiekt IMAAdsRequest, ale użyj tego samego obiektu IMAAdsLoader. Więcej informacji znajdziesz w odpowiedziach na najczęstsze pytania dotyczące pakietu 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];
}
ViewController.m

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)
}
ViewController.swift

7. Konfigurowanie delegata modułu wczytywania reklam

Po pomyślnym wczytaniu zdarzenia IMAAdsLoader wywołuje metodę adsLoadedWithData przypisanego delegata, przekazując jej instancję IMAAdsManager. Po utworzeniu instancji IMAAdsManager zainicjuj menedżera reklam, który wczytuje poszczególne reklamy na podstawie odpowiedzi adresu URL tagu reklamy.

W przypadku nieudanych zdarzeń wczytywania skonfiguruj delegata IMAAdsLoader do obsługi błędów, które występują podczas procesu wczytywania. Jeśli reklamy się nie wczytują, upewnij się, że odtwarzanie multimediów jest kontynuowane bez reklam, aby użytkownicy mogli oglądać treści.

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];
}
ViewController.m

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()
}
ViewController.swift

8. Konfigurowanie delegata menedżera reklam

Na koniec, aby zarządzać zdarzeniami i zmianami stanu, menedżer reklam wymaga własnego delegata. Interfejs IMAAdManagerDelegate ma metody obsługi zdarzeń i błędów związanych z reklamami, a także metody wywoływania odtwarzania i wstrzymywania treści wideo.

Rozpoczynanie odtwarzania

Metoda didReceiveAdEvent obsługuje wszystkie zdarzenia IMAAdEvent. W tym podstawowym przykładzie nasłuchuj zdarzenia LOADED, aby poinformować menedżera reklam o rozpoczęciu odtwarzania treści i reklam. Pakiet IMA SDK uruchamia zdarzenie ICON_FALLBACK_IMAGE_CLOSED, gdy użytkownik zamknie okno rezerwowe ikony po kliknięciu ikony. Po tej czynności odtwarzanie reklamy zostanie wznowione.

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

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
  }
}
ViewController.swift

Obsługa błędów

Dodaj też moduł obsługi błędów reklam. Jeśli wystąpi błąd, tak jak w poprzednim kroku, wznow odtwarzanie treści.

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];
}
ViewController.m

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()
}
ViewController.swift

Wywoływanie zdarzeń odtwarzania i wstrzymywania

Ostatnie 2 metody delegowania, które implementujesz, wywołują zdarzenia odtwarzania i wstrzymywania w bazowych treściach wideo, gdy pakiet IMA SDK o nie poprosi. Wywoływanie wstrzymania i odtwarzania, gdy pakiet IMA SDK o to poprosi, zapobiega pomijaniu przez użytkownika fragmentów treści wideo podczas wyświetlania reklam.

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];
}
ViewController.m

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()
}
ViewController.swift

To wszystko. Teraz wysyłasz żądania reklam i wyświetlasz je za pomocą pakietu IMA SDK. Więcej informacji o dodatkowych funkcjach pakietu SDK znajdziesz w innych przewodnikach lub w przykładach na GitHubie.

Następne kroki

Aby zmaksymalizować przychody z reklam na platformie tvOS, poproś o uprawnienia do przejrzystości i śledzenia aplikacji, aby używać identyfikatora IDFA.