Guide d’introduction au SDK

Guide d'introduction aux API de Triton Digital

Introduction

Ce document décrit les informations essentielles requises pour une intégration réussie des services de streaming de Triton Digital, quand l'éditeur souhaite intégrer le niveau du protocole/API et NE PAS utiliser le SDK. Il a pour objectif d'aider l'éditeur à procéder à une intégration directe aux services de streaming de Triton Digital, sans utiliser le SDK de Triton Digital. Si vous êtes intéressé par la mise en œuvre SDK, nous vous invitons à contacter Triton Digital pour otenir les bons documents.

Ce guide d'introduction aux API part du principe que vous êtes familier avec certains concepts considérés comme étant des connaissances communes aux développeurs d'applications mobiles Web, Android et iOS, notamment (mais sans s'y limiter) :

• Comment utiliser Xcode pour le développement Apple.
• Comment utiliser et intégrer https://google.github.io/ExoPlayer/ dans votre code Android.
• La compréhension de la construction des chaînes d'URL (encodage URL, encodage de Base64, transmission des paramètres URL et requêtes GET/POST).
• En utilisant Web Sockets.
• La connaissance générale du travail avec les horodatages Epoch et leur conversion dans un format lisible par tous.
• Connaissance générale de l'analyse, de VAST et de l'intégration du code de publicité.

Documents de référence

Ce document fournit des informations de haut niveau et fait référence à un certain nombre d'autres documents d'utilisateur Triton Digital où vous trouverez plus de détails. 

Les documents de référence incluent :

• Spécification de streaming Triton Digital
• Spécification à la demande Triton Digital
• Caractéristiques techniques des publicités de Triton Digital
• SDK Triton Digital Mobile (Android)
• SDK Triton Digital Mobile (iOS)

Fonctionnalité essentielle

Dans les grandes lignes, sa fonctionnalité principale consiste à se connecter au(x) bon(s) montage(s) sur le réseau de streaming en direct Triton Digital au moyen d'une URL qui garantit le respect de certaines règles basiques de connexion, de diffusion en direct et de mesure. Votre lecteur ou votre application peut par ailleurs se connecter pour recevoir des appels publicitaires à la demande (généralement avant la diffusion). Cette fonctionnalité de publicité à la demande est optionnelle, la plupart des clients préférant en effet que les publicités soient insérées par les serveurs de diffusion, et non gérées par le lecteur ou les applications.

Streaming en direct :

• Se connecter au flux et lancer la lecture du flux audio.
• Assurer la conformité (éviter le « double play », éviter la « pause », le retour en arrière pour la connectivité).
• Lire les métadonnées du flux et réagir aux événements tels que les pauses et les insertions publicitaires.
• Afficher et rapporter tous les événements relatifs à VAST/DAAST.
• Établir des méthodes de connexion et élaborer la liste des paramètres (pour les paramètres que le lecteur transmet au service de streaming de Triton Digital).
• Assurez-vous d'avoir un paramètre HTTP « UserAgent » correctement configuré. Celui-ci est largement utilisé à des fins de mesure et d'analyse.
• Fournir un certain niveau d'intelligence de connectivité (par exemple, se connecter au bon type de flux pris en charge par l'appareil demandeur).

Voir ci-dessous pour plus de détails sur les fonctionnalités essentielles du streaming en direct.

À la demande :

• Pour recevoir des publicités VAST/DAAST, contactez un terminal à la demande.
• Afficher et rapporter tous les événements relatifs à VAST/DAAST.
• Connectez-vous au fichier et lisez-le.
• Offrir une interface utilisateur pour permettre la « recherche » dans le fichier lorsque cette option est possible.

Diffusion en direct

Cette section fournit plus de détails sur les fonctionnalités essentielles du streaming en direct.

Connexion et lecture instantanée

Il y a deux méthodes légèrement différentes pour se connecter à un flux sur le réseau de streaming Triton Digital. Il existe des points d'entrée d'URL pour différents scénarios et utilisations de connectivité, notamment :

• Redirecteur de flux en direct
• XML de transfert

Ces points d'entrée sont expliqués plus en détail ci-dessous.

Redirecteur de flux en direct

Pour plus de simplicité, cette méthode est celle qui est recommandée pour vous connecter aux flux de Triton Digital. Ce point de terminaison sera toujours renvoyé sous la forme d’une redirection d’URL, vous n’avez donc pas besoin d’une connaissance approfondie du XML d’approvisionnement de Triton Digital pour le faire fonctionner.

Vous trouverez plus de détails sur la façon de créer l’URL permettant de se connecter à votre flux en direct dans la section Spécification du streaming sur la redirection du flux en direct.

Par exemple, si votre station est KSAD utilisant un montage AAC (« KSADAAC ») sur un flux HLS, votre URL sera :

http://playerservices.streamtheworld.com/api/livestream-redirect/KSADAAC.m3u8 

Les nouvelles tentatives devraient être traitées correctement. Si un serveur de streaming est indisponible, vous pouvez réessayer avec la même URL en utilisant un mécanisme de temporisation. Le service de redirection du lecteur choisira au hasard un des multiples serveurs parmis différents centres de données pour chaque demande.

Pour plus d’informations sur la gestion des connexions, reportez-vous également à la section Spécification de streaming Triton Digital sur la gestion des connexions.

Pour plus d’informations sur HLS, reportez-vous à la section Spécification de streaming sur HLS.

XML de transfert

