Configurer le SDK IMA

Sélectionnez une plate-forme : HTML5 Android iOS tvOS

Les SDK IMA permettent d'intégrer facilement des annonces multimédias à vos sites Web et applications. Les SDK IMA peuvent demander des annonces à n'importe quel ad server conforme à la norme VAST et gérer la lecture des annonces dans vos applications. Avec les SDK IMA côté client, vous gardez le contrôle de la lecture des contenus vidéo, tandis que le SDK gère la lecture des annonces. Les annonces sont diffusées dans un lecteur vidéo distinct, positionné au-dessus du lecteur vidéo de contenu de l'application.

Ce guide explique comment intégrer le SDK IMA dans une application de lecteur vidéo. Pour afficher ou suivre un exemple d'intégration complet, téléchargez BasicExample depuis GitHub.

Présentation d'IMA côté client

L'implémentation d'IMA côté client implique quatre composants SDK principaux. Ce guide présente les composants suivants :

  • IMAAdDisplayContainer : Objet conteneur qui spécifie où IMA affiche les éléments d'UI des annonces et mesure la visibilité, y compris Active View et Open Measurement.
  • IMAAdsLoader : objet qui demande des annonces et gère les événements des réponses aux demandes d'annonces. Vous ne devez instancier qu'un seul chargeur d'annonces, qui peut être réutilisé tout au long de la durée de vie de l'application.
  • IMAAdsRequest : Objet qui définit une demande d'annonces. Les demandes d'annonces spécifient l'URL du tag d'emplacement publicitaire VAST, ainsi que des paramètres supplémentaires, tels que les dimensions de l'annonce.
  • IMAAdsManager : Objet contenant la réponse à la demande d'annonces, contrôlant la lecture des annonces et écoutant les événements d'annonce déclenchés par le SDK.

Prérequis

Avant de commencer, vous avez besoin des éléments suivants :

1. Créer un projet Xcode

Dans Xcode, créez un projet tvOS à l'aide d'Objective-C ou de Swift. Utilisez BasicExample comme nom de projet.

2. Ajouter le SDK IMA au projet Xcode

Pour installer le SDK IMA, choisissez la méthode de votre choix.

Recommandation : Installez le SDK IMA à l'aide de Swift Package Manager

Le SDK Interactive Media Ads est compatible avec Swift Package Manager à partir de la version 4.8.2. Pour importer le package Swift, procédez comme suit.

  1. Dans Xcode, installez le package Swift du SDK IMA en accédant à File > Add Packages… (Fichier > Ajouter des packages…).

  2. Dans l'invite qui s'affiche, recherchez le dépôt GitHub du package Swift du SDK IMA :

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos

  3. Sélectionnez la version du package Swift du SDK IMA que vous souhaitez utiliser. Pour les nouveaux projets, nous vous recommandons d'utiliser Up to Next Major Version.

Une fois que vous avez terminé, Xcode résout les dépendances de votre package et les télécharge en arrière-plan. Pour savoir comment ajouter des dépendances de package, consultez l'article d'Apple.

Installer le SDK IMA à l'aide de CocoaPods

Pour installer le SDK IMA, utilisez CocoaPods. Pour en savoir plus sur l'installation ou l'utilisation de CocoaPods, consultez la documentation de CocoaPods. Après avoir installé CocoaPods, procédez comme suit :

  1. Dans le même répertoire que votre fichier BasicExample.xcodeproj, créez un fichier texte nommé Podfile et ajoutez la configuration suivante :

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

platform :tvos, '15'

target "BasicExample" do
  pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0'
end

    Podfile

  2. Depuis le répertoire contenant le fichier Podfile, exécutez pod install --repo-update.

  3. Vérifiez que l'installation a réussi en ouvrant le fichier BasicExample.xcworkspace et en vous assurant qu'il contient deux projets : BasicExample et Pods (les dépendances installées par CocoaPods).

Télécharger et installer manuellement le SDK IMA

