Coupures publicitaires

Présentation

Le SDK Web Receiver est compatible de façon native avec les coupures publicitaires et les annonces associées. dans un flux multimédia donné. Elle fournit des API permettant de définir la position de l'annonce, la source de l'annonce et le comportement des coupures publicitaires et de leurs clips associés. Dans ce guide, Break désigne un intervalle de lecture comportant une ou plusieurs annonces ou bumpers, et chaque annonce ou bumper est appelé BreakClip Ces coupures sont associées aux contenus multimédias en cours de chargement ou de lecture.

Types d'annonces

Le SDK Web Receiver prend en charge l'insertion d'annonces côté client (CSAI) d'insertion d'annonces intégrées. Les annonces assemblées par le client peuvent être définies manuellement par application ou extraite des fichiers de modèle VAST et VMAP. Les annonces assemblées au serveur doivent être spécifiées manuellement avant le chargement du contenu, intégrées ou de manière dynamique pendant la lecture du contenu sous forme de annonces développées intégrées annonces. Les implémentations de chacun de ces types d'annonces sont décrites en détail ci-dessous.

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

Types de timeline du joueur

Lors de la création d'une instance de lecteur, le SDK Web Receiver sélectionne un type de timeline à utiliser prennent en charge la diffusion d'annonces pendant la lecture du contenu. Chaque chronologie active certaines annonces les types de coupures publicitaires à ajouter. Le type de chronologie est déterminé par types d'annonces présents lors du temps de chargement MediaInformation des LoadRequestData. En cas de coupures publicitaires intégrées, la chronologie embedded est sélectionnée. Si des coupures publicitaires assemblées par le client sont présentes, la chronologie stitched est sélectionnée. Si aucune annonce n'est présente, le SDK utilise par défaut embedded calendrier. Une fois la chronologie sélectionnée, vous ne pouvez plus la modifier pour la période actuelle élément multimédia. Le tableau ci-dessous fournit une description détaillée de chaque calendrier.

Les figures 1 à 3 ci-dessous illustrent des contenus avec des types d'annonces variés, ainsi que leurs les valeurs de chronologie respectives. Le contenu est configuré avec une coupure pré-roll. contenant deux coupures publicitaires, ainsi que des coupures publicitaires mid-roll et post-roll, avec une seule coupure. Durée d'exécution de l'horloge depuis le début de la lecture du contenu L'heure multimédia du contenu principal et l'heure de la coupure publicitaire sont alignés sous chaque image.

</ph> <ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

Positionnement de la coupure

Le SDK Web Receiver permet aux développeurs de spécifier l'emplacement des coupures publicitaires. en paramétrant le paramètre position de Break. Cette valeur correspond à l'heure de lecture du contenu principal et peuvent être utilisées pour créer des coupures publicitaires pre-roll, mid-roll et post-roll. Ils sont définis comme suit:

Matrice d'interopérabilité

Pour vous faire une idée rapide, nous vous invitons à consulter le Tableau 1 pour obtenir une vue d'ensemble des types d'annonces et des leur compatibilité avec les fonctionnalités liées aux annonces.

Événements

Lorsque des coupures de clé se produisent, le SDK Cast envoie des événements de type BreaksEvent Une application réceptrice peut s'y abonner à l'aide de PlayerManager. addEventListener API.

Ces événements peuvent être utilisés à des fins d'analyse et de suivi de la lecture des annonces. Lorsque VMAP (Video Multiple Ad Playlist) et VAST (Video Ad Serving Template) tous les événements de suivi standards fournis dans les réponses sont automatiquement envoyé par le SDK.

Les types d'événements sont répertoriés dans le Tableau 2 avec une description détaillée quand ils sont déclenchés.

</ph>

Insertion d'annonces

Le SDK Cast permet aux applications d'insérer et de supprimer des annonces à différents moments d'une session Cast. Les deux types d'insertion d'annonces sont statiques et dynamiques. Pour insérer des annonces statiques, vous devez spécifier les annonces dans le champ LoadRequestData avant la création du joueur. L'insertion dynamique d'annonces utilise BreakManager addBreak API permettant d'insérer des coupures publicitaires dans le contenu déjà chargé. Chaque type d'insertion est compatible avec certains types d'annonces. Une compatibilité consultez la matrice d'interopérabilité.

Insertion d'annonces statiques

