Iniziare a utilizzare l'SDK IMA DAI

Gli SDK IMA semplificano l'integrazione degli annunci multimediali nei siti web e nelle app. Gli SDK IMA possono richiedi annunci da qualsiasi ad server compatibile con VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK IMA DAI, le app richiesta di streaming per annunci e contenuti video, sia VOD che contenuti dal vivo. L'SDK restituisce quindi video stream combinati, in modo che non sia necessario gestire il passaggio dall'annuncio ai video di contenuti e viceversa all'interno dell'app.

Seleziona la soluzione DAI che ti interessa

DAI servizio completo

Questa guida illustra come integrare l'SDK IMA DAI in un semplice video player dell'app. Se vuoi visualizzare o seguire un campione completo integrazione, scarica BasicExample da GitHub.

Panoramica dell'IMA DAI

L'implementazione dell'IMA DAI coinvolge tre componenti principali dell'SDK, come illustrato in guida:

  • IMAAdDisplayContainer: Un oggetto contenitore posizionato sopra l'elemento di riproduzione video e che ospita gli elementi dell'interfaccia utente dell'annuncio.
  • IMAAdsLoader: Un oggetto che richiede flussi di dati e gestisce gli eventi attivati dagli oggetti di risposta alla richiesta di flusso. Devi creare un'istanza solo per un caricatore di annunci, che può essere riutilizzato durante il ciclo di vita un'applicazione.
  • IMAStreamRequest: un IMAVODStreamRequest o un IMALiveStreamRequest: Un oggetto che definisce una richiesta di flusso. Le richieste di streaming possono riguardare video on demand o live i flussi di dati. Le richieste specificano un ID contenuti, una chiave API o un token di autenticazione e altre parametri.
  • IMAStreamManager: Un oggetto che gestisce i flussi di inserimento di annunci dinamici e le interazioni con il backend DAI. La Stream Manager gestisce anche i ping di monitoraggio e inoltra gli eventi di streaming e annuncio ai publisher.

Prerequisiti

Prima di iniziare, è necessario quanto segue:

Crea un nuovo progetto Xcode

In Xcode, crea un nuovo progetto tvOS utilizzando Objective-C. Utilizza BasicExample come il 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 modello per installare l'SDK IMA DAI. Per ulteriori informazioni sull'installazione o l'utilizzo Consulta la documentazione di CocoaPods. Una volta Se hai installato CocoaPods, segui le istruzioni riportate di seguito 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.13.0'
end

  2. Dalla directory che contiene il podfile, esegui:

    pod install --repo-update`

  3. Verifica che l'installazione sia riuscita aprendo il BasicExample.xcworkspace e conferma che contenga due projects: BasicExample e Pods (le dipendenze installate CocoaPods).

Installa l'SDK utilizzando il gestore pacchetti Swift

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

  1. In Xcode, installa il pacchetto Swift GoogleInteractiveMediaAds accedendo a File > Aggiungi pacchetti.

  2. Nella richiesta visualizzata, cerca GoogleInteractiveMediaAds Swift. Pacchettizzazione del repository GitHub:

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

  3. Seleziona la versione del pacchetto Swift GoogleInteractiveMediaAds che vuoi utilizzare. Per nuovi progetti, consigliamo di utilizzare la versione principale fino alla successiva.

Al termine, Xcode risolve le dipendenze dei pacchetti e le scarica sullo sfondo. Per maggiori dettagli su come aggiungere dipendenze dei pacchetti, consulta Mela .

Scaricare e installare manualmente l'SDK

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

Creare un video player semplice

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

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

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

Crea quindi un'istanza IMAAdsLoader e collega la vista del contenitore di annunci al la gerarchia di visualizzazione.

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

Inviare una richiesta di streaming

Creare alcune costanti per contenere le informazioni del flusso, quindi implementare il di richiesta flusso di dati 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 incendio IMAAdsLoader e IMAStreamManager utilizzati per gestire l'inizializzazione, gli errori e le modifiche dello stato del flusso. Questi eventi vengono attivati i protocolli IMAAdsLoaderDelegate e IMAStreamManagerDelegate. Ascolta un evento caricato di annunci e inizializzare lo stream. Se un annuncio non si carica, riproduci lo 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 il logging e gli eventi di errore

Esistono diversi eventi che possono essere gestiti dal delegato del gestore dello stream, per le implementazioni di base, gli usi più importanti sono l'esecuzione del logging degli eventi, per impedire azioni di ricerca durante la riproduzione degli annunci e per gestire gli 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 mostri gli annunci con l'SDK IMA DAI. Per apprendere sulle funzioni più avanzate dell'SDK, consulta le altre guide o su GitHub.