Questa pagina è stata tradotta dall'API Cloud Translation.

Iniziare a utilizzare l'SDK IMA 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 annunci e contenuti video, VOD o contenuti dal vivo. L'SDK restituisce quindi un video stream combinato, in modo che tu non debba gestire il passaggio tra l'annuncio e i contenuti video all'interno dell'app.

Seleziona la soluzione DAI che ti interessa

DAI servizio completo

Questa guida illustra come integrare l'SDK IMA in una semplice app per video player. Per visualizzare o seguire un'integrazione di esempio completa, scarica BasicExample da GitHub.

Panoramica dell'IMA DAI

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

IMAAdDisplayContainer: un oggetto contenitore che si trova sopra l'elemento di riproduzione video e ospita gli elementi dell'interfaccia utente dell'annuncio.
IMAAdsLoader: un oggetto che richiede flussi e gestisce eventi attivati dagli oggetti risposta alla richiesta di flusso. Devi creare un solo caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.
IMAStreamRequest: IMAVODStreamRequest o IMALiveStreamRequest: un oggetto che definisce una richiesta di flusso. Le richieste di streaming possono riguardare video on demand o live streaming. Le richieste specificano un Content ID, una chiave API o un token di autenticazione e altri parametri.
IMAStreamManager: un oggetto che gestisce gli stream di inserimento di annunci dinamici e le interazioni con il backend DAI. Il gestore dello streaming gestisce anche i ping di monitoraggio e inoltra gli eventi live e degli annunci al publisher.

Prerequisiti

Prima di iniziare, occorre quanto segue:

Xcode 13 o versioni successive
CocoaPods (opzione preferita), Swift Package Manager o una copia scaricata dell'SDK IMA per tvOS

Crea un nuovo progetto Xcode

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

Aggiungere l'SDK IMA al progetto Xcode

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

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. Per ulteriori informazioni sull'installazione o sull'utilizzo di CocoaPods, consulta la documentazione di CocoaPods. Dopo aver installato CocoaPods, segui queste istruzioni per installare l'SDK IMA:

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.12.0'
end

Dalla directory che contiene il podfile, esegui:
```
pod install --repo-update`
```
Verifica che l'installazione sia riuscita aprendo il file BasicExample.xcworkspace e confermando che contiene 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.

In Xcode, installa il pacchetto Swift dell'SDK IMA selezionando File > Aggiungi pacchetti.

Nel prompt visualizzato, cerca il repository GitHub del pacchetto SDK IMA:

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

Seleziona la versione dell'SDK IMA SDK Swift che vuoi utilizzare. Per i nuovi progetti, consigliamo di utilizzare la versione principale Fino alla prossima versione.

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

Scaricare e installare manualmente l'SDK

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

Mostra istruzioni

Dalla pagina di download IMA per tvOS, scarica ed estrai la versione più recente dell'SDK IMA per tvOS.
Apri BasicExample.xcodeproj.
Nel riquadro a sinistra, fai clic sul nome del progetto.
Nel riquadro centrale, fai clic su Fasi di creazione.
Espandi la sezione Collega file binario alle librerie.
In fondo all'elenco delle librerie, fai clic sull'icona con il segno più [+].
Fai clic su Aggiungi altro.
Nella directory in cui hai estratto l'SDK scaricato, seleziona GoogleInteractiveMediaAds.framework e fai clic su Apri.
In fondo all'elenco delle librerie, fai di nuovo clic sull'icona con il segno più [+].
Nella colonna Stato, verifica che GoogleInteractiveMediaAds.framework sia impostato su Required.
Includi il flag del linker -ObjC nelle impostazioni della build. Per maggiori informazioni, consulta Apple QA1490.

Creare un video player semplice

Innanzitutto, implementa un video player di base. Inizialmente, questo player non utilizza l'SDK IMA e non 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

Importare l'SDK e aggiungere stub per l'interazione IMA

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

Implementare IMAAdsLoader

A questo punto, crea un'istanza di IMAAdsLoader e collega la vista del contenitore di annunci 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;
}

Invia una richiesta di streaming

Creare alcune costanti per contenere le informazioni del flusso, quindi implementare 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";

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

Gestire gli eventi di streaming

Gli eventi di attivazione IMAAdsLoader e IMAStreamManager utilizzati per gestire l'inizializzazione, gli errori e le modifiche dello stato del flusso. Questi eventi vengono attivati sui protocolli IMAAdsLoaderDelegate e IMAStreamManagerDelegate. Ascolta un evento di annunci caricati e inizializza lo stream. Se non riesci a caricare un annuncio, 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 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 ed errore

Il delegato del gestore dello stream può gestire diversi eventi. Tuttavia, per le implementazioni di base, gli utilizzi più importanti sono l'esecuzione del logging degli eventi, l'impossibilità di eseguire 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. Per scoprire di più sulle funzionalità più avanzate dell'SDK, consulta le altre guide o gli esempi su GitHub.