L'insertion statique d'annonces se caractérise par l'ajout des métadonnées d'annonce pertinentes avant à la création de joueurs. Ces informations sont fournies dans le MediaInformation de LoadRequestData. Par exemple, ils peuvent être définis dans le réseau de chargement d'origine, ou il peut être inséré par l'application réceptrice Web en interceptant la requête LOAD. Une fois que LoadRequestData est renvoyé à la Web Receiver SDK pour le traitement, le lecteur est créé. Plus d'infos sur chargement des contenus multimédias. L'exemple ci-dessous montre une annonce assemblée manuellement par le client ajoutée à la requête LOAD intercepteur.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

Insertion dynamique d'annonce

L'insertion dynamique d'annonces consiste à insérer une coupure publicitaire pendant la lecture du contenu lecture. Pour ce faire, il faut obtenir une instance de BreakManager et appeler la addBreak API. Cela nécessite au moins deux paramètres : intégrée développée Break et un tableau de BreakClip. Une troisième propriété facultative est incluse pour forcer l'envoi des modifications à expéditeurs connectés via une diffusion MediaStatus lorsqu'ils sont définis sur true. Quand ? l'ajout de coupures publicitaires et d'extraits, les ID correspondants doivent être uniques. Ces annonces ne peuvent être ajoutés qu'une fois le lecteur créé. Le SDK Web Receiver se déclenche la PLAYER_LOADING une fois le lecteur créé. L'exemple ci-dessous montre l'utilisation dans Un gestionnaire d'événements qui répond aux modifications apportées aux métadonnées ID3 d'un flux crée des objets Break et BreakClip pour l'insérer dans la timeline.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

Suppression d'annonces dynamiques

Pour supprimer les coupures dynamiques, l'application doit appeler removeBreakById pendant la lecture. La fonction utilise un identifiant de chaîne de la coupure supprimé de la chronologie. L'élément breakId spécifié doit pointer vers un élément intégré la coupure publicitaire agrandie. Si un autre type de coupure publicitaire est détecté, la coupure restent dans la chronologie. Consultez l'exemple ci-dessous pour éviter de faire une pause.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.removeBreakById('break_midroll_embedded_expanded');

Comportement des coupures publicitaires

Le SDK définit un comportement par défaut lorsque le joueur apparaît dans les pauses ou en sort. et permet de le personnaliser davantage à l'aide de certaines des API fournies dans BreakManager

Comportement par défaut des coupures publicitaires

Lorsqu'un Break est saisi lors d'une lecture normale ou en recherchant un Break, le SDK évalue si l'utilisateur l'a déjà vue en vérifiant la isWatched . Une fois créée, la valeur par défaut d'un saut pour cette propriété est false. Si la propriété est true, le saut n'est pas lu lorsque la propriété est saisie et main la lecture du contenu se poursuivra. Si la propriété est false, le saut de ligne est lu lorsque vous y avez accédé.

Lorsque vous recherchez d'anciennes coupures publicitaires, l'implémentation par défaut obtient toutes les Break éléments dont position est compris entre seekFrom et seekTo valeurs. À partir de cette liste de coupures, le SDK lit les Break dont le position est la plus proche de la valeur seekTo et dont la propriété isWatched est définie sur false La propriété isWatched de cette coupure est alors définie sur true et le lecteur commence à lire les extraits vidéo. Une fois la pause regardée, le contenu principal reprendra la lecture à partir de la position seekTo. Si aucune s'affiche, la lecture du contenu principal est interrompue, et le contenu principal est réactivé. en cours de lecture en position seekTo.

Pendant la lecture des interruptions, le SDK diffusera toutes les mises à jour pertinentes aux applications émettrices du MediaStatus Ces applications utiliseront les annonces pour mettre à jour leur UI pour les annonces en lisant la breakStatus . Cette propriété n'est définie que lors de l'interruption de la lecture.

Les applications réceptrices peuvent également interroger directement les informations concernant position de la tête de lecture par rapport à l'heure actuelle de l'élément BreakClip affiché en appelant PlayerManager getBreakClipCurrentTimeSec De même, les applications peuvent interroger la durée du BreakClip actuel en Appel en cours getBreakClipDurationSec

Comportement des coupures personnalisées

Le comportement par défaut pour les coupures publicitaires peuvent être modifiées à l'aide de la setBreakClipLoadInterceptor et setBreakSeekInterceptor fournies dans BreakManager.

Intercepteur de recherche de rupture

