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 DAI, les applications envoient une demande de flux pour les annonces et le contenu vidéo (VOD ou contenu en direct). Le SDK renvoie ensuite un flux vidéo combiné, ce qui vous évite d'avoir à gérer le basculement entre les vidéos d'annonces et de contenu dans votre application.
Sélectionnez la solution DAI qui vous intéresse.
Insertion dynamique d'annonces (service complet)
Ce guide explique comment intégrer le SDK IMA DAI dans une application de lecteur vidéo simple. Si vous souhaitez afficher ou suivre un exemple d'intégration complet, téléchargez BasicExample depuis GitHub.
Présentation d'IMA DAI
L'implémentation d'IMA DAI implique trois principaux composants du SDK, comme indiqué dans ce guide :
IMAAdDisplayContainer: Objet conteneur situé au-dessus de l'élément de lecture vidéo et contenant les éléments d'UI de l'annonce.IMAAdsLoader: objet qui demande des flux et gère les événements déclenchés par les objets de réponse aux demandes de flux. Vous ne devez instancier qu'un seul AdsLoader, qui peut être réutilisé tout au long de la durée de vie de l'application.IMAStreamRequest:IMAVODStreamRequestouIMALiveStreamRequest. Objet qui définit une requête de flux. Les demandes de flux peuvent concerner des vidéos à la demande ou des diffusions en direct. Les demandes de flux en direct spécifient une clé d'élément, tandis que les demandes de VOD spécifient un ID CMS et un ID vidéo. Les deux types de demandes peuvent éventuellement inclure une clé API nécessaire pour accéder aux flux spécifiés, ainsi qu'un code de réseau Google Ad Manager permettant au SDK IMA de gérer les identifiants publicitaires comme spécifié dans les paramètres Google Ad Manager.IMAStreamManager: objet qui gère les flux d'insertion dynamique d'annonces et les interactions avec le backend DAI. Le gestionnaire de flux gère également les pings de suivi et transmet les événements de flux et d'annonces à l'éditeur.
Prérequis
Avant de commencer, vous avez besoin des éléments suivants :
- Xcode 13 ou version ultérieure
- Swift Package Manager, CocoaPods ou une copie téléchargée du SDK IMA DAI pour tvOS
Créer un projet Xcode
Dans Xcode, créez un projet tvOS à l'aide d'Objective-C. Utilisez BasicExample comme nom de projet.
Ajouter le SDK IMA DAI au projet Xcode
Utilisez l'une de ces trois méthodes pour installer le SDK IMA DAI.
Installer le SDK à 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.
Dans Xcode, installez le package Swift GoogleInteractiveMediaAds en accédant à File > Add Packages (Fichier > Ajouter des packages).
Dans l'invite qui s'affiche, recherchez le dépôt GitHub du package Swift GoogleInteractiveMediaAds :
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosSélectionnez la version du package Swift GoogleInteractiveMediaAds 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 à l'aide de CocoaPods
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 DAI. 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 DAI :
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' endDepuis le répertoire contenant le fichier Podfile, exécutez la commande suivante :
pod install --repo-updateVé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 le SDK manuellement
Si vous ne souhaitez pas utiliser Swift Package Manager ni CocoaPods, vous pouvez télécharger le SDK IMA DAI et l'ajouter manuellement à votre projet.
Importer le SDK IMA
Ajoutez le framework IMA à l'aide d'une instruction import :
Objective-C
#import "ViewController.h"
#import <AVKit/AVKit.h>
@import GoogleInteractiveMediaAds;
Swift
import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
Créer un lecteur vidéo et intégrer le SDK IMA
L'exemple suivant initialise le SDK IMA :
Objective-C
// Live stream asset key, VOD content source and video IDs, and backup content URL.
static NSString *const kAssetKey = @"c-rArva4ShKVIAkNfy6HUQ";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";
static NSString *const kBackupStreamURLString =
@"http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/"
@"master.m3u8";
static const StreamType kDefaultStreamType = StreamTypeLive;
@interface ViewController () <IMAAdsLoaderDelegate,
IMAStreamManagerDelegate,
AVPlayerViewControllerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) id<IMAVideoDisplay> videoDisplay;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
self.streamType = kDefaultStreamType;
[self setupAdsLoader];
[self setupPlayer];
[self setupAdContainer];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self requestStream];
}
- (void)setupPlayer {
// Create a stream video player.
AVPlayer *player = [[AVPlayer alloc] init];
self.playerViewController = [[AVPlayerViewController alloc] init];
self.playerViewController.player = player;
// Attach video player to view hierarchy.
[self addChildViewController:self.playerViewController];
[self.view addSubview:self.playerViewController.view];
self.playerViewController.view.frame = self.view.bounds;
[self.playerViewController didMoveToParentViewController:self];
}
Swift
class ViewController:
UIViewController,
IMAAdsLoaderDelegate,
IMAStreamManagerDelegate,
AVPlayerViewControllerDelegate
{
// Live stream asset key, VOD content source and video IDs, Google Ad Manager network code, and
// backup content URL.
static let assetKey = "c-rArva4ShKVIAkNfy6HUQ"
static let contentSourceID = "2548831"
static let videoID = "tears-of-steel"
static let networkCode = "21775744923"
static let backupStreamURLString =
"http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/master.m3u8"
var adsLoader: IMAAdsLoader?
var videoDisplay: IMAAVPlayerVideoDisplay!
var adDisplayContainer: IMAAdDisplayContainer?
var adContainerView: UIView?
private var streamManager: IMAStreamManager?
private var contentPlayhead: IMAAVPlayerContentPlayhead?
private var playerViewController: AVPlayerViewController!
private var userSeekTime = 0.0
private var adBreakActive = false
private enum StreamType {
case live
/// Video on demand.
case vod
}
/// Set the stream type here.
private let currentStreamType: StreamType = .live
deinit {
NotificationCenter.default.removeObserver(self)
}
override func viewDidLoad() {
super.viewDidLoad()
self.view.backgroundColor = UIColor.black
setupAdsLoader()
setupPlayer()
setupAdContainer()
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
requestStream()
}
func setupPlayer() {
let player = AVPlayer()
let playerViewController = AVPlayerViewController()
playerViewController.delegate = self
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)
self.addChild(playerViewController)
playerViewController.view.frame = self.view.bounds
self.view.insertSubview(playerViewController.view, at: 0)
playerViewController.didMove(toParent: self)
self.playerViewController = playerViewController
}
Dans viewDidLoad(), setupAdsLoader() crée IMAAdsLoader, setupPlayer() crée AVPlayerViewController et setupAdContainer() prépare UIView pour l'affichage des annonces. Lorsque la vue devient visible, viewDidAppear() appelle requestStream() pour demander le flux DAI.
Pour définir les paramètres de la requête de flux, cet exemple utilise des constantes, telles que asset key pour les diffusions en direct, ou content source ID et video ID pour les flux VOD. L'exemple utilise également les composants suivants pour gérer le SDK IMA :
adsLoader: gère les demandes de flux vers Google Ad Manager. Nous vous recommandons d'utiliser une seule instance pour le cycle de vie de l'application.videoDisplay: implémentationIMAVideoDisplayqui permet à IMA de contrôler la lecture vidéo et de suivre les événements de lecture à l'aide d'AVPlayer.adDisplayContainer: gère la vue utilisée pour afficher les éléments d'UI des annonces et gérer la sélection de l'UI pendant les pauses publicitaires.streamManager: gère la lecture du flux combiné d'annonces et de contenu, et envoie les événements de cycle de vie des annonces à l'aide de son délégué.playerViewController: lecteur tvOS utilisé pour présenter le flux vidéo géré par le SDK IMA.adBreakActive: indicateur booléen indiquant si une coupure publicitaire est en cours de lecture. Il est utilisé pour empêcher la recherche pendant les annonces et pour gérer la sélection de l'UI.
Implémenter IMAAdsLoader
Ensuite, instanciez IMAAdsLoader et associez la vue du conteneur d'annonces à la hiérarchie des vues.
Objective-C
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] init];
self.adsLoader.delegate = self;
}
- (void)setupAdContainer {
// Attach the ad container to the view hierarchy on top of the player.
self.adContainerView = [[UIView alloc] init];
[self.view addSubview:self.adContainerView];
self.adContainerView.frame = self.view.bounds;
// Keep hidden initially, until an ad break.
self.adContainerView.hidden = YES;
}
Swift
func setupAdsLoader() {
let adsLoader = IMAAdsLoader(settings: nil)
adsLoader.delegate = self
self.adsLoader = adsLoader
}
func setupAdContainer() {
// Attach the ad container to the view hierarchy on top of the player.
let adContainerView = UIView()
self.view.addSubview(adContainerView)
adContainerView.frame = self.view.bounds
// Keep hidden initially, until an ad break.
adContainerView.isHidden = true
self.adContainerView = adContainerView
}
Envoyer une requête de flux
Créez quelques constantes pour stocker les informations du flux, puis implémentez la fonction de requête de flux pour effectuer la requête.
Objective-C
- (void)requestStream {
self.videoDisplay =
[[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView
viewController:self];
// Use the streamType property to determine which request to create.
IMAStreamRequest *request;
switch (self.streamType) {
case StreamTypeLive: {
request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
networkCode:kNetworkCode
adDisplayContainer:self.adDisplayContainer
videoDisplay:self.videoDisplay
userContext:nil];
NSLog(@"IMA: Requesting Live Stream with Asset Key: %@.", kAssetKey);
break;
}
case StreamTypeVOD: {
request = [[IMAVODStreamRequest alloc] initWithContentSourceID:kContentSourceID
videoID:kVideoID
networkCode:kNetworkCode
adDisplayContainer:self.adDisplayContainer
videoDisplay:self.videoDisplay
userContext:nil];
NSLog(@"IMA: Requesting VOD Stream with Video ID: %@.", kVideoID);
break;
}
}
if (request) {
[self.adsLoader requestStreamWithRequest:request];
} else {
// Fallback or error handling if no request object was created
NSLog(@"IMA Error: Could not create stream request for unknown type.");
[self playBackupStream];
}
}
Swift
func requestStream() {
guard let playerViewController = self.playerViewController else { return }
guard let adContainerView = self.adContainerView else { return }
guard let adsLoader = self.adsLoader else { return }
self.videoDisplay = IMAAVPlayerVideoDisplay(avPlayer: playerViewController.player!)
let adDisplayContainer = IMAAdDisplayContainer(
adContainer: adContainerView, viewController: self)
self.adDisplayContainer = adDisplayContainer
// Variable to hold the specific stream request object.
let request: IMAStreamRequest
switch self.currentStreamType {
case .live:
// Create a live stream request.
request = IMALiveStreamRequest(
assetKey: ViewController.assetKey,
networkCode: ViewController.networkCode,
adDisplayContainer: adDisplayContainer,
videoDisplay: self.videoDisplay,
pictureInPictureProxy: nil,
userContext: nil)
print("IMA: Requesting Live Stream with asset key \(ViewController.assetKey)")
case .vod:
// Create a VOD stream request.
request = IMAVODStreamRequest(
contentSourceID: ViewController.contentSourceID,
videoID: ViewController.videoID,
networkCode: ViewController.networkCode,
adDisplayContainer: adDisplayContainer,
videoDisplay: self.videoDisplay,
pictureInPictureProxy: nil,
userContext: nil)
print(
"IMA: Requesting VOD Stream with content source ID \(ViewController.contentSourceID) and "
+ "video ID \(ViewController.videoID)")
}
adsLoader.requestStream(with: request)
}
Gérer les événements de flux
IMAAdsLoader et IMAStreamManager déclenchent des événements qui permettent de gérer l'initialisation, les erreurs et les changements d'état du flux. Ces événements sont déclenchés via les protocoles IMAAdsLoaderDelegate et IMAStreamManagerDelegate. Écoutez un événement d'annonces chargées et initialisez le flux. Si une annonce ne se charge pas, diffusez un flux de secours à la place.
Objective-C
- (void)playBackupStream {
NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
[self.videoDisplay loadStream:backupStreamURL withSubtitles:@[]];
[self.videoDisplay play];
[self startMediaSession];
}
- (void)startMediaSession {
[[AVAudioSession sharedInstance] setActive:YES error:nil];
[[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryPlayback error:nil];
}
#pragma mark - IMAAdsLoaderDelegate
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
// Initialize and listen to stream manager's events.
self.streamManager = adsLoadedData.streamManager;
self.streamManager.delegate = self;
[self.streamManager initializeWithAdsRenderingSettings:nil];
NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}
- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
// Fall back to playing the backup stream.
NSLog(@"Error loading ads: %@", adErrorData.adError.message);
[self playBackupStream];
}
Swift
@objc func contentDidFinishPlaying(_ notification: Notification) {
guard let adsLoader = self.adsLoader else { return }
adsLoader.contentComplete()
}
func startMediaSession() {
try? AVAudioSession.sharedInstance().setActive(true, options: [])
try? AVAudioSession.sharedInstance().setCategory(.playback)
}
// MARK: - IMAAdsLoaderDelegate
func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
let streamManager = adsLoadedData.streamManager!
streamManager.delegate = self
streamManager.initialize(with: nil)
self.streamManager = streamManager
}
func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
print("Error loading ads: \(adErrorData.adError.message)")
let streamUrl = URL(string: ViewController.backupStreamURLString)
self.videoDisplay.loadStream(streamUrl!, withSubtitles: [])
self.videoDisplay.play()
playerViewController.player?.play()
}
Gérer les événements de journalisation et d'erreur
Plusieurs événements peuvent être gérés par le délégué du gestionnaire de flux, mais pour les implémentations de base, les utilisations les plus importantes sont l'enregistrement des événements, la prévention des actions de recherche pendant la lecture des annonces et la gestion des erreurs.
Objective-C
#pragma mark - IMAStreamManagerDelegate
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
NSLog(@"StreamManager event (%@).", event.typeString);
switch (event.type) {
case kIMAAdEvent_STREAM_STARTED: {
[self startMediaSession];
break;
}
case kIMAAdEvent_STARTED: {
// Log extended data.
NSString *extendedAdPodInfo = [[NSString alloc]
initWithFormat:@"Showing ad %zd/%zd, bumper: %@, title: %@, description: %@, contentType:"
@"%@, pod index: %zd, time offset: %lf, max duration: %lf.",
event.ad.adPodInfo.adPosition, event.ad.adPodInfo.totalAds,
event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
event.ad.adDescription, event.ad.contentType, event.ad.adPodInfo.podIndex,
event.ad.adPodInfo.timeOffset, event.ad.adPodInfo.maxDuration];
NSLog(@"%@", extendedAdPodInfo);
break;
}
case kIMAAdEvent_AD_BREAK_STARTED: {
self.adContainerView.hidden = NO;
// Trigger an update to send focus to the ad display container.
self.adBreakActive = YES;
[self setNeedsFocusUpdate];
break;
}
case kIMAAdEvent_AD_BREAK_ENDED: {
self.adContainerView.hidden = YES;
// Trigger an update to send focus to the content player.
self.adBreakActive = NO;
[self setNeedsFocusUpdate];
break;
}
case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
// Resume playback after the user has closed the dialog.
[self.videoDisplay play];
break;
}
default:
break;
}
}
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
// Fall back to playing the backup stream.
NSLog(@"StreamManager error: %@", error.message);
[self playBackupStream];
}
Swift
// MARK: - IMAStreamManagerDelegate
func streamManager(_ streamManager: IMAStreamManager, didReceive event: IMAAdEvent) {
print("StreamManager event \(event.typeString).")
switch event.type {
case IMAAdEventType.STREAM_STARTED:
self.startMediaSession()
case IMAAdEventType.STARTED:
// Log extended data.
if let ad = event.ad {
let extendedAdPodInfo = String(
format: "Showing ad %zd/%zd, bumper: %@, title: %@, "
+ "description: %@, contentType:%@, pod index: %zd, "
+ "time offset: %lf, max duration: %lf.",
ad.adPodInfo.adPosition,
ad.adPodInfo.totalAds,
ad.adPodInfo.isBumper ? "YES" : "NO",
ad.adTitle,
ad.adDescription,
ad.contentType,
ad.adPodInfo.podIndex,
ad.adPodInfo.timeOffset,
ad.adPodInfo.maxDuration)
print("\(extendedAdPodInfo)")
}
break
case IMAAdEventType.AD_BREAK_STARTED:
if let adContainerView = self.adContainerView {
adContainerView.isHidden = false
}
// Trigger an update to send focus to the ad display container.
adBreakActive = true
setNeedsFocusUpdate()
break
case IMAAdEventType.AD_BREAK_ENDED:
if let adContainerView = self.adContainerView {
adContainerView.isHidden = true
}
// Trigger an update to send focus to the content player.
adBreakActive = false
setNeedsFocusUpdate()
break
case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
// Resume playback after the user has closed the dialog.
self.videoDisplay.play()
break
default:
break
}
}
func streamManager(_ streamManager: IMAStreamManager, didReceive error: IMAAdError) {
print("StreamManager error: \(error.message ?? "Unknown Error")")
}
Et voilà ! Vous demandez et diffusez désormais des annonces avec le SDK IMA DAI. Pour en savoir plus sur les fonctionnalités avancées du SDK, consultez les autres guides ou les exemples sur GitHub.