Configura l'SDK IMA

Seleziona la piattaforma: HTML5 Android iOS tvOS

Gli SDK IMA semplificano l'integrazione di annunci multimediali nei siti web e nelle app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server conforme a VAST e gestire la riproduzione degli annunci nelle app. Con gli SDK IMA lato client, mantieni il controllo della riproduzione dei video di 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. Per visualizzare o seguire un'integrazione di esempio completata, scarica il BasicExample da GitHub.

Panoramica lato client di IMA

L'implementazione di IMA lato client prevede quattro componenti SDK principali, che vengono 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à, inclusa la Visualizzazione attiva e Open Measurement.
  • IMAAdsLoader: un oggetto che richiede annunci e gestisce gli eventi dalle risposte alle richieste di annunci. Dovresti creare un'istanza di 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 avere:

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

Per installare l'SDK IMA, scegli un metodo preferito.

Consigliato: 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, segui questi 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 Up to Next Major Version (Fino alla prossima versione principale).

Al termine, Xcode risolve le dipendenze del pacchetto e le scarica in background. Per maggiori dettagli su come aggiungere le dipendenze del pacchetto, consulta l'articolo di Apple.

Installa l'SDK utilizzando CocoaPods

CocoaPods è un gestore delle dipendenze per i progetti Xcode ed è il metodo consigliato per installare l'SDK IMA. Per maggiori informazioni sull'installazione o sull'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 BasicExample.xcodeproj , crea un file di testo denominato Podfile e aggiungi la seguente configurazione:

    Objective-C

    platform :ios, '15'

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

    Podfile

    Swift

    platform :ios, '15'

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

    Podfile

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

  3. Verifica che l'installazione sia andata a buon fine aprendo il file BasicExample.xcworkspace e assicurandoti che contenga due progetti: BasicExample e Pods (le dipendenze installate da CocoaPods).

Scarica e installa manualmente l'SDK

Se non vuoi utilizzare Swift Package Manager, scarica e aggiungi manualmente l'SDK IMA al tuo progetto.

3. Crea 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

Configura le variabili del player:

@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 al caricamento della 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

Configura le variabili del player:

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 al caricamento della 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. Implementa il tracker della testina di riproduzione dei contenuti e l'observer di fine stream

Per riprodurre gli annunci mid-roll, l'SDK IMA deve monitorare la posizione corrente dei 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, devi 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 contentComplete metodo 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 elabora gli oggetti IMAAdsRequest associati a un URL del tag annuncio specificato.

Come best practice, mantieni una sola istanza di IMAAdsLoader per l'intero ciclo di vita dell'app. Per effettuare ulteriori richieste di annunci, crea un nuovo oggetto IMAAdsRequest, ma riutilizza lo stesso IMAAdsLoader. Per maggiori 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. Configura un delegato del caricatore di annunci

In caso di evento di caricamento riuscito, il IMAAdsLoader chiama il adsLoadedWithData metodo del delegato assegnato, passandogli un'istanza di IMAAdsManager. Puoi quindi inizializzare il gestore degli annunci, 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. Configura un delegato del gestore degli annunci

Infine, per gestire gli eventi e le modifiche dello stato, il gestore degli annunci ha bisogno di un proprio delegato. IMAAdManagerDelegate dispone di metodi per gestire gli eventi e gli errori degli annunci, nonché metodi per attivare la riproduzione e la messa in 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

Rimani in ascolto per gli eventi di riproduzione e pausa

Gli ultimi due metodi delegati che devi implementare attivano gli eventi di riproduzione e pausa sui contenuti video sottostanti quando l'SDK IMA li richiede. L'attivazione della pausa e della riproduzione quando richiesto 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

Questo è tutto! Ora puoi richiedere e visualizzare 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 per la trasparenza e il monitoraggio delle app per utilizzare IDFA.