2021-01-05
Pour ceux qui suivent ce blog et qui ne le savent pas encore, j'ai lancé ma chaîne Twitch il y a trois mois maintenant (oui c'est la raison de la pénurie d'articles sur le blog... 😅️). Pour cette chaîne, j'ai décidé de développer moi-même les diverses notifications qui s'afficheront à l'écran lorsque quelqu'un suit la chaîne, s'abonne ou offre des bits (la monnaie virtuelle de Twitch). Dans cette série d'articles, on va donc découvrir les APIs de Twitch et voir comment les utiliser.
Pour ce qui est des notifications, on va les développer en utilisant des technologies web, à savoir JavaScript, HTML et CSS et le tout sans utiliser aucune bibliothèque ni aucun framework ! Pourquoi utiliser ces technologies-là précisément ? Premièrement parce qu'il s'agit de technologies très répandues et relativement accessibles à tous... et aussi par ce qu'il est très facile d'intégrer une page web dans OBS, le logiciel de streaming le plus couramment utilisé ; c'est donc la solution la plus simple pour arriver au résultat désiré.
Pour ce premier article, je vais commencer par vous présenter les différentes APIs, puis on va parler de la création d'une application Twitch et de l'intégration d'une page web dans OBS.
--------------------------------------------------------------------------------
📝️ Note:
--------------------------------------------------------------------------------
NOTE : Ici on va mettre les mains dans le cambouis et parler de programmation. Si vous êtes à la recherche d'une solution clef en main, regardez du côté de Streamlabs, c'est ce que la plupart des streamers utilisent. 😉️
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
📝️ Note:
--------------------------------------------------------------------------------
Cet article fait partie d'une série consacrée à la découverte des APIs Twitch :
Création d'applications et intégration à OBS
Afficher des alertes pour les nouveaux followers !
--------------------------------------------------------------------------------
Pour suivre cette série d'articles dans de bonnes conditions, un minimum de connaissances sur les sujets suivants sont requises :
Le langage HTML et les feuilles de style CSS
La programmation en JavaScript
Bon ceci dit, ne prenez pas peur en voyant la liste ci-dessus : on va y aller doucement, et puis c'est plus facile qu'il n'y paraît. De plus, je vous mettrai tous les liens utiles pour approfondir les différents sujets. 😜️
Déjà, pour y voir plus clair, je vais vous présenter les principales APIs proposées par Twitch (en tout cas celles qui vont nous intéresser) ; car oui, il y en a plusieurs, et elles ne s'appuient pas toutes sur les mêmes technologies !
La première API dont on va parler, c'est celle nommée sobrement « Twitch API » dans la documentation officielle. Elle permet de récupérer la plupart des informations utiles, du dernier follower à l'ID de notre utilisateur et permet également de modifier des choses sur notre compte, comme par exemple changer le titre du stream en cours ou bloquer un utilisateur.
Il s'agit d'une API REST ; dit simplement, cela signifie qu'on va l'appeler en faisant des requêtes HTTP (comme si l'on appelait les pages d'un site Web), et elle nous fournira des réponses au format JSON.
Documentation de l'API REST de Twitch
Liste des fonctionnalités accessibles via cet API
--------------------------------------------------------------------------------
📝️ Note:
--------------------------------------------------------------------------------
NOTE : Il existe également une API nommée « Legacy Twitch API v5 ». Il s'agit de l'ancienne API REST qui ne doit plus être utilisée. D'ailleurs la plupart des appels à cette API se solderont par un code d'erreur « 410 Gone », qui signifie que la ressource n'est plus disponible.
--------------------------------------------------------------------------------
Seconde API intéressante pour nos notifications : l'API PubSub.
Si vous le voulez bien, commençons déjà par expliquer ce que signifie « PubSub ». PubSub est l'écriture contractée de Publish-Subscribe (soit « publier-s’abonner » en français) ; il ne s'agit ni plus ni moins que d'un système de messagerie asynchrone entre deux applications (on peut se représenter ça comme des emails). En résumé, Twitch va envoyer des messages à notre application, et notre application va les dépiler un par un pour en lire le contenu et agir en conséquence.
Contrairement à l'API REST, cette API ne repose pas sur le protocole HTTP, mais sur les WebSockets. Les WebSockets permettent de conserver connexion ouverte entre les serveurs de Twitch et notre application, ce qui autorise une réactivité en temps réel de notre application aux différents événements qui surviendront.
L'API PubSub fournit un certain nombre de choses intéressantes pour les notifications que l'on souhaite afficher lors de nos lives. Elle peut notamment nous envoyer des messages lorsque quelqu'un s'abonne¹ à la chaîne, donne des bits ou utilise des points de chaînes.
Documentation de l'API PubSub de Twitch
Liste des sujets (topics) auxquels on peut s'abonner
--------------------------------------------------------------------------------
📝️ Note:
--------------------------------------------------------------------------------
¹ NOTE : sur Twitch il ne faut pas confondre « suivre une chaîne » et « s'abonner à une chaîne ». Suivre une chaîne (follow) est gratuit alors que s'abonner (subscribe ou sub dans le jargon des streamers touiche) est payant.
--------------------------------------------------------------------------------
Les API mentionnées ci-dessus ne sont pas ouvertes aux 4 vents. Pour y accéder, il faut déclarer notre application auprès de Twitch, et autoriser cette application à agir en notre nom (ce qui se fait via une phase d'authentification). Il y a donc une API dédiée à l'authentification.
Documentation de l'authentification Twitch
Il y a deux autres APIs qui me semblent intéressantes et dont on reparlera surement plus tard :
Comme je l'ai dit en introduction, il est facile d'intégrer une page Web à OBS. Pour commencer en douceur avant de mettre les mains dans les APIs Twitch, on va créer une petite application qui affichera à intervalle régulier une notification contenant le lien vers ce blog, puis on l'intègrera à une scène OBS afin de pouvoir l'utiliser durant nos lives.
On va donc commencer simplement par créer un fichier « index.html » avec le contenu suivant :
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>Test application</title>
<link type="text/css" rel="stylesheet" href="./style.css" />
</head>
<body>
<!-- Notification qui affichera l'URL du blog sur le stream -->
<div class="notification" id="notification-blog">
🔗️ blog.flozz.fr
</div>
<script src="./script.js"></script>
</body>
</html>
Il n'y a pas grand-chose à dire, on a une simple <div> qui contient le texte à afficher... Passons donc à la suite.
Maintenant qu'on a le HTML, on va rajouter une feuille de style nommée « style.css » dans laquelle on va mettre ceci :
body, html {
/* On définit un fond transparent sur la page pour ne pas avoir un carré
* blanc à l'écran dans OBS */
background: transparent;
}
/**
* Apparence de la notification.
*/
.notification {
/* On positionne la notification en bas à gauche de l'écran */
position: fixed;
bottom: 30px;
left: 30px;
/* On définit une transition pour son passage de l'état initial (masqué) à
* son état visible */
transition: all 0.5s;
/* Partie purement esthétique */
padding: 15px 20px;
font-family: sans-serif;
font-size: 20pt;
font-weight: bold;
color: #333;
background: #fff;
border-bottom: #ff7700 solid 5px;
box-shadow: 0 0 10px rgba(0, 0, 0, 0.5);
}
/**
* État initial de la notification :
* on la décale vers le bas et on la rend transparente
*/
.notification {
transform: translate(0, 100px);
opacity: 0;
}
/**
* État "visible" de la notification:
* on la remet à sa place initiale et on enlève la transparence
*/
.notification.visible {
transform: translate(0, 0);
opacity: 1;
}
Cette feuille de style va permettre d'afficher la <div> contenant le lien du blog en bas à gauche de l'écran. De base cette <div> n'est pas visible, mais on peut l'afficher en lui rajoutant la classe « .visible ».
Si vous ouvrez la page à ce stade vous ne verrez rien du tout, car il nous manque encore un dernier élément : le JavaScript qui anime tout ça !
Voici donc le contenu du fichier « script.js » qui va donner vie à notre application :
// Intervalle entre 2 notifications (secondes)
const NOTIFICATION_INTERVAL = 5
// Durée d'affichage de la notification (secondes)
const NOTIFICATION_DURATION = 10
// On récupère la <div> qui contient l'URL du blog
const divNotificationBlog = document.getElementById("notification-blog");
// Fonction qui affiche la notification
function showNotification() {
// On ajoute la classe "visible" à la <div>
divNotificationBlog.classList.add("visible");
// On définit un timer pour appeler la fonction qui masquera la notification
setTimeout(hideNotification, NOTIFICATION_DURATION * 1000);
}
// Fonction qui masque la notification
function hideNotification() {
// On supprime la classe "visible" à la <div> ce qui la remettra à son état
// initial
divNotificationBlog.classList.remove("visible");
// On définit un timer pour appeler la fonction qui affichera à nouveau la
// notification
setTimeout(showNotification, NOTIFICATION_INTERVAL * 1000);
}
// On fait un premier appel à showNotification() pour lancer la machine :p
showNotification();
Vous pouvez à présent tester le tout en ouvrant la page HTML dans un navigateur et admirer le résultat. Comme je suis sympa, vous pouvez aussi avoir un aperçu en cliquant sur le bouton ci-dessous :
----
Cette démo n'est disponible que sur la version Web du blog, désolé. :(
----
À présent qu'on a notre page Web, il nous reste à l'intégrer à OBS. Pour ce faire, il vous suffit d'ajouter une source « Browser » (ou équivalent) à l'une de vos scènes.
Capture d'écran : ajouter une source « Browser » dans OBS
--------------------------------------------------------------------------------
📝️ Note:
--------------------------------------------------------------------------------
NOTE : Si vous êtes sous Linux et que vous n'avez aucune source « Browser » de disponible, il vous faudra alors installer le plugin OBS Linux Browser, qui vous fournira ce qu'il faut.
--------------------------------------------------------------------------------
Une fois la source ajoutée, renseignez le chemin vers votre fichier et adaptez si besoin les dimensions du navigateur en fonction du contenu de votre page :
Capture d'écran : Configuration de la soruce OBS Linux Browser
Il ne vous reste plus qu'à positionner la source où vous voulez sur la scène, en bas à gauche dans mon cas :
Capture d'écran : source « Browser » dans OBS
Et c'est tout ! La page que nous avons créée affichera à intervalle régulier l'adresse du blog pendant les lives (il faudra toutefois adapter les délais que j'ai volontairement définis assez courts pour les besoins de la démo) ! 😎️
Maintenant qu'on sait comment intégrer notre application à OBS, on va voir comment la déclarer auprès de Twitch, puisqu'on ne pourra pas accéder aux APIs si on ne déclare pas notre application au préalable.
Pour déclarer l'application,
Capture d'écran : Authentification sur dev.twitch.tv
Une fois authentifiés,
Capture d'écran : Création d'une application Twitch, étape 1
Capture d'écran : Création d'une application Twitch, étape 2
Il ne vous reste plus qu'à remplir le formulaire :
Capture d'écran : Création d'une application Twitch, étape 3
Une fois l'application dûment enregistrée auprès de Twitch, il nous faut récupérer son « Client ID ». Il s'agit de l'identifiant unique qui sert à l'identification de l'application par les APIs de Twitch.
Pour récupérer cet identifiant,
Capture d'écran : Récupérer le Client ID, étape 1
Capture d'écran : Récupérer le Client ID, étape 2
Notez que cet identifiant n'a pas particulièrement besoin de rester secret.
Dans ce premier article on a donc vu quelles étaient les différentes APIs Twitch qui pouvaient nous être utiles, on a vu comment intégrer une application Web à OBS et comment déclarer son application auprès de Twitch. La prochaine fois, je vous expliquerai comment développer la phase d'authentification de notre application, et après on pourra enfin commencer à jouer avec les APIs ! 😁️
L'exemple d'application que je vous ai montré dans cet article est bien sûr disponible sur Github si vous souhaitez le télécharger :
Pour ceux que ça intéresse, j'ai entamé une série de lives sur les APIs Twitch. Vous pourrez retrouver les vidéos des précédents lives sur ma chaîne YouTube et les futurs lives seront diffusés sur ma chaîne Twitch (n'hésitez pas à suivre la chaîne / à vous abonner !). Si vous avez des questions, n'hésitez pas à les poser en commentaire sous cet article ou à venir discuter sur Discord.
À bientôt pour la suite de cette série sur les APIs Twitch ! 😉️
--------------------------------------------------------------------------------
