Configura l'SDK IMA

Seleziona la piattaforma: HTML5 Android iOS tvOS

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 lato client IMA, mantieni il controllo della riproduzione dei video dei contenuti, mentre l'SDK gestisce la riproduzione degli annunci. Gli annunci vengono riprodotti in un video player separato posizionato sopra il video player dei contenuti dell'app.

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

Panoramica lato client di IMA

L'implementazione di IMA lato client prevede quattro componenti principali dell'SDK, che sono illustrati in questa guida:

  • IMAAdDisplayContainer: Un oggetto contenitore che specifica dove IMA esegue il rendering degli elementi dell'interfaccia utente dell'annuncio e misura la visibilità, inclusi Visualizzazione attiva e Open Measurement.
  • IMAAdsLoader: Un oggetto che richiede annunci e gestisce gli eventi dalle risposte alle richieste di annunci. Devi istanziare un solo caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.
  • IMAAdsRequest: Un oggetto che definisce una richiesta di annunci. Le richieste di annunci specificano l'URL del tag annuncio VAST, nonché parametri aggiuntivi, come le dimensioni dell'annuncio.
  • IMAAdsManager: Un oggetto che contiene la risposta alla richiesta di annunci, controlla la riproduzione degli annunci e ascolta gli eventi degli annunci attivati dall'SDK.

Prerequisiti

Prima di iniziare, devi disporre di quanto segue:

  • Xcode 13 o versioni successive
  • CocoaPods (preferito), Swift Package Manager o una copia scaricata dell'SDK IMA per iOS

1. Crea un nuovo progetto Xcode

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

2. Aggiungi l'SDK IMA al progetto Xcode

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. Una volta installato CocoaPods, utilizza le seguenti istruzioni per installare l'SDK IMA:

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

    Objective-C

    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '12'

target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1'
end

    Podfile

    Swift

    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '12'

target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1'
end

    Podfile

  2. Dalla directory che contiene il Podfile, esegui pod install --repo-update.

  3. Verifica che l'installazione sia andata a buon fine aprendo il file BasicExample.xcworkspace e confermando che contenga 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 3.18.4. Per importare il pacchetto Swift, completa i seguenti passaggi:

  1. In Xcode, installa il pacchetto Swift dell'SDK IMA andando a File > Add Package Dependencies… (File > Aggiungi dipendenze pacchetto…).

  2. Nel prompt, cerca il repository GitHub del pacchetto Swift dell'SDK IMA per iOS: swift-package-manager-google-interactive-media-ads-ios.

  3. Seleziona la versione del pacchetto Swift dell'SDK IMA che vuoi utilizzare. Per i nuovi progetti, ti consigliamo di utilizzare l'opzione Fino alla prossima versione principale.

Al termine, Xcode risolve le dipendenze del pacchetto e le scarica in background. Per maggiori dettagli su come aggiungere dipendenze del pacchetto, 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 aggiungerla manualmente al tuo progetto.

3. Creare un video player

Innanzitutto, implementa un video player. Inizialmente, questo player non utilizza l'SDK IMA e non contiene alcun metodo per attivare la riproduzione.

Objective-C

Importa le dipendenze del player:

#import "ViewController.h"

@import AVFoundation;
ViewController.m

Imposta le variabili del giocatore:

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>

/// Content video player.
@property(nonatomic, strong) AVPlayer *contentPlayer;

/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

/// UIView in which we will render our AVPlayer for content.
@property(nonatomic, weak) IBOutlet UIView *videoView;
ViewController.m

Avvia il video player quando viene caricata la visualizzazione:

@implementation ViewController

// The content URL to play.
NSString *const kTestAppContentUrl_MP4 =
    @"https://storage.googleapis.com/gvabox/media/samples/stock.mp4";

// Ad tag
NSString *const kTestAppAdTagUrl = @"https://pubads.g.doubleclick.net/gampad/ads?"
  @"iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&"
  @"ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&"
  @"correlator=";

