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. Si vous souhaitez 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 principaux du SDK, qui sont présentés dans ce guide :

  • 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

Installer 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. Suivez les étapes ci-dessous pour importer le package Swift.

  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 s'est bien déroulée 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 CocoaPods, vous pouvez télécharger le SDK IMA et l'ajouter manuellement à 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 ce faire, créez une classe qui implémente IMAContentPlayhead. Si vous utilisez un AVPlayer, comme illustré dans cet exemple, le SDK fournit la classe IMAAVPlayerContentPlayhead qui le fait pour vous. Si vous n'utilisez pas AVPlayer, vous devez implémenter 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

Vous devez également indiquer au SDK quand votre contenu est terminé afin qu'il puisse afficher des annonces post-roll. Pour ce faire, appelez contentComplete sur IMAAdsLoader à l'aide de AVPlayerItemDidPlayToEndTimeNotification.

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, vous devez créer une instance IMAAdsLoader. Ce chargeur peut être utilisé pour traiter 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. Vous pouvez ensuite initialiser le gestionnaire d'annonces, qui charge les annonces individuelles, telles que définies par la réponse à l'URL du tag d'annonce.

De plus, veillez à gérer les erreurs qui peuvent survenir lors du processus de chargement. Si les annonces ne se chargent pas, assurez-vous que la lecture du contenu multimédia se poursuit sans annonces afin de ne pas perturber l'expérience utilisateur.

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 a besoin de son propre délégué. 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 peut être utilisée pour gérer de nombreux événements. 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 dernières méthodes de délégué que vous devez implémenter servent à déclencher les événements de lecture et de mise en pause sur le contenu vidéo sous-jacent, lorsque le SDK IMA le demande. Le déclenchement de la mise en pause et de la lecture à la demande permet à l'utilisateur de ne pas manquer des parties du contenu vidéo lorsque des annonces sont diffusées.

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.