Le XML de transfert vous donne le plus de contrôle, car il fait un usage intensif des composants personnalisés du SDK de Triton Digital, mais exige aussi le plus d'efforts en termes de compréhension des composants et de leur utilisation appropriée. Toutefois, si vous souhaitez simplement vous connecter à un flux à l’aide du HTTP Live Streaming (HLS), nous vous recommandons plutôt d’utiliser la méthode de redirection du streaming en direct (voir ci-dessous).

L'URL XML d'approvisonnement contient tout ce qui est « connu » de la station à laquelle vous vous connectez. Si vous suivez la logique d'approvisionnement, vous pouvez toujours trouver un point d'entrée URL dans tous les formats possibles et disponibles pour cette station. Votre code peut les parcourir ou être spécifique à la méthode de connexion appropriée. Il renseigne également tous les serveurs qui ont un point de connexion disponible.

Cette méthode est principalement utilisée dans les cas où vous avez besoin d'un contrôle total sur la connexion. Par exemple, une base de code unique faite en Xamarin ou JAVA ; la logique de ce à quoi et où se connecter est contrôlée par les bibliothèques de découverte de plate-forme de Xamarin ou Java.

Pour obtenir les meilleurs résultats et le meilleur mécanisme de basculement, suivez les informations sur la gestion des connexions dans la spécification de streaming Triton Digital.

Assurer la conformité

Construisez votre lecteur pour vous assurer qu'il soit conforme aux exigences Triton Metrics.

• N’autorisez pas deux connexions simultanées ou plus (c’est-à-dire un « double jeu »).
• N’autorisez pas la « pause » pendant la diffusion en direct. Utilisez uniquement les fonctions Arrêt-Début. Vous pouvez inclure un bouton « Muet », mais il doit fonctionner de la même façon que Stop - en fait arrêter le flux - et cela doit être clair pour l’auditeur. Pour les mesures, les fonctions Mute et Arrêter sont identiques.  
• Utilisez un schéma « backoff/retry » lors de la connexion, afin d’éviter de saturer les serveurs Triton Digital avec trop de demandes de connexion. Pour plus d’informations, consultez la section Spécification du streaming Triton Digital sur la gestion des connexions et la section sur le streaming en direct HTTP.

Métadonnées

Vous pouvez utiliser Shoutcast pour les métadonnées, mais il n’est pas très répandu. Les métadonnées de bande latérale (SBM) constituent une meilleure option. Il s’agit d’une connexion secondaire qui fournit différents événements en parallèle avec le flux, tels que la liste des pistes pour l’affichage « lecture en cours » et les événements publicitaires pour l’insertion de publicités. Assurez-vous que votre lecteur dispose d'un gestionnaire qui sait comment interpréter ces événements.

Quelques remarques :

• Un événement publicitaire peut contenir un lien vers une URL VAST, qui peut apporter des paramètres publicitaires tels que des bannières, etc.
• L’horodatage des métadonnées dans le flux en direct représente les millisecondes écoulées depuis le début du flux. Les données de bande latérale sont généralement quelques millisecondes plus tard. Vous devez lancer une minuterie sur l'application qui suit le temps écoulé depuis la connexion. Les événements dans les métadonnées contiendront des horodatages indiquant quand le lecteur doit réagir à l'événement. Il est important d'être précis pour les événements impliquant l'insertion de publicité. Si vous ne faites pas d'insertion publicitaire, ce timing n'a pas besoin d'être aussi précis.
• Créez votre propre analyseur VAST ou utilisez un analyseur disponible en ligne, tel que le SDK IMA de Google.
• Veillez à respecter les principes de VAST. Par exemple, assurez-vous de signaler chaque impression et de déclencher chaque URL.
• Ne soyez pas inutilement strict avec l'analyseur VAST. Par exemple, ne rejetez pas les fichiers VAST qui sont d'une version différente de votre analyseur ; il devrait lire VAST 2.0 ou VAST 4.0 même si votre analyseur est en version 3.0.
• Pour plus d’informations, reportez-vous à la section Spécification de streaming Triton Digital concernant les métadonnées de bande latérale.

Configurez votre URL (Liste des paramètres)

La section Spécification de streaming sur l’URL du flux décrit la structure de l’URL et les paramètres que vous pouvez y intégrer. Les paramètres de requête disponibles sont listés ici.

Les paramètres les plus importants que vous devriez utiliser avec l'URL sont :

• LSID.
• SBMID, qui est utilisé pour corréler le flux avec les métadonnées qui lui sont associées.
• Tous les attributs de ciblage. Nous vous recommandons de les préconfigurer autant que possible avant de vous connecter au flux.
• Tous les attributs de localisation.

Rappelez-vous que plus vous utilisez de paramètres, plus vos observations peuvent être précieuses.

Agent utilisateur

L'agent utilisateur du lecteur Web utilisera automatiquement celui fourni par le navigateur, et celui-ci ne peut pas être modifié. Les développeurs peuvent cependant contrôler l'agent utilisateur de leur application.  Configurez judicieusement le gestionnaire d'utilisateurs de votre lecteur, et ce, afin que les analystes de Triton puissent correctement détecter et nommer votre application ou vos appareils. Si vous avez besoin de conseils à ce sujet, contactez un spécialiste des solutions Triton Digital.

Intelligence de connectivité

La gestion des connexions est expliquée dans la spécification du streaming, ici.

Le diagramme de ce document s’applique principalement à la méthode XML d’approvisionnement. C’est plus simple pour la méthode Live Stream Redirector.

Quelques remarques :

• Soyez prêt à vous déconnecter et sachez quoi faire en cas de déconnexion.
• Utilisez les méthodes correctes de connexion et de déconnexion.
• Grâce à un tampon, votre application/lecteur peut gérer les reconnexions afin que celles-ci soient quasiment imperceptibles pour l'auditeur.