Si vous ne souhaitez pas utiliser Swift Package Manager, téléchargez et ajoutez manuellement le SDK IMA à votre projet.

3. Importer le SDK IMA

Ajoutez le framework IMA à l'aide d'une instruction d'importation.

Objective-C

#import "ViewController.h"
#import <AVKit/AVKit.h>

@import GoogleInteractiveMediaAds;
ViewController.m

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

ViewController.swift

4. Créer un lecteur vidéo et intégrer le SDK IMA

L'exemple suivant initialise le SDK IMA :

Objective-C

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
NSString *const kAdTagURLString =
    @"https://pubads.g.doubleclick.net/gampad/ads?"
    @"iu=/21775744923/external/vmap_ad_samples&sz=640x480&"
    @"cust_params=sample_ar%3Dpremidpostlongpod&ciu_szs=300x250&gdfp_req=1&ad_rule=1&"
    @"output=vmap&unviewed_position_start=1&env=vp&cmsid=496&vid=short_onecue&correlator=";

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];
  [self setupAdsLoader];
  [self setupContentPlayer];
}

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestAds];
}

// Add the content video player as a child view controller.
- (void)showContentPlayer {
  [self addChildViewController:self.contentPlayerViewController];
  self.contentPlayerViewController.view.frame = self.view.bounds;
  [self.view insertSubview:self.contentPlayerViewController.view atIndex:0];
  [self.contentPlayerViewController didMoveToParentViewController:self];
}

// Remove and detach the content video player.
- (void)hideContentPlayer {
  // The whole controller needs to be detached so that it doesn't capture resume events from the
  // remote and play content underneath the ad.
  [self.contentPlayerViewController willMoveToParentViewController:nil];
  [self.contentPlayerViewController.view removeFromSuperview];
  [self.contentPlayerViewController removeFromParentViewController];
}
ViewController.m

Swift

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
  static let contentURLString =
    "https://devstreaming-cdn.apple.com/videos/streaming/examples/"
    + "img_bipbop_adv_example_fmp4/master.m3u8"
  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="

  var adsLoader: IMAAdsLoader!
  var adDisplayContainer: IMAAdDisplayContainer!
  var adsManager: IMAAdsManager!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!
  var adBreakActive = false

  deinit {
    NotificationCenter.default.removeObserver(self)
  }

  override func viewDidLoad() {
    super.viewDidLoad()
    self.view.backgroundColor = UIColor.black
    setUpContentPlayer()
    setUpAdsLoader()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    requestAds()
  }
ViewController.swift

Dans cet exemple, viewDidLoad() initialise IMAAdsLoader et viewDidAppear() demande des annonces une fois la vue visible. Les méthodes d'assistance showContentPlayer() et hideContentPlayer() activent/désactivent la visibilité du contenu pendant la lecture des annonces.

Cet exemple utilise la variable constante adTagURLString pour définir le tag d'emplacement publicitaire VAST pour la demande d'annonce, ainsi que les composants suivants pour gérer le SDK IMA :

  • adsLoader : gère les demandes et les réponses concernant les annonces. Nous vous recommandons d'utiliser une seule instance pour le cycle de vie de l'application.
  • adDisplayContainer : spécifie la vue pour l'affichage des annonces.
  • adsManager : gère la lecture des annonces et écoute les événements publicitaires.
  • contentPlayhead : suit la progression du contenu pour déclencher des coupures publicitaires mid-roll.
  • adBreakActive : indique si une coupure publicitaire est en cours de lecture pour empêcher l'utilisateur de passer les annonces.

5. Implémenter le suivi de la tête de lecture du contenu et l'observateur de fin de flux

Pour diffuser des annonces mid-roll, le SDK IMA doit suivre la position actuelle de votre contenu vidéo. Pour transmettre la position actuelle à IMA, créez une classe qui implémente IMAContentPlayhead. Si vous utilisez un AVPlayer, comme le montre cet exemple, le SDK IMA fournit la classe IMAAVPlayerContentPlayhead pour transmettre les informations de position actuelles. Si vous n'utilisez pas AVPlayer, implémentez IMAContentPlayhead sur une classe de votre choix.

