Configurare l'SDK IMA per DAI

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 IMA DAI, le app effettuano una richiesta di streaming per l'annuncio e il video dei contenuti, che possono essere VOD o live. L'SDK restituisce quindi uno stream video combinato, in modo da non dover gestire il passaggio tra l'annuncio e il video di contenuti all'interno dell'app.

Seleziona la soluzione DAI che ti interessa

DAI con servizio completo

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

Panoramica di IMA DAI

L'implementazione di IMA DAI prevede tre componenti SDK principali, come illustrato in questa guida:

  • IMAAdDisplayContainer: Un oggetto contenitore che si trova sopra l'elemento di riproduzione video e contiene gli elementi dell'interfaccia utente dell'annuncio.
  • IMAAdsLoader: Un oggetto che richiede flussi e gestisce gli eventi attivati dagli oggetti di risposta alla richiesta di flusso. Devi creare un solo caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.
  • IMAStreamRequest: un IMAVODStreamRequest o un IMALiveStreamRequest: un oggetto che definisce una richiesta di stream. Le richieste di stream possono riguardare video on demand o live streaming. Le richieste di live streaming specificano una chiave asset, mentre le richieste VOD specificano un ID CMS e un ID video. Entrambi i tipi di richiesta possono includere facoltativamente una chiave API necessaria per accedere agli stream specificati e un codice di rete Google Ad Manager per l'SDK IMA per gestire gli identificatori pubblicità come specificato nelle impostazioni di Google Ad Manager.
  • IMAStreamManager: Un oggetto che gestisce i flussi di inserimento di annunci dinamici e le interazioni con il backend DAI. Lo stream manager gestisce anche i ping di monitoraggio e inoltra gli eventi di stream e annunci al publisher.

Prerequisiti

Prima di iniziare, devi disporre di quanto segue:

Crea un nuovo progetto Xcode

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

Aggiungi l'SDK IMA DAI al progetto Xcode

Utilizza uno di questi tre metodi per installare l'SDK IMA DAI.

Installa l'SDK utilizzando CocoaPods (opzione preferita)

CocoaPods è un gestore delle dipendenze per i progetti Xcode ed è il metodo consigliato per installare l'SDK IMA DAI. Per ulteriori informazioni sull'installazione o sull'utilizzo di CocoaPods, consulta la documentazione di CocoaPods. Una volta installato CocoaPods, segui queste istruzioni per installare l'SDK IMA DAI:

  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, '14'
target "BasicExample" do
  pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.15.1'
end

  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).

Installa l'SDK utilizzando Swift Package Manager

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

  1. In Xcode, installa il pacchetto Swift GoogleInteractiveMediaAds andando su File > Add Packages (File > Aggiungi pacchetti).

  2. Nel prompt visualizzato, cerca il repository GitHub del pacchetto Swift GoogleInteractiveMediaAds:

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

  3. Seleziona la versione del pacchetto Swift GoogleInteractiveMediaAds 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 le dipendenze del pacchetto, consulta l'articolo di Apple.

Download e installazione manuali dell'SDK

Se non vuoi utilizzare Swift Package Manager o CocoaPods, puoi scaricare l'SDK IMA DAI e aggiungerlo manualmente al tuo progetto.

Crea un video player semplice

Innanzitutto, implementa un video player di base. Inizialmente, questo player non utilizza l'SDK IMA DAI né contiene alcun metodo per attivare la riproduzione.

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

Importa l'SDK e aggiungi stub per l'interazione con IMA

Dopo aver aggiunto l'SDK IMA DAI al tuo progetto, importa l'SDK e aggiungi stub per i punti principali dell'interazione con 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

Implementa IMAAdsLoader

Successivamente, crea un'istanza di IMAAdsLoader e collega la visualizzazione del contenitore dell'annuncio alla gerarchia delle visualizzazioni.

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

Effettuare una richiesta di stream

Crea alcune costanti per contenere le informazioni sul flusso e poi implementa la funzione di richiesta del flusso per effettuare la richiesta.

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";
static NSString *const kNetworkCode = @"21775744923";

@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
                                                                     networkCode:kNetworkCode
                                                              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
  //                                              networkCode:kNetworkCode
  //                                       adDisplayContainer:adDisplayContainer
  //                                             videoDisplay:videoDisplay];
  [self.adsLoader requestStreamWithRequest:request];
}

Gestire gli eventi di stream

IMAAdsLoader e IMAStreamManager attivano eventi utilizzati per gestire l'inizializzazione, gli errori e le modifiche dello stato dello stream. Questi eventi vengono attivati tramite i protocolli IMAAdsLoaderDelegate e IMAStreamManagerDelegate. Ascolta un evento di caricamento degli annunci e inizializza lo stream. Se un annuncio non viene caricato, riproduci uno stream di backup.

ViewController.m

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";
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

Gestire gli eventi di logging e di errore

Esistono diversi eventi che possono essere gestiti dal delegato del gestore di stream, ma per le implementazioni di base, gli utilizzi più importanti sono l'esecuzione della registrazione degli eventi, la prevenzione delle azioni di ricerca durante la riproduzione degli annunci e la gestione degli errori.

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

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