- (void)viewDidLoad {
  [super viewDidLoad];

  self.playButton.layer.zPosition = MAXFLOAT;

  [self setupAdsLoader];
  [self setUpContentPlayer];
}

#pragma mark Content Player Setup

- (void)setUpContentPlayer {
  // Load AVPlayer with path to our content.
  NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];
  self.contentPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.contentPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];

  // Set up our content playhead and contentComplete callback.
  self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:self.contentPlayer.currentItem];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestAds];
  self.playButton.hidden = YES;
}
ViewController.m

Swift

Importa le dipendenze del player:

import AVFoundation
PlayerContainerViewController.swift

Imposta le variabili del giocatore:

class PlayerContainerViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
  static let contentURL = URL(
    string: "https://storage.googleapis.com/gvabox/media/samples/stock.mp4")!

  private var contentPlayer = AVPlayer(url: PlayerContainerViewController.contentURL)

  private lazy var playerLayer: AVPlayerLayer = {
    AVPlayerLayer(player: contentPlayer)
  }()
PlayerContainerViewController.swift

Avvia il video player quando viene caricata la visualizzazione:

private lazy var videoView: UIView = {
  let videoView = UIView()
  videoView.translatesAutoresizingMaskIntoConstraints = false
  view.addSubview(videoView)

  NSLayoutConstraint.activate([
    videoView.bottomAnchor.constraint(
      equalTo: view.safeAreaLayoutGuide.bottomAnchor),
    videoView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
    videoView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),
    videoView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
  ])
  return videoView
}()

// MARK: - View controller lifecycle methods

override func viewDidLoad() {
  super.viewDidLoad()

  videoView.layer.addSublayer(playerLayer)
  adsLoader.delegate = self

  NotificationCenter.default.addObserver(
    self,
    selector: #selector(contentDidFinishPlaying(_:)),
    name: .AVPlayerItemDidPlayToEndTime,
    object: contentPlayer.currentItem)
}

override func viewDidAppear(_ animated: Bool) {
  super.viewDidAppear(animated)
  playerLayer.frame = videoView.layer.bounds
}

override func viewWillTransition(
  to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator
) {
  coordinator.animate { _ in
    // do nothing
  } completion: { _ in
    self.playerLayer.frame = self.videoView.layer.bounds
  }
}

// MARK: - Public methods

func playButtonPressed() {
  requestAds()
}
PlayerContainerViewController.swift

4. Importa l'SDK IMA

Per importare l'SDK IMA:

Objective-C

  1. Importa l'SDK IMA:

    @import GoogleInteractiveMediaAds;
    ViewController.m

  2. Crea variabili per le classi IMAAdsLoader, IMAAVPlayerContentPlayhead e IMAAdsManager utilizzate nell'app:

    // SDK
/// Entry point for the SDK. Used to make ad requests.
@property(nonatomic, strong) IMAAdsLoader *adsLoader;

/// Playhead used by the SDK to track content video progress and insert mid-rolls.
@property(nonatomic, strong) IMAAVPlayerContentPlayhead *contentPlayhead;

/// Main point of interaction with the SDK. Created by the SDK as the result of an ad request.
@property(nonatomic, strong) IMAAdsManager *adsManager;
    ViewController.m

Swift

  1. Importa l'SDK IMA:

    import GoogleInteractiveMediaAds

    PlayerContainerViewController.swift

  2. Crea variabili per le classi IMAAdsLoader, IMAAVPlayerContentPlayhead e IMAAdsManager utilizzate nell'app:

    static let adTagURLString =
  "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/"
  + "single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&"
  + "gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&correlator="

private let adsLoader = IMAAdsLoader()
private var adsManager: IMAAdsManager?

private lazy var contentPlayhead: IMAAVPlayerContentPlayhead = {
  IMAAVPlayerContentPlayhead(avPlayer: contentPlayer)
}()
    PlayerContainerViewController.swift