Objective-C

- (void)setupContentPlayer {
  // Create a content video player. Create a playhead to track content progress so the SDK knows
  // when to play ads in a VMAP playlist.
  NSURL *contentURL = [NSURL URLWithString:kContentURLString];
  AVPlayer *player = [AVPlayer playerWithURL:contentURL];
  self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
  self.contentPlayerViewController.player = player;
  self.contentPlayerViewController.view.frame = self.view.bounds;
  self.contentPlayhead =
      [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayerViewController.player];

  // Track end of content.
  AVPlayerItem *contentPlayerItem = self.contentPlayerViewController.player.currentItem;
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:contentPlayerItem];

  // Attach content video player to view hierarchy.
  [self showContentPlayer];
}
ViewController.m

Swift

func setUpContentPlayer() {
  // Load AVPlayer with path to our content.
  let contentURL = URL(string: ViewController.contentURLString)!
  let player = AVPlayer(url: contentURL)
  playerViewController = AVPlayerViewController()
  playerViewController.player = player

  // Set up our content playhead and contentComplete callback.
  contentPlayhead = IMAAVPlayerContentPlayhead(avPlayer: player)
  NotificationCenter.default.addObserver(
    self,
    selector: #selector(ViewController.contentDidFinishPlaying(_:)),
    name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
    object: player.currentItem)

  showContentPlayer()
}
ViewController.swift

Configurez un écouteur pour appeler contentComplete sur IMAAdsLoader lorsque votre contenu se termine, à l'aide de AVPlayerItemDidPlayToEndTimeNotification. L'appel de contentComplete permet au SDK IMA de savoir quand votre contenu se termine pour afficher des annonces post-roll.

Objective-C

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Notify the SDK that the postrolls should be played.
  [self.adsLoader contentComplete];
}

- (void)dealloc {
  [[NSNotificationCenter defaultCenter] removeObserver:self];
}
ViewController.m

Swift

@objc func contentDidFinishPlaying(_ notification: Notification) {
  adsLoader.contentComplete()
}
ViewController.swift

6. Initialiser le chargeur d'annonces et envoyer une demande d'annonces

Pour demander un ensemble d'annonces, créez une instance IMAAdsLoader. Ce chargeur traite les objets IMAAdsRequest associés à une URL de tag d'annonce spécifiée.

Nous vous recommandons de ne conserver qu'une seule instance de IMAAdsLoader pour l'ensemble du cycle de vie de votre application. Pour effectuer des demandes d'annonces supplémentaires, créez un objet IMAAdsRequest, mais réutilisez le même IMAAdsLoader. Pour en savoir plus, consultez les questions fréquentes sur le SDK IMA.

Objective-C

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

- (void)requestAds {
  // Pass the main view as the container for ad display.
  self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view
                                                                viewController:self];
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
                                                adDisplayContainer:self.adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}
ViewController.m

Swift

func setUpAdsLoader() {
  adsLoader = IMAAdsLoader(settings: nil)
  adsLoader.delegate = self
}

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

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

7. Configurer un délégué du chargeur d'annonces

Lors d'un événement de chargement réussi, IMAAdsLoader appelle la méthode adsLoadedWithData de son délégué attribué, en lui transmettant une instance de IMAAdsManager. Une fois que vous avez l'instance IMAAdsManager, initialisez le gestionnaire d'annonces, qui charge les annonces individuelles en fonction de la réponse de l'URL du tag d'annonce.

Pour les événements de chargement infructueux, configurez un délégué IMAAdsLoader pour gérer les erreurs qui se produisent pendant le processus de chargement. Si les annonces ne se chargent pas, assurez-vous que la lecture du contenu multimédia se poursuit sans annonces pour permettre aux utilisateurs de visionner le contenu multimédia.