L'intercepteur de recherche de pause permet à l'appli de contrôler le comportement de la recherche avant les coupures publicitaires. La fonction est déclenchée lorsqu'une opération de recherche est demandée pour avancer ou reculer sur une ou plusieurs coupures. Lorsqu'elle est appelée, la méthode BreakSeekData est transmise en tant que paramètre à la fonction de rappel. L'objet BreakSeekData contient un tableau de Break objets dont la propriété position est définie sur un nombre compris entre la durée de la tête de lecture est définie comme seekFrom et l'heure de la destination de la recherche seekTo

Cet intercepteur autorise les objets Break dans les coupures respectives d'être modifiées. Une fois implémenté, cet intercepteur doit spécifier l'annonce se lance en renvoyant un objet BreakSeekData modifié en option. La le joueur lit toutes les coupures incluses dans la valeur renvoyée. Si une valeur de null ou rien n'est renvoyé par l'intercepteur de recherche de pauses, la rupture est ont été ignorées.

L'exemple ci-dessous présente une implémentation simple de l'intercepteur remplace le comportement par défaut pour regarder toutes les coupures publicitaires recherchées avec la à l'exception des coupures publicitaires déjà visionnées.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

Intercepteur de chargement des extraits

Vous pouvez modifier un objet BreakClip à l'aide de l'intercepteur de chargement des extraits avant le début de la lecture.

L'intercepteur de chargement des extraits vidéo n'est appelé que pour un saut dans la chronologie assemblée et peuvent être définis à l'aide setBreakClipLoadInterceptor Avant d'entrer dans un Break, cet intercepteur est appelé une fois pour chaque personne BreakClip défini dans cette coupure. Le SDK transmet l'original BreakClip comme paramètre de la fonction de rappel. L'application peut alors modifier ce BreakClip et le renvoyer afin que le SDK puisse récupérer et afficher la coupure avec la configuration mise à jour. Si la valeur null ou rien n'est renvoyée, le saut de ligne l'extrait est passé.

Vous trouverez ci-dessous un exemple qui modifie le contentUrl des coupures publicitaires avec Une fonction utilitaire appelle getUrlFromClipId, où le id de BreakClip est mappée à une URL.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

Omission de l'annonce

Le SDK Web Receiver fournit des API permettant d'ignorer les coupures publicitaires et les coupures publicitaires individuelles pendant une coupure publicitaire. Le SDK permet également aux utilisateurs d'ignorer interagissant avec leurs applications émettrices ou leurs écrans connectés.

Extraits de coupures désactivables par l'utilisateur

Définir des coupures publicitaires comme désactivables permet aux utilisateurs d'interagir avec l'expéditeur connecté et les écrans connectés pour pouvoir ignorer le reste d'une l'extrait d'arrêt en cours de lecture. Définir le paramètre whenSkippable sur un nombre non négatif de secondes permet d'activer la fonctionnalité BreakClip. Le lecteur considère que l'extrait de la coupure est désactivable une fois que d'arrêt a été lu pendant ce nombre de secondes. Définir cette valeur sur 0 permet aux utilisateurs d'ignorer immédiatement l'extrait vidéo.

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

Ces informations peuvent être définies dans la requête de chargement initiale de l'expéditeur ou dans la application réceptrice. Extrait d'une coupure publicitaire dans une coupure publicitaire de la chronologie assemblée s'il est ignoré arrêtera la lecture de l'extrait actuel. Le lecteur charge soit casser l'extrait s'il est présent ou charger le contenu principal. Lorsqu'il est ignoré, un extrait vidéo faisant une pause dans une la coupure publicitaire chronologie intégrée recherche la fin de l'extrait et pour poursuivre la lecture du flux à ce stade.

Ignorer les annonces à l'aide d'un programme

Les annonces peuvent également être ignorées automatiquement sans aucune intervention de l'utilisateur.

Pour ignorer une pause complète de la lecture, une application doit définir le paramètre isWatched d'un Break à true. Cette opération peut être effectuée à tout moment pendant le chargement la séquence ou la lecture de contenu. La propriété isWatched est évaluée par la joueur lorsque la valeur position d'une pause est atteinte dans l'heure actuelle du contenu principal. À À ce stade, le joueur détermine s'il convient ou non de faire une pause. Reportez-vous à l'exemple ci-dessous, qui parcourt toutes les coupures et modifie le lors du chargement du lecteur.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

Pour ignorer un extrait vidéo spécifique de manière programmatique, Utilisez l'intercepteur de chargement des extraits. Par renvoie null ou ne renvoie pas de valeur dans la fonction de rappel, l'extrait cette coupure est ignorée.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});