Gérez vos vidéos et vos directs depuis votre propre site grâce à l'API DCAST

Si votre produit dispose déjà de ses propres pages, de ses utilisateurs et de sa base de données, renvoyer les gens vers un tableau de bord vidéo distinct est un pas en arrière. Vous voulez que votre propre code ajoute des vidéos, les liste et démarre des diffusions pendant que les visiteurs restent sur votre site. Cet article vous guide dans cette mise en place avec l'API DCAST, les décisions à prendre en premier et les défaillances à vérifier avant le lancement.

Connectez une fois votre site à DCAST via l'API ; ensuite, votre propre code ajoute de nouvelles vidéos et crée des diffusions en direct, sans passer par le tableau de bord DCAST.

Gardez la clé sur votre serveur et décidez qui possède quoi

Avant d'écrire le moindre code de téléversement, décidez où se trouve la clé d'API. Gardez la clé d'API sur votre serveur et ne la placez jamais dans une page que vos visiteurs chargent. Quiconque ouvre le code source de la page ou le journal réseau peut copier une clé envoyée au navigateur, et dès lors il peut agir en votre nom sur votre compte. Stockez-la dans une variable d'environnement, tenez-la hors du contrôle de version, et laissez votre navigateur ne communiquer qu'avec des routes de votre propre backend. Ces routes doivent vérifier que le visiteur est autorisé à téléverser avant d'appeler l'API vidéo.

Une vidéo ajoutée via l'API appartient au compte qui détient la clé d'API. Si plusieurs projets partagent une même clé, toutes leurs vidéos atterrissent dans une seule bibliothèque et vous ne pouvez plus distinguer à qui appartient quel contenu. Dans la mesure du possible, utilisez une clé distincte pour chaque projet, afin de pouvoir en renouveler une sans casser les autres et de limiter la portée d'une fuite.

Téléverser une vidéo depuis votre propre code

Lorsque vous ajoutez une vidéo via l'API, vous lui donnez un titre, un nom de fichier, une taille de fichier et une visibilité, par exemple public.

Chaque requête de téléversement renvoie l'adresse à laquelle votre site envoie le fichier vidéo, ainsi qu'une adresse de statut qui indique à votre site quand la vidéo est prête à être affichée.

Le fichier lui-même est envoyé à l'adresse de téléversement renvoyée avec une requête PUT.

Décidez qui envoie les octets. Envoyer depuis votre serveur est le chemin le plus simple à journaliser et à relancer. Envoyer directement depuis le navigateur du visiteur évite à votre backend de relayer de gros fichiers, mais vous devez alors vous assurer que l'adresse de téléversement peut être exposée sans risque à ce visiteur, et gérer un onglet qui se ferme en cours de route. Choisissez une approche par projet, notez pourquoi vous l'avez choisie, et testez-la avec une connexion bridée.

L'espace de stockage du fichier est réservé pour votre compte au moment où le téléversement est demandé, avant que le premier octet du fichier ne circule.

Lisez la réponse à la requête de téléversement avant de commencer à envoyer des octets, et arrêtez-vous s'il s'agit d'une erreur. Pousser un gros fichier vers une adresse que vous n'avez jamais confirmée fait perdre du temps à votre visiteur et gaspille votre bande passante. Affichez un message clair lorsque la requête est refusée, et évitez de réessayer en boucle serrée, ce qui ne ferait que répéter le même refus.

Mesurez la taille du fichier de votre côté et envoyez ce nombre exact. Un écart entre la taille déclarée et le fichier réel est le genre de bogue qui n'apparaît qu'avec de gros téléversements ; essayez donc un petit fichier et un fichier de plusieurs gigaoctets avant de faire confiance au flux.

Attendez l'adresse de statut avant d'afficher une vidéo

Votre site ne doit pas afficher un lecteur dès la fin du PUT. L'adresse de statut issue de la requête de téléversement est le moyen pour votre site de savoir que la vidéo est prête à être affichée ; stockez-la donc à côté de l'enregistrement de la vidéo dans votre propre base de données.

Interrogez-la avec des intervalles croissants, par exemple toutes les quelques secondes au début, puis toutes les trente secondes, et arrêtez-vous après une limite raisonnable. Enregistrez le dernier état connu avec un horodatage afin qu'un redémarrage du serveur ne vous fasse pas perdre la trace d'une vidéo. Lorsque la limite est dépassée, marquez la vidéo comme retardée dans votre interface plutôt que d'afficher un indicateur de chargement sans fin.

Chaque vidéo de la liste indique son statut, par exemple prête, avec l'adresse de sa page de lecteur.

Utilisez cette liste comme filet de sécurité. Une tâche nocturne qui compare votre base de données à la liste repère toute vidéo dont la vérification de statut a été manquée, par exemple parce que votre serveur était hors service pendant l'attente. Corrigez l'écart en mettant à jour votre propre enregistrement, et non en téléversant à nouveau le fichier.

Construisez une galerie à partir de votre bibliothèque