Objective-C

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to the ads manager loaded for this request.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  [self.adsManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayerViewController.player 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
  adsManager.initialize(with: nil)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  print("Error loading ads: \(adErrorData.adError.message ?? "No error message available.")")
  showContentPlayer()
  playerViewController.player?.play()
}
ViewController.swift

8. Configurer un délégué Ads Manager

Enfin, pour gérer les événements et les changements d'état, le gestionnaire d'annonces nécessite son propre délégué. Le IMAAdManagerDelegate comporte des méthodes pour gérer les événements et les erreurs liés aux annonces, ainsi que des méthodes pour déclencher la lecture et la pause de votre contenu vidéo.

Lancer la lecture

La méthode didReceiveAdEvent gère tous les événements IMAAdEvent. Pour cet exemple de base, écoutez l'événement LOADED pour indiquer au gestionnaire d'annonces de commencer la lecture du contenu et des annonces. Le SDK IMA déclenche l'événement ICON_FALLBACK_IMAGE_CLOSED lorsque l'utilisateur ferme une boîte de dialogue de remplacement d'icône après avoir appuyé sur une icône. La lecture des annonces reprend alors.

Objective-C

#pragma mark - IMAAdsManagerDelegate

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  switch (event.type) {
    case kIMAAdEvent_LOADED: {
      // Play each ad once it has loaded.
      [adsManager start];
      break;
    }
    case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
      // Resume ad after user has closed dialog.
      [adsManager resume];
      break;
    }
    default:
      break;
  }
}
ViewController.m

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
  switch event.type {
  case IMAAdEventType.LOADED:
    // Play each ad once it has been loaded.
    adsManager.start()
  case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
    // Resume playback after the user has closed the dialog.
    adsManager.resume()
  default:
    break
  }
}
ViewController.swift

Traiter les erreurs

Ajoutez également un gestionnaire pour les erreurs d'annonces. Si une erreur se produit, comme à l'étape précédente, reprenez la lecture du contenu.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing content.
  NSLog(@"AdsManager error: %@", error.message);
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}
ViewController.m

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
  // Fall back to playing content
  print("AdsManager error: \(error.message ?? "No error message available.")")
  showContentPlayer()
  playerViewController.player?.play()
}
ViewController.swift

Déclencher des événements de lecture et de pause

Les deux derniers méthodes déléguées que vous implémentez déclenchent des événements de lecture et de pause sur le contenu vidéo sous-jacent lorsque le SDK IMA les demande. Le déclenchement de la pause et de la lecture lorsque le SDK IMA les demande empêche l'utilisateur de manquer des parties du contenu vidéo lorsque des annonces s'affichent.

Objective-C

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // Pause the content for the SDK to play ads.
  [self.contentPlayerViewController.player pause];
  [self hideContentPlayer];
  // Trigger an update to send focus to the ad display container.
  self.adBreakActive = YES;
  [self setNeedsFocusUpdate];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // Resume the content since the SDK is done playing ads (at least for now).
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
  // Trigger an update to send focus to the content player.
  self.adBreakActive = NO;
  [self setNeedsFocusUpdate];
}
ViewController.m

Swift

func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
  // Pause the content for the SDK to play ads.
  playerViewController.player?.pause()
  hideContentPlayer()
  // Trigger an update to send focus to the ad display container.
  adBreakActive = true
  setNeedsFocusUpdate()
}

func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
  // Resume the content since the SDK is done playing ads (at least for now).
  showContentPlayer()
  playerViewController.player?.play()
  // Trigger an update to send focus to the content player.
  adBreakActive = false
  setNeedsFocusUpdate()
}
ViewController.swift

Et voilà ! Vous demandez et diffusez désormais des annonces avec le SDK IMA. Pour en savoir plus sur les autres fonctionnalités du SDK, consultez les autres guides ou les exemples sur GitHub.

Étapes suivantes

Pour maximiser vos revenus publicitaires sur la plate-forme tvOS, demandez l'autorisation de transparence et de suivi des applications pour utiliser l'IDFA.