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 SDK principaux, 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 :

  • Xcode 13 ou version ultérieure
  • CocoaPods (recommandé), Swift Package Manager ou une copie téléchargée du SDK IMA pour iOS

1. Créer un projet Xcode

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

2. Ajouter le SDK IMA au projet Xcode

CocoaPods est un gestionnaire de dépendances pour les projets Xcode. Il s'agit de la méthode recommandée pour installer le SDK IMA. Pour en savoir plus sur l'installation ou l'utilisation de CocoaPods, consultez la documentation de CocoaPods. Une fois CocoaPods installé, suivez les instructions ci-dessous pour installer le SDK IMA :

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

    Objective-C

    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '12'
    
    target "BasicExample" do
      pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1'
    end
    
    

    Swift

    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '12'
    
    target "BasicExample" do
      pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1'
    end
    
    
  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 confirmant qu'il contient deux projets : BasicExample et Pods (les dépendances installées par CocoaPods).

Installer le SDK à l'aide de Swift Package Manager

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

  1. Dans Xcode, installez le package Swift du SDK IMA en accédant à File > Add Package Dependencies... (Fichier > Ajouter des dépendances de package…).

  2. Dans l'invite, recherchez le dépôt GitHub du package Swift du SDK IMA pour iOS : swift-package-manager-google-interactive-media-ads-ios.

  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.

Télécharger et installer le SDK manuellement

Si vous ne souhaitez pas utiliser Swift Package Manager ni CocoaPods, vous pouvez télécharger le SDK IMA et l'ajouter manuellement à votre projet.

3. Créer un lecteur vidéo

Commencez par implémenter un lecteur vidéo. Au départ, ce lecteur n'utilise pas le SDK IMA et ne contient aucune méthode pour déclencher la lecture.

Objective-C

Importez les dépendances du lecteur :

#import "ViewController.h"

@import AVFoundation;

Configurez les variables du lecteur :

@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;

Initialisez le lecteur vidéo lorsque la vue se charge :

@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;
}

Swift

Importez les dépendances du lecteur :

import AVFoundation

Configurez les variables du lecteur :

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)
  }()

Initialisez le lecteur vidéo lorsque la vue se charge :

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()
}

4. Importer le SDK IMA

Pour importer le SDK IMA :

Objective-C

  1. Importez le SDK IMA :

    @import GoogleInteractiveMediaAds;
    
  2. Créez des variables pour les classes IMAAdsLoader, IMAAVPlayerContentPlayhead et IMAAdsManager utilisées dans l'application :

    // 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;
    

Swift

  1. Importez le SDK IMA :

    import GoogleInteractiveMediaAds
    
    
  2. Créez des variables pour les classes IMAAdsLoader, IMAAVPlayerContentPlayhead et IMAAdsManager utilisées dans l'application :

    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)
    }()
    

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 devrez implémenter IMAContentPlayhead sur une classe qui vous est propre.

Vous devez également indiquer au SDK quand votre contenu est terminé afin qu'il puisse afficher des annonces post-roll. Pour ce faire, appelez la méthode contentComplete sur IMAAdsLoader, en utilisant AVPlayerItemDidPlayToEndTimeNotification.

Objective-C

Créez l'instance IMAAVPlayerContentPlayhead dans la configuration du lecteur :

// 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];

Créez la méthode contentDidFinishPlaying() pour appeler IMAAdsLoader.contentComplete() lorsque le contenu a fini d'être lu :

- (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];
  }
}

Swift

Créez l'observateur de fin de contenu dans la configuration du lecteur :

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

Créez la méthode contentDidFinishPlaying() pour appeler IMAAdsLoader.contentComplete() lorsque le contenu a fini d'être lu :

@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()
  }
}

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] 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];
}

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)
}

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 nuire à l'expérience utilisateur.

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];
}

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()
}

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

Écoutez l'événement LOADED pour lancer la lecture du contenu et des annonces. Pour en savoir plus, consultez 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];
  }
}

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()
  }
}

Gérer 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 {
  // 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];
}

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()
}

Écouter les événements de lecture et de pause

Les deux dernières méthodes déléguées que vous devez implémenter sont utilisées pour déclencher des é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 {
  // 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];
}

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()
}

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 iOS, demandez l'autorisation de transparence et de suivi des applications pour utiliser l'IDFA.