Votre site lit la liste de vos vidéos avec le statut de chacune et récupère le code de lecteur prêt à l'emploi pour n'importe laquelle, afin de construire sa propre galerie vidéo à partir de votre bibliothèque DCAST.

La liste de vos vidéos ne contient que les vidéos du compte qui détient la clé, jamais les vidéos d'un autre compte.

La liste est paginée et vous indique le nombre total de vos vidéos, de sorte que votre site peut parcourir une grande bibliothèque page par page.

Ne récupérez pas toute la bibliothèque à chaque affichage de page. Mettez la liste en cache sur votre serveur pour une courte durée, n'affichez aux visiteurs que les vidéos dont le statut est prêt, et utilisez le nombre total pour dessiner les liens de pagination. Videz le cache lorsque votre propre code ajoute une vidéo, afin que le nouvel élément apparaisse aussitôt.

Demander le code de lecteur d'une vidéo qui appartient à un autre compte reçoit pour réponse « introuvable ». Traitez cette réponse comme un cas ordinaire dans votre code. Lorsqu'elle apparaît pour un identifiant que vous avez vous-même stocké, vérifiez d'abord quelle clé votre environnement utilise, car une mauvaise clé est une cause plus probable qu'une panne.

Placez le lecteur sur votre page

Le code de lecteur se présente sous la forme d'une simple adresse, d'un extrait iframe et d'une version adaptative qui s'ajuste à la page.

Le code de lecteur est une iframe que vous placez sur votre propre page.

Choisissez selon la mise en page. Utilisez la version adaptative dans les pages d'articles et les grilles de cartes, où la largeur change selon l'écran. Utilisez la simple adresse lorsque vous voulez construire l'iframe vous-même, par exemple pour ajouter un attribut title qui aide les lecteurs d'écran. Vérifiez la page sur un vrai téléphone avant le lancement, car un cadre de taille fixe est la cause la plus courante d'une vidéo intégrée qui semble cassée sur mobile.

Vous pouvez placer le lecteur de vos vidéos et de vos diffusions sur votre propre site web avec un court code d'intégration.

Par défaut, le lecteur intégré fonctionne sur n'importe quel site web, de sorte qu'un partenaire ou un fan peut partager votre contenu sans vous demander d'abord.

Si vous voulez garder le contrôle, listez les domaines où votre lecteur peut apparaître, et tous les autres sites web sont refusés.

Définissez la liste selon votre objectif. Restreignez la liste lorsque vous vendez l'accès via votre propre site et voulez que le lecteur n'apparaisse que là. Laissez la liste vide lorsque votre objectif est la portée, car chaque copie du code d'intégration fonctionne alors pour quiconque la colle.

Démarrez des directs depuis votre code

Votre site crée une diffusion en direct via l'API et reçoit les adresses vers lesquelles publier, ainsi que le code de lecteur pour la page qui affiche la diffusion.

Une nouvelle diffusion est fournie avec une adresse RTMP, une adresse SRT et, lorsqu'elle est disponible, une adresse HTTPS pour WHIP.

Une diffusion en direct créée via l'API est enregistrée pour votre compte et possède sa propre adresse d'intégration pour le lecteur.

Choisissez l'adresse de publication qui correspond à votre encodeur. Le RTMP est accepté par presque tous les encodeurs logiciels et boîtiers matériels, le SRT gère mieux un réseau avec pertes lorsque votre encodeur le prend en charge, et le WHIP permet à un navigateur de publier sans logiciel supplémentaire. Si vous n'avez pas de raison forte de choisir autrement, commencez par le RTMP et passez aux autres une fois votre première diffusion fonctionnelle.

Avant un véritable événement, effectuez une répétition de dix minutes créée par le même chemin de code que celui que vous utiliserez le jour J. Vérifiez que le lecteur de votre page affiche l'image, que le son est présent, et que votre encodeur se reconnecte après que vous avez débranché le réseau quelques secondes. Enregistrez ensuite l'identifiant de la diffusion afin que votre équipe d'assistance puisse la retrouver plus tard.

Effectuez ces vérifications avant le lancement

Parcourez cette courte liste dans l'ordre. Premièrement, cherchez la clé d'API dans vos pages générées et dans le journal réseau de votre navigateur ; elle ne doit apparaître nulle part. Deuxièmement, téléversez un petit fichier, un gros fichier et un fichier non pris en charge, et confirmez que chacun aboutit à un état que votre interface sait expliquer. Troisièmement, ouvrez la galerie en tant que visiteur déconnecté et vérifiez que les vidéos non terminées sont masquées. Quatrièmement, demandez un lecteur pour un identifiant qui n'existe pas et confirmez que votre page se dégrade proprement au lieu d'afficher un cadre vide.

Une fois ces vérifications réussies, vos visiteurs voient un seul site, votre code maîtrise le flux de travail et la plateforme vidéo reste en arrière-plan. Commencez par un téléversement et une page de galerie, puis ajoutez les diffusions lorsque la première partie tourne sans accroc.