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.

Z tego przewodnika dowiesz się, jak zintegrować pakiet IMA SDK z aplikacją odtwarzacza wideo. Jeśli chcesz zobaczyć gotową przykładową integrację lub z niej skorzystać, pobierz BasicExample z GitHub.

Omówienie IMA po stronie klienta

Wdrażanie pakietu IMA SDK po stronie klienta obejmuje 4 główne komponenty SDK, które są opisane w tym przewodniku:

  • IMAAdDisplayContainer: obiekt kontenera, który określa, gdzie IMA renderuje elementy interfejsu reklamy i mierzy widoczność, w tym Widok aktywnyOpen 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

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, wybierając kolejno File > Add Packages... (Plik > Dodaj pakiety...).

  2. W wyświetlonym oknie wyszukaj repozytorium pakietu IMA SDK Swift Package w GitHubie:

    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
    
    
  2. W katalogu zawierającym plik Podfile uruchom polecenie 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: BasicExamplePods (zależności zainstalowane przez CocoaPods).

Ręczne pobieranie i instalowanie pakietu IMA SDK

Jeśli nie chcesz używać CocoaPods, możesz pobrać pakiet IMA SDK i ręcznie dodać go do projektu.

3. Importowanie pakietu IMA SDK

Dodaj platformę IMA za pomocą instrukcji importowania.

Objective-C

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

@import GoogleInteractiveMediaAds;

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

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

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

W tym przykładzie viewDidLoad() inicjuje IMAAdsLoader, a viewDidAppear() wysyła żądanie reklam, gdy widok jest widoczny. Metody pomocnicze showContentPlayer()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 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. Wdrażanie narzędzia do śledzenia pozycji odtwarzania treści i obserwatora końca transmisji

Aby odtwarzać reklamy w trakcie filmu, pakiet IMA SDK musi śledzić bieżącą pozycję treści wideo. Aby to zrobić, utwórz klasę, która implementuje interfejs IMAContentPlayhead. Jeśli używasz AVPlayer, jak pokazano w tym przykładzie, pakiet SDK udostępnia klasę IMAAVPlayerContentPlayhead, która wykonuje to za Ciebie. Jeśli nie używasz AVPlayer, musisz zaimplementować 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];
}

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

Musisz też poinformować pakiet SDK, kiedy odtwarzanie treści się zakończy, aby mógł wyświetlić reklamy po zakończeniu filmu. W tym celu wywołaj funkcję contentComplete na obiekcie IMAAdsLoader, używając 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. Zainicjuj moduł wczytywania reklam i wyślij żądanie reklamy.

Aby poprosić o zestaw reklam, musisz utworzyć instancję IMAAdsLoader. Ten moduł wczytujący może służyć do przetwarzania obiektów IMAAdsRequest powiązanych 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];
}

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. Konfigurowanie delegata modułu wczytywania reklam

Po pomyślnym wczytaniu zdarzenia IMAAdsLoader wywołuje metodę adsLoadedWithData przypisanego delegata, przekazując jej instancję IMAAdsManager. Następnie możesz zainicjować menedżera reklam, który wczytuje poszczególne reklamy zgodnie z odpowiedzią na adres URL tagu reklamy.

Pamiętaj też, aby obsługiwać wszelkie błędy, które mogą wystąpić podczas wczytywania. Jeśli reklamy się nie ładują, upewnij się, że odtwarzanie multimediów jest kontynuowane bez reklam, aby nie zakłócać wrażeń użytkownika.

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. Konfigurowanie delegata menedżera reklam

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

Rozpoczynanie odtwarzania

Metoda didReceiveAdEvent może służyć do obsługi wielu zdarzeń. 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 wywołuje 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;
  }
}

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

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

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

Wywoływanie zdarzeń odtwarzania i wstrzymywania

Ostatnie 2 metody delegowania, które musisz zaimplementować, służą do wywoływania zdarzeń odtwarzania i wstrzymywania w bazowych treściach wideo, gdy zażąda tego pakiet IMA SDK. Wstrzymywanie i odtwarzanie na żądanie 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];
}

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

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.