5. Implementare il tracker della testina di riproduzione dei contenuti e l'osservatore di fine stream

Per riprodurre gli annunci mid-roll, l'SDK IMA deve monitorare la posizione attuale dei tuoi contenuti video. Per farlo, crea una classe che implementi IMAContentPlayhead. Se utilizzi un AVPlayer, come mostrato in questo esempio, l'SDK fornisce la classe IMAAVPlayerContentPlayhead che esegue questa operazione per te. Se non utilizzi AVPlayer, dovrai implementare IMAContentPlayhead in una classe di tua proprietà.

Devi anche comunicare all'SDK quando la riproduzione dei contenuti è terminata in modo che possa mostrare gli annunci post-roll. Per farlo, chiama il metodo contentComplete su IMAAdsLoader, utilizzando AVPlayerItemDidPlayToEndTimeNotification.

Objective-C

Crea l'istanza IMAAVPlayerContentPlayhead nella configurazione del player:

// Set up our content playhead and contentComplete callback.
self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(contentDidFinishPlaying:)
                                             name:AVPlayerItemDidPlayToEndTimeNotification
                                           object:self.contentPlayer.currentItem];
ViewController.m

Crea il metodo contentDidFinishPlaying() per chiamare IMAAdsLoader.contentComplete() al termine della riproduzione dei contenuti:

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if (notification.object == self.contentPlayer.currentItem) {
    [self.adsLoader contentComplete];
  }
}
ViewController.m

Swift

Crea l'observer di fine contenuti nella configurazione del player:

NotificationCenter.default.addObserver(
  self,
  selector: #selector(contentDidFinishPlaying(_:)),
  name: .AVPlayerItemDidPlayToEndTime,
  object: contentPlayer.currentItem)
PlayerContainerViewController.swift

Crea il metodo contentDidFinishPlaying() per chiamare IMAAdsLoader.contentComplete() al termine della riproduzione dei contenuti:

@objc func contentDidFinishPlaying(_ notification: Notification) {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if notification.object as? AVPlayerItem == contentPlayer.currentItem {
    adsLoader.contentComplete()
  }
}
PlayerContainerViewController.swift

6. Inizializza il caricatore di annunci ed effettua una richiesta di annunci

Per richiedere un insieme di annunci, devi creare un'istanza IMAAdsLoader. Questo caricatore può essere utilizzato per elaborare gli oggetti IMAAdsRequest associati a un URL tag annuncio specificato.

Come best practice, mantieni una sola istanza di IMAAdsLoader per l'intero ciclo di vita della tua app. Per effettuare richieste di annunci aggiuntive, crea un nuovo oggetto IMAAdsRequest, ma riutilizza lo stesso IMAAdsLoader. Per ulteriori informazioni, consulta le domande frequenti sull'SDK IMA.

Objective-C

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;
}

- (void)requestAds {
  // Create an ad display container for ad rendering.
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];
  // Create an ad request with our ad tag, display container, and optional user context.
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl
                                                adDisplayContainer:adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}
ViewController.m

Swift

private func requestAds() {
  // Create ad display container for ad rendering.
  let adDisplayContainer = IMAAdDisplayContainer(
    adContainer: videoView, viewController: self, companionSlots: nil)
  // Create an ad request with our ad tag, display container, and optional user context.
  let request = IMAAdsRequest(
    adTagUrl: PlayerContainerViewController.adTagURLString,
    adDisplayContainer: adDisplayContainer,
    contentPlayhead: contentPlayhead,
    userContext: nil)

  adsLoader.requestAds(with: request)
}
PlayerContainerViewController.swift

7. Configurare un delegato del caricatore di annunci

In caso di evento di caricamento riuscito, IMAAdsLoader chiama il metodo adsLoadedWithData del delegato assegnato, passandogli un'istanza di IMAAdsManager. A questo punto puoi inizializzare Ads Manager, che carica i singoli annunci, come definito dalla risposta all'URL del tag annuncio.

