Le SDK Brightcove v6.9.0 a été publié le 22 octobre 2019, et il comprend plusieurs changements (comme on peut le voir dans les notes de mise à jour). Mais dans ce billet, je veux parler spécifiquement des changements apportés au plugin SSAI, en particulier la prise en charge ajoutée de Live SSAI.
APERÇU DU SSAI EN DIRECT
Qu'est-ce que le SSAI en direct ? En bref, le SSAI en direct est un flux en direct qui contient des publicités assemblées de manière dynamique. Vous trouverez plus d'informations sur l'API SSAI en direct dans Live API : Server-Side Ad Insertion (SSAI)") - et consultez également Video Cloud SSAI Overview pour en savoir plus sur le SSAI en général.
Lorsque vous lisez un flux SSAI en direct dans n'importe quel lecteur, vous verrez le contenu et les publicités comme faisant partie du même flux, et il n'y aura pas d'indication visuelle entre les deux. C'est là que le SDK et le plugin SSAI de Brightcove s'avèrent utiles. Le plugin SSAI détectera la diffusion d'une pause publicitaire et le contrôleur changera pour afficher des informations utiles, telles que la durée de la pause publicitaire, la durée de la publicité individuelle et le compte à rebours du numéro de la publicité.
POUR COMMENCER
Avant de commencer à parler d'Android et du code du plugin SSAI, vous devrez faire les choses suivantes :
- Créer une configuration d'annonce en direct
- Configurez votre flux en direct
- Trouvez et copiez votre Live adConfigId
CRÉER UNE CONFIGURATION PUBLICITAIRE EN DIRECT
Vous devez créer une configuration publicitaire de la même manière que pour une vidéo VOD. Pour ce faire, veuillez suivre le guide suivant : Créer une configuration publicitaire Live. Vous pouvez également consulter la rubrique Implémentation de publicités côté serveur dans le module Live.
CONFIGURER VOTRE FLUX EN DIRECT
Pour créer votre flux en direct avec la prise en charge SSAI, veuillez suivre les étapes suivantes : Création d'un événement en direct prenant en charge les publicités côté serveur.
TROUVER ET COPIER VOTRE ADCONFIGID LIVE
Lorsque vous créez une configuration publicitaire en direct à l'étape 1, vous obtenez un identifiant et vous pourriez être tenté de l'utiliser comme adConfigId, de la même manière que pour le SSAI VOD. Cependant, ce n'est pas l'identifiant dont nous avons besoin pour le SSAI en direct.
Pour trouver le Live adConfigIdvous devez suivre les étapes décrites dans Publier l'événement en direct. Dans la dernière étape, vous pourrez voir l'URL du lecteur. Cette URL de lecteur contient l'élément adConfigId. Vous pourrez la différencier parce que cette adConfigId commence par “live.”
DEMANDER VOTRE VIDÉO SSAI EN DIRECT AVEC LE PLUGIN SSAI
Nous sommes maintenant prêts à demander la vidéo et à la lire.
La première chose à faire est de créer un fichier HttpRequestConfig
avec l'objet Live adConfigId.
String adConfigIdKey = "ad_config_id";
String adConfigIdValue = "live.eb5YO2S2Oqdzlhc3BCHAoXKYJJl4JZlWXeiH49VFaYO2qdTkNe_GdEBSJjir";
HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
.addQueryParameter(adConfigIdKey, adConfigIdValue)
.build();
Deuxièmement, nous créons le SSAIComponent
qui traite le flux SSAI en direct de la même manière qu'un flux SSAI en vidéo à la demande.
SSAIComponent plugin = new SSAIComponent(this, brightcoveVideoView);
Ensuite, nous créons le Catalog
objet.
Catalog catalog = new Catalog(eventEmitter, accountId, policyKey);
Enfin, nous effectuons la demande de vidéo à l'aide de la fonction HttpRequestConfig
préalablement créé et nous traitons la vidéo reçue avec le plugin SSAI. Le plugin SSAI ajoutera automatiquement la vidéo à la vue vidéo de Brightcove.
catalog.findVideoByID(videoId, httpRequestConfig, new VideoListener() {
@Override
public void onVideo(Video video) {
plugin.processVideo(video);
}
});
Vous remarquerez que le processus est exactement le même que pour un SSAI VOD. La seule différence est l'adConfigId utilisé.
CHANGEMENTS DE RUPTURE
Dans le plugin SSAI v6.9.0, nous avons dû introduire une rupture potentielle en raison d'un problème lié à la position de la tête de lecture lors de l'interruption et de la reprise de la vidéo en direct. Cette modification n'aura d'impact que si vous utilisez la fonction Event.PLAYHEAD_POSITION
de l'une ou l'autre des propriétés EventType.PROGRESS
ou EventType.AD_PROGRESS
événement.
Le Event.PLAYHEAD_POSITION
dans les versions précédentes contenait la position relative de la tête de lecture par rapport à la publicité ou au contenu principal, mais elle a la position absolue de la tête de lecture dans la version 6.9.0.
Permettez-moi de l'expliquer à l'aide d'un exemple. Dans la figure suivante, nous avons une vidéo VOD SSAI d'une durée totale de 43 secondes. Le contenu principal dure 15 secondes, et il y a trois publicités, un pré-roll de 6 secondes, un mid-roll de 14 secondes et un post-roll de 8 secondes. Lorsque nous commençons à lire le mid-roll, la position absolue de la tête de lecture sera de 11 secondes, mais la position relative de la tête de lecture par rapport au mid-roll sera de zéro. La position de la tête de lecture relative par rapport au milieu du rouleau sera de zéro. Event.PLAYHEAD_POSITION
est nulle dans les versions antérieures, mais elle est de 11 secondes dans la version 6.9.0.
REMARQUE: toutes les valeurs de position de la tête de lecture sont exprimées en millisecondes dans le SDK de Brightcove.
D'autre part, nous avons également introduit une nouvelle propriété d'événement appelée Event.PROGRESS_BAR_PLAYHEAD_POSITION
qui contient la position relative de la tête de lecture. Ce nom décrit mieux son objectif, qui est d'afficher la position de la tête de lecture du bloc en cours de lecture (publicité ou contenu) à l'utilisateur par l'intermédiaire de la barre de progression. Cela dit, si vous dépendez de la fonction Event.PLAYHEAD_POSITION
il suffit de commencer à utiliser Event.PROGRESS_BAR_PLAYHEAD_POSITION
au lieu de cela.
Le Event.ORIGINAL_PLAYHEAD_POSITION
est restée inchangée à des fins de compatibilité et contient toujours la position absolue de la tête de lecture.
Le tableau suivant résume les changements :
Propriété de l'événement | Précédent la version 6.9.0 | 6.9.0 et plus |
Event.PLAYHEAD_POSITION |
Position relative de la tête de lecture | Position absolue de la tête de lecture |
Event.ORIGINAL_PLAYHEAD_POSITION |
Position absolue de la tête de lecture | Position absolue de la tête de lecture |
Event.PROGRESS_BAR_PLAYHEAD_POSITION |
N/A | Position relative de la tête de lecture |
CONSIDÉRATIONS LORS DE L'ÉCOUTE DE L'ÉVÉNEMENT DE PROGRESSION
Il y a certaines choses dont vous devez être conscient lorsque vous écoutez la EventType.PROGRESS
dans le plugin SSAI. Le moment où vous ajoutez votre écouteur est important.
Je voudrais commencer par vous donner un aperçu du SDK de Brightcove et du plugin SSAI.
1. Premièrement, le EventType.PROGRESS
est émise à l'origine par le ExoPlayerVideoDisplayComponent
et la classe Event.PLAYHEAD_POSITION
contient la position de la tête de lecture récupérée d'ExoPlayer (je suppose que vous utilisez ExoPlayer), qui est la position absolue de la tête de lecture dans le contexte SSAI.
2. Ensuite, le plugin SSAI attrape les EventType.PROGRESS
et compare la position de la tête de lecture à la ligne de temps SSAI, afin de déterminer s'il s'agit d'un contenu ou d'une publicité. Dans les deux cas, nous calculons la position relative de la tête de lecture et ajoutons un nouvel élément Event.PROGRESS_BAR_PLAYHEAD_POSITION
avec cette valeur.
- S'il s'agit d'un contenu en cours de lecture, nous laissons l'événement se propager au reste des auditeurs.
- En cas de diffusion d'une publicité, nous cessons de propager le message
EventType.PROGRESS
et émet l'événementEventType.AD_PROGRESS
avec les mêmes propriétés.
3. Enfin, tous les auditeurs ajoutés après SSAIEventType.AD_DATA_READY
est émise ou ceux qui ont le @Default
recevra l'annotation EventType.PROGRESS
événement.
En raison de la façon dont le EventType.PROGRESS
est traité, il se peut que vous n'obteniez pas les valeurs attendues, en fonction du moment où vous ajoutez votre écouteur. Par exemple, si vous ajoutez l'élément EventType.PROGRESS
avant l'auditeur SSAIEventType.AD_DATA_READY
est émis, votre listener sera appelé avant qu'il ne soit traité par le plugin SSAI, et vous ne pourrez donc pas obtenir le code Event.PROGRESS_BAR_PLAYHEAD_POSITION
valeur.
NOTE: Cela se produit également dans les versions plus anciennes, mais au lieu de ne pas obtenir de
Event.PROGRESS_BAR_PLAYHEAD_POSITION
la valeurEvent.PLAYHEAD_POSITION
aura la position de tête de lecture absolue au lieu de la position de tête de lecture relative attendue (encore une fois, cela concerne les anciennes versions).NOTE: Ce problème ne se produit pas lorsque l'on écoute le
EventType.AD_PROGRESS
événement.
Si vous êtes confronté à cette situation, vous pouvez essayer quelques solutions :
- Ajouter le
@Default
à votre auditeur. - Ajoutez votre auditeur après
SSAIEventType.AD_DATA_READY
est émise.
AJOUTER @DEFAULT
À VOTRE AUDITEUR
En interne, nous annotons certains écouteurs avec la balise @Default
annotation. Ainsi, tous les auditeurs annotés par défaut attendent que tous les auditeurs non annotés par défaut soient appelés en premier, avant que les auditeurs annotés par défaut ne soient appelés.
En ajoutant cette annotation à votre EventType.PROGRESS
vous le faites attendre jusqu'à ce que le plugin SSAI, qui n'est pas le plugin par défaut, se mette en route. EventType.PROGRESS
traite l'événement. La seule réserve est que ce comportement peut changer si le plugin SSAI EventType.PROGRESS
est annoté avec la balise @Default
dans une prochaine version (je ne prévois pas pour l'instant que cela se produise).
L'exemple se présente comme suit :
eventEmitter.on(EventType.PROGRESS, new EventListener() {
@Default
@Override
public void processEvent(Event event) {
int absolutePlayheadPosition = event.getIntegerProperty(Event.PLAYHEAD_POSITION);
int relativePlayheadPosition = event.getIntegerProperty(Event.PROGRESS_BAR_PLAYHEAD_POSITION);
}
});
AJOUTEZ VOTRE AUDITEUR APRÈS SSAIEVENTTYPE.AD_DATA_READY
EST ÉMIS
Vous pouvez également ajouter votre écouteur après l'élément SSAIEventType.AD_DATA_READY
est émis, ce qui garantit que votre écouteur sera appelé après que le plugin SSAI a eu la possibilité de traiter l'événement.
L'exemple se présente comme suit :
eventEmitter.once(SSAIEventType.AD_DATA_READY, adDataReady -> {
eventEmitter.on(EventType.PROGRESS, progressEvent -> {
int absolutePlayheadPosition = progressEvent.getIntegerProperty(Event.PLAYHEAD_POSITION);
int relativePlayheadPosition = progressEvent.getIntegerProperty(Event.PROGRESS_BAR_PLAYHEAD_POSITION);
});
});
Une mise en garde s'impose. Étant donné que le SSAIEventType.AD_DATA_READY
est émis à chaque fois que la vidéo SSAI (Live et VOD) est ouverte, vous devez vous assurer que vous n'ajoutez pas votre événement EventType.``PROGRESS
plusieurs fois.
Une façon d'éviter cela est de sauvegarder le jeton lors de l'ajout de l'élément EventType.PROGRESS
à l'émetteur d'événements et l'utiliser pour supprimer cet écouteur après chaque SSAIEventType.AD_DATA_READY
événement. Par exemple :
// Declare member variable
private int mCurrentProgressToken = -1;
// Code called every time a SSAI video is processed with the SSAI plugin
eventEmitter.once(SSAIEventType.AD_DATA_READY, adDataReady -> {
if (mCurrentProgressToken != -1) {
eventEmitter.off(EventType.PROGRESS, mCurrentProgressToken);
}
mCurrentProgressToken = eventEmitter.on(EventType.PROGRESS, progressEvent -> {
int absolutePlayheadPosition = progressEvent.getIntegerProperty(Event.PLAYHEAD_POSITION);
int relativePlayheadPosition = progressEvent.getIntegerProperty(Event.PROGRESS_BAR_PLAYHEAD_POSITION);
});
});
RÉSUMÉ
Le plugin SSAI 6.9.0 fait le gros du travail pour prendre en charge le SSAI en direct. Il n'y a pas de changements significatifs dans l'API du plugin utilisé pour commencer à lire les flux SSAI en direct par rapport au SSAI en vidéo à la demande. La partie la plus difficile est de configurer votre flux SSAI en direct et d'identifier le bon identifiant de configuration publicitaire que vous devez transmettre à la fonction HttpRequestConfig
lors de la demande de catalogue.
Vous devez être conscient des ruptures potentielles, mais une fois que vous avez identifié si vous êtes concerné, il est très simple de corriger votre code. Et si vous dépendez de l'application EventType.PROGRESS
vous devez également accorder une attention particulière au moment où vous ajoutez votre écouteur de progression et vérifier que vous obtenez les valeurs attendues.