Premiers pas

Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et applications. Les SDK IMA demander des annonces <ph type="x-smartling-placeholder"></ph> compatible avec 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 du contenu vidéo, tandis que le SDK gère la lecture des annonces. Les annonces sont diffusées un lecteur vidéo distinct placé au-dessus du lecteur vidéo de contenu de l'application.

Ce guide explique comment intégrer le SDK IMA dans un lecteur vidéo simple. l'application. Si vous souhaitez consulter ou suivre un exemple terminé intégration, téléchargez le BasicExample de GitHub.

Présentation d'IMA côté client

L'implémentation d'IMA côté client implique quatre composants principaux du SDK : présentées dans ce guide:

• IMAAdDisplayContainer: Objet conteneur dans lequel les annonces sont affichées.
• IMAAdsLoader: Objet qui demande des annonces et gère les événements provenant des réponses aux demandes d'annonces. Vous ne devez instancier un chargeur d'annonces que vous pouvez réutiliser 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 qui contient la réponse à la demande d'annonce, contrôle la lecture des annonces et écoute l'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 un de la copie 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

Installer le SDK à l'aide de CocoaPods (recommandé)

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

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

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

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

3. Vérifiez que l'installation a réussi en ouvrant le BasicExample.xcworkspace et vérifier 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 le package Swift Manager à partir de la version 3.18.4. Suivez le les étapes ci-dessous pour importer le package Swift.

1. Dans Xcode, installez le package Swift du SDK IMA en accédant à Fichier > Ajouter des packages...

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

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

3. Sélectionnez la version du package IMA SDK Swift que vous souhaitez utiliser. Pour les nouveaux projets, nous vous recommandons d'utiliser l'option Jusqu'à la prochaine version majeure.

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

Télécharger et installer manuellement le SDK

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

3. Créer un lecteur vidéo simple

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

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";

@interface ViewController ()
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

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

- (void)setupContentPlayer {
  // Create a content video player.
  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;

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

// 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 events from the remote.
  [self.contentPlayerViewController willMoveToParentViewController:nil];
  [self.contentPlayerViewController.view removeFromSuperview];
  [self.contentPlayerViewController removeFromParentViewController];
}

@end
      

import AVFoundation
import UIKit

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

  var playerViewController: AVPlayerViewController!

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

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

    showContentPlayer()
  }

  func showContentPlayer() {
    self.addChild(playerViewController)
    playerViewController.view.frame = self.view.bounds
    self.view.insertSubview(playerViewController.view, at: 0)
    playerViewController.didMove(toParent:self)
  }

  func hideContentPlayer() {
    // The whole controller needs to be detached so that it doesn't capture
    // events from the remote.
    playerViewController.willMove(toParent:nil)
    playerViewController.view.removeFromSuperview()
    playerViewController.removeFromParent()
  }
}
      

4. Importer le SDK IMA

Ensuite, ajoutez le cadre IMA en utilisant une instruction d'importation sous la structure existante des importations.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
      

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"
      

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

Pour lire 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 effectue cette opération pour vous. Si vous n'utilisez pas AVPlayer, vous devez implémenter IMAContentPlayhead sur créer votre propre cours.

Vous devez aussi indiquer au SDK quand la lecture de votre contenu est terminée les annonces vidéo post-roll. Pour ce faire, appelez contentComplete au niveau de la IMAAdsLoader avec AVPlayerItemDidPlayToEndTimeNotification.

ViewController.m

...

@interface ViewController ()
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

...

- (void)setupContentPlayer {
  // Create a content video player.
  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];
}

...

- (void)contentDidFinishPlaying:(NSNotification *)notification {}

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

@end
      

...

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"

  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

  deinit {
    NotificationCenter.default.removeObserver(self)
  }

...

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

    // Set up your 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()
  }

