Les SDK IMA simplifient l'intégration d'annonces multimédias dans vos sites Web et vos 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, qu'il s'agisse de VOD ou de contenu en direct. Le SDK renvoie ensuite un flux vidéo combiné, ce qui vous évite d'avoir à gérer le passage de l'annonce à la vidéo de contenu dans votre application.
Ce guide explique comment lire un flux de diffusion de pod DAI à l'aide du SDK IMA DAI pour CAF.
Avant d'utiliser ce guide, familiarisez-vous avec le protocole Web Receiver du Chromecast Application Framework. Ce guide suppose que vous maîtrisez les concepts de base du récepteur CAF, tels que les intercepteurs de messages et les objets mediaInformation, et que vous savez utiliser l'outil de commande et de contrôle Cast pour émuler un émetteur CAF.
Pour utiliser IMA DAI Pod Serving, vous devez travailler avec un partenaire Pod Serving et disposer d'un compte Ad Manager 360 Advanced. Si vous possédez un compte Ad Manager, contactez votre responsable de compte pour en savoir plus. Pour en savoir plus sur l'inscription à Ad Manager, consultez le Centre d'aide Ad Manager.
Pour en savoir plus sur l'intégration avec d'autres plates-formes ou sur l'utilisation des SDK IMA côté client, consultez SDK Interactive Media Ads.
Présentation de l'insertion dynamique d'annonces IMA DAI
L'implémentation de la diffusion de pods à l'aide du SDK IMA CAF DAI implique deux composants principaux, qui sont présentés dans ce guide :
StreamRequest: objet qui définit une demande de flux adressée aux serveurs publicitaires de Google. Les requêtes spécifient un code réseau, une clé d'élément personnalisée et une clé API facultative, ainsi que d'autres paramètres facultatifs.StreamManager: objet qui gère la communication entre le flux vidéo et le SDK IMA DAI, par exemple en déclenchant des pings de suivi et en transférant les événements de flux à l'éditeur.
Prérequis
- Un compte Cast Developer Console avec des appareils de test enregistrés.
- Une application réceptrice Web hébergée, enregistrée dans la console du développeur Cast et pouvant être modifiée pour héberger le code fourni par ce guide.
- Une application émettrice configurée pour utiliser votre application réceptrice Web. Pour les besoins de cet exemple, utilisez l'outil Cast Command and Control comme émetteur.
Configurer les objets MediaInfo de l'expéditeur
Tout d'abord, configurez l'objet MediaInfo de votre application émettrice pour inclure les champs suivants :
| Champ | Sommaire | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
contentId
|
Identifiant unique de cet élément multimédia.
CONTENT_ID |
||||||||||
contentUrl
|
Facultatif. URL du flux de secours à lire si le flux DAI ne se charge pas.
BACKUP_STREAM_URL |
||||||||||
contentType
|
Facultatif. Type MIME des flux de sauvegarde de contenu. Obligatoire uniquement pour les flux DASH.
CONTENT_STREAM_MIMETYPE |
||||||||||
streamType
|
La chaîne littérale ou la constante utilisée pour cette valeur varie selon la plate-forme de l'expéditeur. | ||||||||||
customData
|
Le champ customData contient un magasin de clés-valeurs de champs obligatoires supplémentaires. Dans cet exemple, il contient les paramètres de votre flux d'insertion d'annonce dynamique. Dans une application de production, vous pouvez transmettre un identifiant que votre application réceptrice Cast utilisera pour récupérer ces paramètres avec une requête côté serveur.
|
Voici quelques exemples de code pour vous aider à vous lancer :
Web
Pour configurer ces valeurs dans un émetteur Web Cast, commencez par créer un objet MediaInfo avec les données requises, puis envoyez une requête de chargement au récepteur Web.
// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "CONTENT_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.LIVE;
mediaInfo.customData = {
daiStreamType: "DAI_STREAM_TYPE",
networkCode: "NETWORK-CODE",
customAssetKey: "CUSTOM_ASSET_KEY",
apiKey: "API_KEY"
};
// Make load request to cast web receiver
const castSession = cast.framework.CastContext.getInstance().getCurrentSession();
const request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
() => { console.log('Load succeed'); },
(errorCode) => { console.log('Error code: ' + errorCode); });
Android
Pour configurer ces valeurs dans un émetteur Web Cast, commencez par créer un objet MediaInfo avec les données requises, puis envoyez une requête de chargement au récepteur Web.
JSONObject customData = new JSONObject()?
.put("daiStreamType", "DAI_STREAM_TYPE")
.put("networkCode", "NETWORK-CODE")
.put("customAssetKey", "CUSTOM_ASSET_KEY")
.put("apiKey", "API_KEY");
MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
.setContentUrl("BACKUP_STREAM_URL")
.setContentType("CONTENT_STREAM_MIMETYPE")
.setStreamType(MediaInfo.STREAM_TYPE_LIVE)
.setCustomData(customData)
.build();
RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());
iOS (Obj-C)
Pour configurer ces valeurs dans un émetteur Web Cast, commencez par créer un objet GCKMediaInformation avec les données requises, puis envoyez une requête de chargement au récepteur Web.
NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
@"daiStreamType": @"DAI_STREAM_TYPE",
@"networkCode": @"NETWORK-CODE",
@"customAssetKey": @"CUSTOM_ASSET_KEY",
@"apiKey": @"API_KEY"};
mediaInfoBuilder.customData = customData;
GCKMediaInformationBuilder *mediaInfoBuilder =
[[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeLive;
mediaInfoBuilder.customData = customData;
self.mediaInformation = [mediaInfoBuilder build];
GCKRequest *request = [self.sessionManager.currentSession.remoteMediaClient loadMedia:self.mediaInformation];
if (request != nil) {
request.delegate = self;
}
iOS (Swift)
Pour configurer ces valeurs dans un émetteur Web Cast, commencez par créer un objet GCKMediaInformation avec les données requises, puis envoyez une requête de chargement au récepteur Web.
let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
print("invalid mediaURL")
return
}
let customData = [
"daiStreamType": "DAI_STREAM_TYPE",
"networkCode": "NETWORK-CODE",
"customAssetKey": "CUSTOM_ASSET_KEY",
"region": "API_KEY"
]
let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.Live
mediaInfoBuilder.customData = customData
mediaInformation = mediaInfoBuilder.build()
guard let mediaInfo = mediaInformation else {
print("invalid mediaInformation")
return
}
if let request = sessionManager.currentSession?.remoteMediaClient?.loadMedia
(mediaInfo) {
request.delegate = self
}
Outil CAC
Pour configurer ces valeurs dans l'outil Cast commande et contrôle, cliquez sur l'onglet "Load Media" (Charger un contenu multimédia), puis définissez le type de requête de chargement personnalisé sur "LOAD" (CHARGER). Remplacez ensuite les données JSON dans la zone de texte par le code JSON suivant :
{
"media": {
"contentId": "CONTENT_ID",
"contentUrl": "BACKUP_STREAM_URL",
"contentType": ""CONTENT_STREAM_MIMETYPE"",
"streamType": "LIVE",
"customData": {
"daiStreamType": "DAI_STREAM_TYPE",
"networkCode": "NETWORK-CODE",
"customAssetKey": "CUSTOM_ASSET_KEY",
"oAuthToken": "API_KEY"
}
}
}
Cette requête de chargement personnalisée peut être envoyée au récepteur pour tester les étapes restantes.
Créer un récepteur CAF de base
Créez un récepteur Web personnalisé, comme indiqué dans le guide du récepteur Web personnalisé du SDK CAF.
Le code de votre récepteur doit se présenter comme suit :
<html>
<head>
<script
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
</script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
// ...
</script>
</body>
</html>
Importer le SDK IMA DAI et obtenir le Player Manager
Ajoutez une balise de script pour importer le SDK IMA DAI pour CAF dans votre récepteur Web, juste après le script chargeant CAF. Dans le tag de script, stockez le contexte du récepteur et le gestionnaire de lecteur en tant que constantes avant de démarrer le récepteur.
<html>
<head>
<script
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
castContext.start();
</script>
</body>
</html>
Initialiser le gestionnaire de flux IMA
Initialisez le gestionnaire de flux IMA.
<html>
<head>
<script type="text/javascript"
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const streamManager = new google.ima.cast.dai.api.StreamManager();
castContext.start();
</script>
</body>
</html>
Créer l'intercepteur de charge du gestionnaire de flux
Avant que vos éléments multimédias ne soient transmis à CAF, créez votre demande de flux dans un intercepteur de message LOAD.
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const streamManager = new google.ima.cast.dai.api.StreamManager();
/**
* Creates a livestream request object for a Pod Serving stream.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {StreamRequest} an IMA stream request
*/
const createStreamRequest = (castRequest) => { /* ... */};
/**
* Initates a DAI stream request for the final stream manifest.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
*/
const createDAICastRequest = (castRequest) => {
return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
.then((castRequestWithPodStreamData) => {
console.log('Successfully made DAI stream request.');
// ...
return castRequestWithPodStreamData;
})
.catch((error) => {
console.log('Failed to make DAI stream request.');
// CAF will automatically fallback to the content URL
// that it can read from the castRequest object.
return castRequest;
});
};
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, createDAICastRequest);
castContext.start();
Créer la requête de flux
Complétez la fonction createStreamRequest pour créer un flux de diffusion de pod basé sur la requête de chargement CAF.
/**
* Creates a livestream request object for a Pod Serving stream.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {StreamRequest} an IMA stream request
*/
const createStreamRequest = (castRequest) => {
const customData = castRequest.media.customData;
let streamRequest;
if (customData.daiStreamType == "LIVE") {
streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
streamRequest.customAssetKey = customData.customAssetKey;
streamRequest.networkCode = customData.networkCode;
streamRequest.apiKey = customData.apiKey;
} else if (customData.daiStreamType == "VOD") {
streamRequest = new google.ima.cast.dai.api.PodVodStreamRequest();
streamRequest.networkCode = customData.networkCode;
streamRequest.apiKey = customData.apiKey;
}
return streamRequest;
};
Récupérer le fichier manifeste raccordé auprès de votre VTP
Si votre requête de flux aboutit, utilisez streamManager.getStreamId() pour récupérer l'ID du flux. Votre partenaire technique vidéo ou votre outil de manipulation de fichier manifeste personnalisé vous fournira des instructions pour récupérer une URL de fichier manifeste à l'aide de cet ID de flux.
Une fois que vous avez récupéré l'URL de votre fichier manifeste, remplacez l'URL contentUrl existante par la nouvelle URL manifestUrl.
Enfin, avant de renvoyer le fichier manifeste de flux modifié, appelez la méthode loadStreamMetadata sur votre streamManager pour informer le SDK IMA qu'il peut demander des métadonnées de flux en toute sécurité. Cet appel n'est nécessaire que pour les flux de VOD.
/**
* Initates a DAI stream request for the final stream manifest.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
*/
const createDAICastRequest = (castRequest) => {
return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
.then((castRequestWithPodStreamData) => {
console.log('Successfully made DAI stream request.');
// This is a sample VTP integration. Consult your VTP documentation
// for how to retrieve an ad-stitched stream manifest URL.
const manifestTemplate = "https://.../manifest.m3u8?gam_stream_id=[[STREAMID]]";
const streamId = streamManager.getStreamId();
const manifestUrl = manifestTemplate.replace('[[STREAMID]]', streamId)
// Assign your manifestUrl to the request's content URL.
castRequestWithPodStreamData.media.contentUrl = manifestUrl;
// After generating the manifest URL, VOD streams must notify the
// IMA SDK that it is safe to request ad pod metadata.
// This is only necessary for VOD streams. It is a no-op for
// livestreams, so no conditional is needed.
streamManager.loadStreamMetadata();
return castRequestWithPodStreamData;
})
.catch((error) => {
console.log('Failed to make DAI stream request.');
// CAF will automatically fallback to the content URL
// that it can read from the castRequest object.
return castRequest;
});
};
Nettoyer les assets IMA DAI
Une fois que vous avez demandé et affiché des annonces dans un flux de diffusion de séries d'annonces avec le SDK IMA DAI, nous vous suggérons de nettoyer toutes les ressources une fois la session de diffusion de séries d'annonces terminée. Appelez StreamManager.destroy() pour arrêter la lecture du flux, arrêter tout le suivi des annonces et libérer tous les éléments de flux chargés.