Configura l'SDK IMA

Seleziona la piattaforma: HTML5 Android iOS tvOS

Gli SDK IMA semplificano l'integrazione di annunci multimediali nei tuoi siti web e nelle tue app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server compatibile con VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK lato client IMA, mantieni il controllo della riproduzione dei video dei contenuti, mentre l'SDK gestisce la riproduzione degli annunci. Gli annunci vengono riprodotti in un video player separato posizionato sopra il video player dei contenuti dell'app.

Questa guida mostra come integrare l'SDK IMA in un'app video player. Se vuoi visualizzare o seguire un esempio di integrazione completato, scarica BasicExample da GitHub.

Panoramica lato client di IMA

L'implementazione di IMA lato client prevede quattro componenti principali dell'SDK, che sono illustrati in questa guida:

  • IMAAdDisplayContainer: Un oggetto contenitore che specifica dove IMA esegue il rendering degli elementi dell'interfaccia utente dell'annuncio e misura la visibilità, inclusi Visualizzazione attiva e Open Measurement.
  • IMAAdsLoader: Un oggetto che richiede annunci e gestisce gli eventi dalle risposte alle richieste di annunci. Devi istanziare un solo caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.
  • IMAAdsRequest: Un oggetto che definisce una richiesta di annunci. Le richieste di annunci specificano l'URL del tag annuncio VAST, nonché parametri aggiuntivi, come le dimensioni dell'annuncio.
  • IMAAdsManager: Un oggetto che contiene la risposta alla richiesta di annunci, controlla la riproduzione degli annunci e ascolta gli eventi degli annunci attivati dall'SDK.

Prerequisiti

Prima di iniziare, devi disporre di quanto segue:

1. Crea un nuovo progetto Xcode

In Xcode, crea un nuovo progetto tvOS utilizzando Objective-C o Swift. Utilizza BasicExample come nome del progetto.

2. Aggiungi l'SDK IMA al progetto Xcode

Installare l'SDK IMA utilizzando Swift Package Manager

L'SDK Interactive Media Ads supporta Swift Package Manager a partire dalla versione 4.8.2. Segui i passaggi riportati di seguito per importare il pacchetto Swift.

  1. In Xcode, installa il pacchetto Swift dell'SDK IMA andando a File > Add Packages… (File > Aggiungi pacchetti…).

  2. Nel prompt visualizzato, cerca il repository GitHub del pacchetto Swift dell'SDK IMA:

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

  3. Seleziona la versione del pacchetto Swift dell'SDK IMA che vuoi utilizzare. Per i nuovi progetti, ti consigliamo di utilizzare l'opzione Fino alla prossima versione principale.

Al termine, Xcode risolve le dipendenze del pacchetto e le scarica in background. Per maggiori dettagli su come aggiungere dipendenze del pacchetto, consulta l'articolo di Apple.

Installare l'SDK IMA utilizzando CocoaPods

Per installare l'SDK IMA, utilizza CocoaPods. Per ulteriori informazioni sull'installazione o l'utilizzo di CocoaPods, consulta la documentazione di CocoaPods. Dopo aver installato CocoaPods, procedi nel seguente modo:

  1. Nella stessa directory del file BasicExample.xcodeproj, crea un file di testo denominato Podfile e aggiungi la seguente configurazione:

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

platform :tvos, '15'

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

    Podfile

  2. Dalla directory che contiene il Podfile, esegui pod install --repo-update

  3. Verifica che l'installazione sia andata a buon fine aprendo il file BasicExample.xcworkspace e confermando che contenga due progetti: BasicExample e Pods (le dipendenze installate da CocoaPods).

Download e installazione manuali dell'SDK IMA

Se non vuoi utilizzare CocoaPods, puoi scaricare l'SDK IMA e aggiungerla manualmente al tuo progetto.

3. Importa l'SDK IMA

Aggiungi il framework IMA utilizzando un'istruzione di importazione.

Objective-C

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

@import GoogleInteractiveMediaAds;
ViewController.m

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

ViewController.swift

4. Crea un video player e integra l'SDK IMA

L'esempio seguente inizializza l'SDK IMA:

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

In questo esempio, viewDidLoad() inizializza IMAAdsLoader e viewDidAppear() richiede gli annunci una volta che la visualizzazione è visibile. I metodi helper showContentPlayer() e hideContentPlayer() attivano/disattivano la visibilità dei contenuti durante la riproduzione dell'annuncio.

