Utilizzare l'SDK IMA DAI su iOS

Riproduci gli stream VOD registrati con l'API Google Cloud Video Stitcher

Questa guida mostra come utilizzare l'SDK IMA DAI per iOS per richiedere e riprodurre una sessione di streaming VOD di Google Cloud.

Questa guida amplia l'esempio di base riportato nella guida introduttiva per l'IMA DAI.

Per informazioni sull'integrazione con altre piattaforme o sull'utilizzo degli SDK lato client IMA, consulta SDK Interactive Media Ads.

Se vuoi visualizzare o seguire un'integrazione di esempio completata, scarica l'esempio di Video Stitcher di Cloud per Objective-C o Swift.

Nota: Apple fornisce solo framework per supportare HTTP Live Streaming (HLS), come AVKit, AVFoundation e WebKit. Questi framework non funzionano con il formato dello stream DASH.

Configura un progetto Google Cloud

Inserisci le seguenti variabili da utilizzare nell'SDK IMA:

Località

La regione Google Cloud in cui è stata creata la configurazione VOD: LOCATION

Numero progetto

Il numero del progetto Google Cloud che utilizza l'API Video Stitcher: PROJECT_NUMBER

Token OAuth

Il token OAuth a breve termine di un account di servizio con il ruolo utente Video Stitcher:

OAUTH_TOKEN

Scopri di più sulla creazione di token OAuth di breve durata. Il token OAuth può essere riutilizzato in più richieste, a condizione che non sia scaduto.

Codice di rete

Il codice di rete Ad Manager per la richiesta di annunci: NETWORK_CODE

ID configurazione VOD

L'ID configurazione VOD per lo stream VOD: VOD_CONFIG_ID

Scopri di più sulla creazione dell'ID di configurazione VOD nella guida alla creazione di una configurazione VOD per l'unione in cloud.

Contesto utente

Il contesto utente per le richieste di monitoraggio. Può essere nil. Il valore predefinito in questa guida è nil.

Configurare l'esempio di base

Vai alla pagina di GitHub della release di IMA iOS DAI e scarica l'esempio di base in Objective-C. Questo esempio è un progetto Xcode per iOS che si basa su Cocoapods per caricare l'SDK IMA DAI. Se utilizzi Swift, IMA non ha un'app di esempio per iOS, ma consulta lo snippet di codice Swift più avanti in questa guida per scoprire come implementare un IMAVideoStitcherVODStreamRequest nella tua app.

Importante: è necessario l'SDK DAI IMA v3.23.0 o versioni successive. Aggiorna il file pod in base alle esigenze.

Per preparare l'esecuzione del sample, assicurati che CocoaPods sia installato, quindi apri la cartella dell'esempio di base nel terminale ed esegui il seguente comando:

pod install --repo-update

Al termine del comando, nella cartella del progetto viene visualizzato un file denominato BasicExample.xcworkspace. Apri questo file in Xcode ed esegui l'esempio per assicurarti che il video di test e gli annunci vengano riprodotti come previsto.

Richiedere uno stream VOD

Per sostituire lo stream di esempio con lo stream VOD con annunci uniti, utilizza IMAVideoStitcherVODStreamRequest per creare una sessione di annunci con Google Ad Manager. Puoi utilizzare l'interfaccia utente di Google Ads Manager per individuare le sessioni DAI generate per il monitoraggio e il debug.

Nel sample esistente sono presenti esempi per richiedere uno stream VOD o un live streaming dai server DAI di Google. Per farlo funzionare con l'API Video Stitcher di Google Cloud, devi sostituire la funzione requestStream attuale con una che utilizzi la classe IMAVideoStitcherVODStreamRequest.

Ecco un esempio:

Objective-C

ViewController.m

...

#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
/// The Stream's VOD config ID.
static NSString *const kVODConfigID = @"VOD_CONFIG_ID";
/// The Network Code used by the Video Stitcher API.
static NSString *const kNetworkCode = @"NETWORK_CODE";
/// The Google Cloud project using the Video Stitcher API.
static NSString *const kProjectNumber = @"PROJECT_NUMBER";
/// The Google Cloud region containing your project.
static NSString *const kLocation = @"LOCATION";
/// An OAuth Token created by a Google Cloud account with Video Stitcher API
/// permissions.
static NSString *const kOAuthToken = @"OAUTH_TOKEN";

/// Fallback URL in case something goes wrong in loading the stream. If all goes well, this will not
/// be used.
static NSString *const kBackupStreamURLString =
    @"http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/"
    @"master.m3u8";
@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>

...

- (void)requestStream {
    // Create an ad display container for ad rendering.
    IMAAdDisplayContainer *adDisplayContainer =
        [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                            viewController:self
                                            companionSlots:nil];
    // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
    IMAAVPlayerVideoDisplay *imaVideoDisplay =
        [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.contentPlayer];
    IMAVideoStitcherVODStreamRequest *streamRequest =
        [[IMAVideoStitcherVODStreamRequest alloc] initWithVODConfigID:kVODConfigID
                                                             region:kLocation
                                                      projectNumber:kProjectNumber
                                                         OAuthToken:kOAuthToken
                                                        networkCode:kNetworkCode
                                                 adDisplayContainer:adDisplayContainer
                                                       videoDisplay:imaVideoDisplay
                                                        userContext:nil
                                        videoStitcherSessionOptions:nil];
    [self.adsLoader requestStreamWithRequest:streamRequest];
}

...

Swift

ViewController.swift