...

  @objc func contentDidFinishPlaying(_ notification: Notification) {
    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 à un l'URL du tag d'emplacement publicitaire spécifiée.

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

ViewController.m

...

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&impl=s&cmsid=496&vid=short_onecue&correlator=";

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

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

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

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

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

...

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

...

@end
      

...

class ViewController: UIViewController {
  static let ContentURLString = "https://storage.googleapis.com/interactive-media-ads/media/stock.mp4"
  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&impl=s&correlator="

  var adsLoader: IMAAdsLoader!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

...

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

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

...

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

  func requestAds() {
    // Create ad display container for ad rendering.
    let adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view)
    // 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)
  }

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

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

En cas de chargement réussi, IMAAdsLoader appelle adsLoadedWithData de son délégué, en lui transmettant une instance de IMAAdsManager. Toi puis initialiser le Gestionnaire d'annonces, qui charge les annonces individuelles, comme défini par la réponse à l'URL du tag d'emplacement publicitaire.

En outre, veillez à gérer toutes les erreurs pouvant survenir lors du chargement processus. Si les annonces ne se chargent pas, assurez-vous que la lecture des contenus multimédias se poursuit, afin de ne pas interférer avec l'expérience utilisateur.

ViewController.m

...

@interface ViewController () <IMAAdsLoaderDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@end

@implementation ViewController

...

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

...

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

@end
      

...

class ViewController: UIViewController, IMAAdsLoaderDelegate {

...

  var adsLoader: IMAAdsLoader!
  var adsManager: IMAAdsManager!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!

...

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

...

  // MARK: - IMAAdsLoaderDelegate

  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    adsManager = adsLoadedData.adsManager
    adsManager.initialize(with: nil)
  }

  func adsLoader(_ loader: IMAAdsLoader!, failedWith adErrorData: IMAAdLoadingErrorData!) {
    print("Error loading ads: " + adErrorData.adError.message)
    showContentPlayer()
    playerViewController.player?.play()
  }
}
      

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

Enfin, pour gérer les événements et les changements d'état, le gestionnaire d'annonces a besoin d'un délégué lui-même. IMAAdManagerDelegate dispose de méthodes pour gérer les erreurs et les événements d'annonce, ainsi que les méthodes pour déclencher la lecture et l'interruption du contenu vidéo.

Démarrage de la lecture...

La méthode didReceiveAdEvent peut être utilisée pour gérer de nombreux événements, Pour cet exemple de base, écoutez simplement l'événement LOADED pour indiquer aux annonces pour lancer la lecture du contenu et des annonces.

ViewController.m

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>

...

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

...

#pragma mark - IMAAdsManagerDelegate

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // Play each ad once it has loaded.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}

...
      

...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {

...

  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    // Grab the instance of the IMAAdsManager and set yourself as the delegate.
    adsManager = adsLoadedData.adsManager
    adsManager.delegate = self
    adsManager.initialize(with: nil)
  }

...

  // MARK: - IMAAdsManagerDelegate

  func adsManager(_ adsManager: IMAAdsManager!, didReceive event: IMAAdEvent!) {
    // Play each ad once it has been loaded
    if event.type == IMAAdEventType.LOADED {
      adsManager.start()
    }
  }

...
      

Traiter les erreurs

Ajoutez également un gestionnaire pour les erreurs liées aux annonces. Si une erreur se produit, comme dans l'exemple pour reprendre la lecture du contenu.

ViewController.m

...

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

...

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

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

Les deux dernières méthodes de délégation que vous devez implémenter sont utilisées pour déclencher la lecture et mettre en pause des événements sur le contenu vidéo sous-jacent, à la demande du SDK IMA. Déclencher une pause et une lecture à la demande empêche l'utilisateur de manquer des parties du contenu vidéo lors de l'affichage des annonces.

ViewController.m

...

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // Pause the content for the SDK to play ads.
  [self.contentPlayerViewController.player pause];
  [self hideContentPlayer];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // Resume the content since the SDK is done playing ads (at least for now).
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}

@end
      

...

  func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager!) {
    // Pause the content for the SDK to play ads.
    playerViewController.player?.pause()
    hideContentPlayer()
  }

  func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager!) {
    // Resume the content since the SDK is done playing ads (at least for now).
    showContentPlayer()
    playerViewController.player?.play()
  }
}
      

Et voilà ! Vous demandez et affichez à présent des annonces avec le SDK IMA. Pour apprendre sur les fonctionnalités supplémentaires du SDK, consultez les autres guides exemples sur GitHub.

Étapes suivantes

Pour maximiser vos revenus publicitaires sur la plate-forme iOS, demandez l'autorisation de transparence et de suivi dans l'application afin d'utiliser l'IDFA.