Questo esempio utilizza la variabile costante adTagURLString per definire il tag annuncio VAST per la richiesta di annuncio e i seguenti componenti per gestire l'SDK IMA:

  • adsLoader: gestisce le richieste e le risposte degli annunci. Ti consigliamo di utilizzare una singola istanza per il ciclo di vita dell'app.
  • adDisplayContainer: specifica la visualizzazione per il rendering degli annunci.
  • adsManager: gestisce la riproduzione degli annunci e ascolta gli eventi pubblicitari.
  • contentPlayhead: monitora l'avanzamento dei contenuti per attivare le interruzioni pubblicitarie mid-roll.
  • adBreakActive: indica se è in corso la riproduzione di un'interruzione pubblicitaria per evitare di saltare gli annunci.

5. Implementare il tracker della testina di riproduzione dei contenuti e l'osservatore della fine dello stream

Per riprodurre gli annunci mid-roll, l'SDK IMA deve monitorare la posizione attuale dei tuoi contenuti video. Per farlo, crea una classe che implementi IMAContentPlayhead. Se utilizzi un AVPlayer, come mostrato in questo esempio, l'SDK fornisce la classe IMAAVPlayerContentPlayhead che esegue questa operazione per te. Se non utilizzi AVPlayer, devi implementare IMAContentPlayhead in una classe di tua proprietà.

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

Devi anche comunicare all'SDK quando la riproduzione dei contenuti è terminata, in modo che possa mostrare gli annunci post-roll. Questa operazione viene eseguita chiamando contentComplete su IMAAdsLoader, utilizzando 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];
}
ViewController.m

Swift

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

6. Inizializza il caricatore di annunci ed effettua una richiesta di annunci

Per richiedere un insieme di annunci, devi creare un'istanza IMAAdsLoader. Questo caricatore può essere utilizzato per elaborare gli oggetti IMAAdsRequest associati a un URL tag annuncio specificato.

Come best practice, mantieni una sola istanza di IMAAdsLoader per l'intero ciclo di vita della tua app. Per effettuare richieste di annunci aggiuntive, crea un nuovo oggetto IMAAdsRequest, ma riutilizza lo stesso IMAAdsLoader. Per ulteriori informazioni, consulta le domande frequenti sull'SDK IMA.

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. Configurare un delegato del caricatore di annunci

In caso di evento di caricamento riuscito, IMAAdsLoader chiama il metodo adsLoadedWithData del suo delegato assegnato, passandogli un'istanza di IMAAdsManager. A questo punto puoi inizializzare Ads Manager, che carica i singoli annunci, come definito dalla risposta all'URL del tag annuncio.

Inoltre, assicurati di gestire eventuali errori che potrebbero verificarsi durante il caricamento. Se gli annunci non vengono caricati, assicurati che la riproduzione dei contenuti multimediali continui senza annunci, in modo da non interferire con l'esperienza dell'utente.

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. Configurare un delegato di Ads Manager

Infine, per gestire gli eventi e le modifiche di stato, il responsabile degli annunci ha bisogno di un proprio delegato. IMAAdManagerDelegate ha metodi per gestire eventi ed errori degli annunci, nonché metodi per attivare la riproduzione e la pausa dei contenuti video.

Avvio della riproduzione

Esistono molti eventi che possono essere gestiti con il metodo didReceiveAdEvent. Per questo esempio di base, ascolta l'evento LOADED per indicare all'Ad Manager di avviare la riproduzione di contenuti e annunci. L'SDK IMA attiva l'evento ICON_FALLBACK_IMAGE_CLOSED quando l'utente chiude una finestra di dialogo di fallback dell'icona dopo aver toccato un'icona. Dopo questa azione, la riproduzione dell'annuncio riprende.

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

Gestione degli errori

Aggiungi anche un gestore per gli errori degli annunci. Se si verifica un errore, come nel passaggio precedente, riprendi la riproduzione dei contenuti.

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

Attivazione di eventi di riproduzione e pausa

Gli ultimi due metodi delegati che devi implementare vengono utilizzati per attivare gli eventi di riproduzione e pausa sui contenuti video sottostanti, quando richiesto dall'SDK IMA. L'attivazione della pausa e della riproduzione su richiesta impedisce all'utente di perdere parti dei contenuti video durante la visualizzazione degli annunci.

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

È tutto. Ora richiedi e visualizzi gli annunci con l'SDK IMA. Per scoprire di più sulle funzionalità aggiuntive dell'SDK, consulta le altre guide o gli esempi su GitHub.

Passaggi successivi

Per massimizzare le entrate pubblicitarie sulla piattaforma tvOS, richiedi l'autorizzazione App Tracking Transparency per utilizzare l'IDFA.