...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAStreamManagerDelegate {
  /// The Stream's VOD config ID.
  static let vodConfigID = "VOD_CONFIG_ID"
  /// The Network Code used by the Video Stitcher API.
  static let networkCode = "NETWORK_CODE"
  /// The Google Cloud project using the Video Stitcher API.
  static let projectNumber = "PROJECT_NUMBER"
  /// The Google Cloud region containing your project.
  static let location = "LOCATION"
  /// An OAuth Token created by a Google Cloud account with Video Stitcher API
  /// permissions.
  static let oAuthToken = "OAUTH_TOKEN"

  /// Fallback URL in case something goes wrong in loading the stream. If all goes well, this will
  /// not be used.
  static let backupStreamURLString = """
    http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/\
    bbb-,480p,720p,1080p,.mov.csmil/master.m3u8
    """

  ...

  func requestStream() {
    // Create an ad display container for ad rendering.
    adDisplayContainer = IMAAdDisplayContainer(
      adContainer: videoView,
      viewController: self,
      companionSlots: nil)
    // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
    let imaVideoDisplay = IMAAVPlayerVideoDisplay(avPlayer: contentPlayer!)
    // Create a VOD stream request.
    let streamRequest = IMAVideoStitcherVODStreamRequest(
      VODConfigID: ViewController.vodConfigID,
      region: ViewController.location,
      projectNumber: ViewController.projectNumber,
      oAuthToken: ViewController.oAuthToken,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: imaVideoDisplay,
      userContext: nil,
      videoStitcherSessionOptions: nil)
    adsLoader?.requestStream(with: streamRequest)
  }

  ...

Esegui il progetto, quindi puoi richiedere e riprodurre lo stream VOD personalizzato.

(Facoltativo) Aggiungi opzioni per la sessione di streaming

Personalizza la richiesta di stream aggiungendo opzioni di sessione per eseguire l'override della configurazione predefinita dell'API Cloud Video Stitcher compilando il parametro videoStitcherSessionOptions nella richiesta IMAVideoStitcherVODStreamRequest. Se fornisci un'opzione non riconosciuta, l'API Cloud Video Stitcher risponderà con un errore HTTP 400. Per assistenza, consulta la guida alla risoluzione dei problemi.

Ad esempio, puoi sostituire le opzioni manifest con lo snippet di codice seguente, che richiede due manifest di stream con le rappresentazioni ordinate dalla maggiore alla minore velocità in bit.

Objective-C

 // Define session options JSON string.
 // The following session options are examples. Use session options
 // that are compatible with your video stream.
 NSString *sessionOptionsStr =
   @"{"
   "  \"manifestOptions\": {"
   "    \"includeRenditions\":["
   "      {\"bitrateBps\": 3000, \"codecs\": \"hvc1.1.4.L126.B0, mp4a.40.2\"},"
   "      {\"bitrateBps\": 2000, \"codecs\": \"avc1.64001f, mp4a.40.2\"},"
   "    ]"
   "  }"
   "}";
 // convert JSON NSString to NSDictionary
 NSData *sessionOptionsData = [sessionOptionsStr dataUsingEncoding:NSUTF8StringEncoding];
 NSError *error = nil;
 NSDictionary *sessionOptions = [NSJSONSerialization
                       JSONObjectWithData:sessionOptionsData
                       options:0
                       error:&error];
 // make stream request
 IMAVideoStitcherVODStreamRequest *streamRequest =
     [[IMAVideoStitcherVODStreamRequest alloc] initWithVODConfigID:kVODConfigID
                                                           region:kLocation
                                                     projectNumber:kProjectNumber
                                                       OAuthToken:kOAuthToken
                                                       networkCode:kNetworkCode
                                               adDisplayContainer:adDisplayContainer
                                                     videoDisplay:imaVideoDisplay
                                                       userContext:nil
                                       videoStitcherSessionOptions:sessionOptions];
 [self.adsLoader requestStreamWithRequest:streamRequest];

Swift

 // Define session options JSON string.
 // The following session options are examples. Use session options
 // that are compatible with your video stream.
 let sessionOptionsStr = """
     {
       "manifestOptions": {
         "includeRenditions": [
           {"bitrateBps": 3000, "codecs": "hvc1.1.4.L126.B0, mp4a.40.2"},
           {"bitrateBps": 2000, "codecs": "avc1.64001f, mp4a.40.2"},
         ],
         "bitrateOrder": "ascending"
       }
     }
     """
 // convert JSON string to dictionary
 guard let sessionOptionsData = sessionOptionsStr.data(using: .utf8, allowLossyConversion: false) else { return nil }
 let sessionOptions = try? JSONSerialization.jsonObject(with: sessionOptionsData, options: .mutableContainers)
 // make stream request
 let streamRequest = IMAVideoStitcherVODStreamRequest(
   vodConfigID:ViewController.vodConfigID
   region:ViewController.location
   projectNumber:ViewController.projectNumber
   OAuthToken:ViewController.oAuthToken
   networkCode:ViewController.networkCode
   adDisplayContainer:adDisplayContainer
   videoDisplay:imaVideoDisplay
   userContext:nil
   videoStitcherSessionOptions:sessionOptions)
 adsLoader?.requestStream(with: streamRequest)

Esegui la pulizia

Ora che hai ospitato correttamente uno stream VOD utilizzando l'API Google Cloud Video Stitcher e lo hai richiesto utilizzando l'SDK IMA DAI per iOS, è importante ripulire le risorse di pubblicazione.

Segui la guida alla pulizia dei contenuti VOD per rimuovere risorse e asset non necessari.