Iniziare a utilizzare l'SDK IMA DAI

Gli SDK IMA semplificano l'integrazione degli annunci multimediali nei tuoi siti web e nelle tue app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server conforme a VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK IMA DAI, le app inviano una richiesta di streaming per gli annunci e i video di contenuti, sia VOD che dal vivo. L'SDK restituisce quindi un stream video combinato, in modo da non dover gestire il passaggio tra annunci e video di contenuti all'interno della tua app.

Seleziona la soluzione DAI che ti interessa

DAI con servizio completo

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

Panoramica dell'IMA DAI

L'implementazione di IMA DAI prevede quattro 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 stream e gestisce gli eventi attivati dagli oggetti di risposta alla richiesta di stream. Devi creare un'istanza di un solo caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.
  • IMAStreamRequest: un valore IMAVODStreamRequest o IMALiveStreamRequest. Un oggetto che definisce una richiesta di stream. Le richieste di stream possono riguardare video on demand o live streaming. Le richieste specificano un ID contenuto, nonché 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 stream gestisce anche i ping di monitoraggio e inoltra gli eventi relativi allo stream e agli annunci al publisher.

Prerequisiti

Prima di iniziare, devi disporre di quanto segue:

Creare un nuovo progetto Xcode

In Xcode, crea un nuovo progetto iOS 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 utilizzando CocoaPods, consulta la documentazione di CocoaPods. Dopo il giorno hai installato CocoaPods, segui queste istruzioni per installare l'SDK IMA DAI:

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

    source 'https://github.com/CocoaPods/Specs.git'
    platform :ios, '14'
    target "BasicExample" do
      pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0'
    end
    
  2. Dalla directory che contiene il file Podfile, esegui:

    pod install --repo-update`
  3. Verifica che l'installazione sia andata a buon fine aprendo il file BasicExample.xcworkspace e conferma che contenga due progetti: 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 3.18.4. Segui i seguenti passaggi per importare il pacchetto Swift.

  1. In Xcode, installa il pacchetto Swift dell'SDK IMA DAI accedendo a File > Aggiungi pacchetti.

  2. Nella richiesta visualizzata, cerca il repository GitHub del pacchetto Swift dell'SDK IMA DAI:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
    
  3. Seleziona la versione del pacchetto Swift dell'SDK IMA DAI 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 Articolo di Apple.

Scaricare e installare manualmente l'SDK

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

Creare 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 progetto, importa l'SDK e aggiungi gli stub per i punti di interazione principali 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

Implementare l'IMAAdsLoader

Poi, esegui l'inizializzazione di IMAAdsLoader e associa la visualizzazione del contenitore degli 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;
}

Inviare una richiesta di streaming

Crea alcune costanti per contenere le informazioni sullo stream e poi implementa la funzione di richiesta dello stream 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 stream

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 di caricamento degli annunci e inizializza 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. A per saperne di più sulle funzioni avanzate dell'SDK, consulta le altre guide o su GitHub.