Inizia

Gli SDK IMA ti consentono di integrare facilmente gli 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 inviano una richiesta di streaming per annunci e contenuti video, VOD o contenuti in diretta. L'SDK restituisce quindi un video stream combinato, in modo che tu non debba gestire il passaggio da un annuncio all'altro all'interno della tua app.

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

Panoramica dell'IMA DAI

L'implementazione dell'inserimento di annunci dinamici IMA prevede tre componenti SDK principali, illustrati in questa guida:

  • IMAAdDisplayContainer: un oggetto contenitore posizionato sopra l'elemento di riproduzione del video e che ospita gli elementi dell'interfaccia utente dell'annuncio.
  • IMAAdsLoader: un oggetto che richiede flussi e gestisce gli eventi attivati dagli oggetti risposta delle richieste di streaming. Devi creare un'unica istanza del caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.
  • IMAStreamRequest: IMAVODStreamRequest o IMALiveStreamRequest: un oggetto che definisce una richiesta di streaming. Le richieste di stream possono essere video on demand o live streaming. Le richieste specificano un ID contenuto, una chiave API o un token di autenticazione e altri parametri.
  • IMAStreamManager: un oggetto che gestisce i flussi di inserimento di annunci dinamici e le interazioni con il backend DAI. Inoltre, gestisce i ping di monitoraggio e inoltra gli eventi in streaming e gli annunci al publisher.

Prerequisiti

Prima di iniziare, assicurati di disporre di:

1. Crea un nuovo progetto Xcode

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

2. Aggiungi l'SDK IMA al progetto Xcode

Installare l'SDK utilizzando CocoaPods (opzione preferita)

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

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

    source 'https://github.com/CocoaPods/Specs.git'
    platform :tvos, '10'
    target "BasicExample" do
      pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.2'
    end
    
  2. Dalla directory che contiene il podfile, esegui pod install --repo-update

  3. Verifica che l'installazione sia riuscita aprendo il file BaseExample.xcworkspace e verificando che contenga due progetti: BaseExample e Pod (le dipendenze installate da CocoaPods).

Scaricare e installare manualmente l'SDK

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

3. Creare un video player semplice

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

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

Una volta aggiunto l'SDK IMA al progetto, importa l'SDK e aggiungi gli 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

5. Implementare IMAAdsLoader

Quindi, crea un'istanza IMAAdsLoader e collega la visualizzazione del contenitore di annunci alla 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;
}
...

6. Inviare una richiesta di streaming

Creare alcune costanti per contenere le informazioni del flusso e implementare la funzione di richiesta di streaming per effettuare la richiesta.

ViewController.m

...
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
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];
}
...

7. Gestire gli eventi di streaming

Gli eventi di attivazione IMAAdsLoader e IMAStreamManager utilizzati per gestire l'inizializzazione, gli errori e le modifiche allo stato del flusso. Questi eventi vengono attivati nei protocolli IMAAdsLoaderDelegate e IMAStreamManagerDelegate. Monitora un evento caricato dagli annunci e inizializza il flusso. Se un annuncio non viene caricato, riproduci uno stream di backup.

ViewController.m

...
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
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

8. Gestire eventi di logging ed errore

La delega per la gestione dei flussi può gestire diversi eventi; tuttavia, per le implementazioni di base, gli utilizzi più importanti sono eseguire il logging degli eventi, impedire azioni di ricerca durante la riproduzione degli annunci e 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.
      self.playerViewController.requiresLinearPlayback = YES;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow users to seek through after an ad ends.
      self.playerViewController.requiresLinearPlayback = NO;
      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 informazioni sulle funzionalità più avanzate dell'SDK, consulta le altre guide o gli esempi su GitHub.

Passaggi successivi

Per massimizzare le entrate pubblicitarie sulla piattaforma tvOS, richiedi l'autorizzazione di monitoraggio e trasparenza dell'app per utilizzare l'IDFA.