Inoltre, assicurati di gestire eventuali errori che potrebbero verificarsi durante il processo di caricamento. Se gli annunci non vengono caricati, assicurati che la riproduzione dei contenuti multimediali continui senza annunci, in modo da non interferire con l'esperienza dell'utente.

Objective-C

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  // Create ads rendering settings to tell the SDK to use the in-app browser.
  IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];
  adsRenderingSettings.linkOpenerPresentingController = self;
  // Initialize the ads manager.
  [self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Something went wrong loading ads. Log the error and play the content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayer play];
}
ViewController.m

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  adsManager = adsLoadedData.adsManager
  adsManager?.delegate = self

  // Create ads rendering settings and tell the SDK to use the in-app browser.
  let adsRenderingSettings = IMAAdsRenderingSettings()
  adsRenderingSettings.linkOpenerPresentingController = self

  // Initialize the ads manager.
  adsManager?.initialize(with: adsRenderingSettings)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  if let message = adErrorData.adError.message {
    print("Error loading ads: \(message)")
  }
  contentPlayer.play()
}
PlayerContainerViewController.swift

8. Configurare un delegato di Ads Manager

Infine, per gestire gli eventi e le modifiche di stato, il responsabile degli annunci ha bisogno di un proprio delegato. IMAAdManagerDelegate ha metodi per gestire eventi ed errori degli annunci, nonché metodi per attivare la riproduzione e la pausa dei contenuti video.

Avvia riproduzione

Ascolta l'evento LOADED per avviare la riproduzione di contenuti e annunci. Per maggiori dettagli, vedi didReceiveAdEvent.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // When the SDK notified us that ads have been loaded, play them.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}
ViewController.m

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
  // When the SDK notifies us the ads have been loaded, play them.
  if event.type == IMAAdEventType.LOADED {
    adsManager.start()
  }
}
PlayerContainerViewController.swift

Gestisci gli errori

Aggiungi anche un gestore per gli errori degli annunci. Se si verifica un errore, come nel passaggio precedente, riprendi la riproduzione dei contenuti.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Something went wrong with the ads manager after ads were loaded. Log the error and play the
  // content.
  NSLog(@"AdsManager error: %@", error.message);
  [self.contentPlayer play];
}
ViewController.m

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
  // Something went wrong with the ads manager after ads were loaded.
  // Log the error and play the content.
  if let message = error.message {
    print("AdsManager error: \(message)")
  }
  contentPlayer.play()
}
PlayerContainerViewController.swift

Ascolta gli eventi di riproduzione e pausa

Gli ultimi due metodi delegati che devi implementare vengono utilizzati per attivare gli eventi di riproduzione e pausa sui contenuti video sottostanti, quando richiesto dall'SDK IMA. L'attivazione della pausa e della riproduzione su richiesta impedisce all'utente di perdere parti dei contenuti video durante la visualizzazione degli annunci.

Objective-C

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // The SDK is going to play ads, so pause the content.
  [self.contentPlayer pause];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // The SDK is done playing ads (at least for now), so resume the content.
  [self.contentPlayer play];
}
ViewController.m

Swift

func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
  // The SDK is going to play ads, so pause the content.
  contentPlayer.pause()
}

func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
  // The SDK is done playing ads (at least for now), so resume the content.
  contentPlayer.play()
}
PlayerContainerViewController.swift

È tutto. Ora richiedi e visualizzi gli annunci con l'SDK IMA. Per scoprire di più sulle funzionalità aggiuntive dell'SDK, consulta le altre guide o gli esempi su GitHub.

Passaggi successivi

Per massimizzare le entrate pubblicitarie sulla piattaforma iOS, richiedi l'autorizzazione App Tracking Transparency per utilizzare l'IDFA.