Création d’une application MS Teams à l’aide de React & FluentUI – Matt Astachnowicz

Le courrier électronique est enfin en train de mourir – hourra! Aujourd’hui, dans la plupart des organisations, les applications de messagerie instantanée telles que MS Teams remplacent rapidement les e-mails traditionnels, apportant avec elles des communications plus rapides et plus faciles. Cependant, l’un des plus grands avantages de ces applications est l’espace d’intégration d’autres applications. dans notre outil de communication.

Il est vraiment logique de profiter de ces opportunités – les communications sont au cœur de tout ce que nous faisons au travail. Donc, quand j’ai été inspiré pour intégrer l’une de nos applications internes dans notre canal Teams, j’ai eu du mal à croire à quel point il était difficile de trouver un exemple complet de la façon de réellement faire il. Après avoir suivi plusieurs exemples à moitié cuits de Microsoft et lu les documents de l’API, je suis ravi d’avoir créé une application Teams fonctionnelle complète, en utilisant React, Fluent UI (pour une UI Teams cohérente) et l’authentification Azure AD.

Remarque: Ce didacticiel explique comment implémenter un outil personnalisé Languette dans un canal Teams, si vous recherchez des intégrations de bots, j’écris actuellement un article séparé sur la mise en œuvre de celui-ci auquel je fournirai un lien une fois terminé.

Tout d’abord, nous devons comprendre (comme je ne l’ai pas fait à l’origine) que MS Teams n’héberge pas une application en tant que telle, vous lui donnez simplement les informations dont il a besoin pour trouver votre application ailleurs et l’afficher dans une iframe.

Ces informations sont conservées dans un fichier appelé manifest.json et comprend des éléments tels que le nom, l’icône, la description de votre application et, surtout, l’URL de configurer votre application à partir du moment où elle est ajoutée à une chaîne.

C’est vrai – vous ne donnez pas réellement à Teams l’URL du site que vous souhaitez afficher, mais une page de configuration qui donnera ensuite à Teams l’URL réelle de votre contenu. Cela nous donne un peu plus de flexibilité, de sorte que, en fonction d’un certain nombre de facteurs (par exemple, le locataire, le canal auquel l’application est ajoutée, les paramètres de la page de configuration, etc.), vous pouvez changer l’emplacement d’où l’application réelle est extraite. .

Pour cet exemple, nous utiliserons la configuration React / Typescript prête à l’emploi, alors exécutez cette commande pour créer rapidement notre application (j’utilise ici du fil, mais bien sûr cela fonctionne aussi avec npm):

yarn create react-app  --template typescript

Aux fins de ce didacticiel, je suppose que vous n’avez pas de serveur Web de rechange avec un domaine https certifié prêt à l’emploi (une exigence pour que les équipes affichent votre application. Attention également – Les équipes n’autorisent pas ngrok / autres URL de service de tunneling), nous allons donc déployer notre site Web sur un serveur Web statique Azure comme une option super facile et rentable. Bien que si vous faire avoir un serveur Web de rechange avec https, n’hésitez pas à l’utiliser et passez à la section suivante.

Il existe de nombreux didacticiels sur la façon de créer un site Web statique gratuit / très bon marché sur Azure (par exemple, ici et ici), donc je ne montrerai pas les étapes à suivre.

Cependant, il existe une différence importante: Étant donné que nous utiliserons le routage côté client, nous devons modifier nos paramètres d’hébergement statiques pour rediriger les erreurs 404 vers l’application principale, qui ira ensuite rendre la page demandée dans le navigateur.

De là, nous pouvons facilement construire le projet en utilisant

yarn build

Si vous utilisez VS Code, l’ajout du plug-in de stockage Azure vous permet de déployer sur votre site Web en cliquant simplement avec le bouton droit sur le répertoire de génération et en sélectionnant Déployer sur un site Web statique. Si vous n’utilisez pas VS Code / utilisez votre propre serveur Web, je vous laisse le soin de découvrir comment déployer le site.

Une fois que vous avez déployé le site Web, visitez l’URL pour vous assurer que vous pouvez voir le site Web React par défaut avant de continuer.

Avant de continuer, installons toutes les dépendances dont nous avons besoin pour le reste du projet:

• Réagissez le routeur: Gère le routage entre les pages
• Équipes-js: Nous donne accès aux fonctions / API intégrées des équipes
• FluentUI: Crée des éléments d’interface utilisateur sur le thème de MS Teams
• ADAL angulaire: Authentification Azure AD

yarn add @types/react-router-dom @microsoft/teams-js @fluentui/react-northstar adal-angular

Nous avons tous nos plans de projet préférés, alors prenez un moment ici pour mettre en œuvre le vôtre. La façon dont j’aime présenter mes projets React est illustrée ci-dessous, mais n’hésitez pas à y aller comme vous le faites normalement:

Nous allons maintenant créer deux pages: l’une pour configurer notre application avant d’être ajoutée à une chaîne et l’autre avec du contenu réel à afficher dans l’onglet.

Tu peux vérifier le repo complet si vous avez besoin de voir comment ces pages sont liées à différents itinéraires (le code est à /src/config/routes.tsx).

Il y a une autre modification importante à apporter à notre composant de niveau supérieur, qui consiste à importer la bibliothèque teams-js et à l’initialiser. Une fois cela fait, nous pouvons accéder aux fonctions de la bibliothèque teams-js n’importe où dans notre application!

Exécutez l’application localement et testez que vous pouvez accéder aux itinéraires ‘/’ (affiche le titre ‘Our new Teams Tab’) et ‘/ configure’ (affiche le titre ‘Configure’) avant de continuer.

Hé – nous avons maintenant une application Teams fonctionnelle! Bien sûr, c’est primitif, mais c’est une véritable application qui fonctionne et nous devrions tester que nous pouvons maintenant l’ajouter à un canal Teams.

Il existe deux façons de le faire, soit créer le fichier manifest.json nous-mêmes, soit utiliser l’interface graphique dans les équipes MS Plugin App Studio pour le faire pour nous, je vais choisir cette dernière option.

Une fois que vous avez installé App Studio, sélectionnez-le dans le volet gauche, puis accédez au Éditeur de manifeste languette. Lorsque vous cliquez sur Créer une nouvelle application, un écran semblable à celui ci-dessous s’affichera, où il vous sera demandé de modifier certains détails de base sur votre application.

Une fois que vous avez terminé cette section, accédez au Onglets dans la partie gauche de l’écran et cliquez sur Ajouter sous le Onglet Équipe section. Si vous souhaitez que cette application apparaisse dans le volet gauche (par exemple, où App Studio est affiché), vous pouvez également créer un onglet personnel.

Choisir de créer un onglet d’équipe fera apparaître un écran comme celui ci-dessous, qui vous invite à quelques options, la principale étant l’URL à partir de laquelle nous pouvons configurer notre application. Si vous suivez l’exemple de code que j’ai écrit, celui-ci est hébergé sur le site configurer page.

Maintenant que notre application est configurée, accédez au Testez et distribuez section du formulaire. Cela nous donne trois options:

1. Installez l’application directement dans une équipe.
2. Téléchargez une copie du manifeste de notre application.
3. Soumettez cette application à la boutique d’applications Teams pour approbation, afin qu’elle puisse être ajoutée au marché public.

Dans ce cas, je choisis l’option 1 et je l’installe directement dans une équipe, mais si vous prévoyez que cette application sera accessible au public, optez pour l’option 3!

Toutes nos félicitations!

Vous avez maintenant une application React qui fonctionne sur votre chaîne MS Teams!

Si c’est tout ce dont vous avez besoin, vous avez terminé. N’hésitez pas à continuer à lire pour savoir comment ajouter des composants d’interface utilisateur sur le thème des équipes et l’authentification…

Nous avons maintenant une application MS Teams fonctionnelle, faisons-la Regardez comme l’un avec l’aide de FluentUI.

Comme vous pouvez le voir dans l’essentiel ci-dessous, le principal changement dans notre composant App est que tout est maintenant enveloppé dans un Fournisseur , qui implémente le thème actuel (stocké dans l’état de l’application) sur tous ses enfants. le ThemeHelper class est simplement là pour vous aider à convertir une chaîne de thème en un objet ThemePrepared.

Notez également la ligne suivante:

msTeams.registerOnThemeChangeHandler(this.updateTheme.bind(this));

Cela lie la méthode updateTheme () de l’application à un hook Teams intégré qui est appelé chaque fois que le thème est modifié. Cela signifie que nous n’avons pas besoin de recharger la page après qu’un utilisateur a changé de thème pour que les modifications prennent effet.

À partir de là, j’ai implémenté un ensemble d’onglets verticaux sur notre page d’accueil pour illustrer simplement les composants thématiques des équipes, vous pouvez voir les résultats ci-dessous dans les thèmes clairs et sombres.

Agréable! Nous avons maintenant de vrais composants MS à thème dynamique dans notre application!

PS. Il y a une faille mineure dans cette implémentation. Vous remarquerez que nous avons initialement défini le thème sur « par défaut », car malheureusement la fonction getContext () qui nous donne le thème actuel est asynchrone. Il existe de nombreuses façons de contourner ce problème, par exemple vous pouvez créer une méthode de rendu bloquant, afficher une page de chargement, etc. mais pour mon cas d’utilisation, un délai d’une demi-seconde pour obtenir le thème n’est pas un gros problème donc je ne vais pas l’implémenter.

Tout d’abord, nous devons comprendre comment l’authentification est gérée dans MS Teams. Comme je l’ai mentionné, votre application s’affiche dans un cadre iFrame. Malheureusement, la transmission d’informations d’identification via un iframe est un risque pour la sécurité, de sorte que la plupart des fournisseurs d’authentification ne le permettront pas. Pour contourner ce problème, Teams suit le flux d’authentification indiqué ci-dessous:

1. L’utilisateur commence le flux de connexion (par exemple en cliquant sur un bouton de connexion).
2. Les équipes ouvrent un fenêtre contextuelle hébergée sur votre site Web, dont le seul but est de rediriger l’utilisateur vers la page de connexion MS de votre organisation.
3. L’utilisateur se connecte à son compte MS dans la fenêtre contextuelle.
4. AAD traite la demande de connexion, puis envoie le jeton d’authentification généré à une «page de redirection» désignée. Cette page exécutera un script pour extraire le jeton de la demande et l’enregistrer à un endroit où l’application peut y accéder (par exemple dans localStorage).
5. Enfin, la fenêtre contextuelle se ferme et le jeton est disponible pour l’application.

Pour faciliter ce flux, j’ai rassemblé les 3 pages dont nous avons besoin (connexion, la page de démarrage popup et la page de fin popup) ainsi que le classe d’aide à la connexion – ensemble, ceux-ci nous permettent de mettre en œuvre les 5 étapes ci-dessus.

Remarque: Vous pouvez apporter deux modifications supplémentaires au processus de connexion qui peuvent offrir différentes fonctionnalités utiles, selon votre application:

• Authentification silencieuse: Exécute le flux ci-dessus dans une fenêtre contextuelle cachée au cas où aucune entrée d’utilisateur n’est requise (par exemple, parce que vous vous êtes connecté récemment ailleurs). Si cela échoue, nous exécutons simplement le processus habituel à la place. (Documentation MS)
• SSO (actuellement en mode aperçu développeur uniquement): Cela implémentera théoriquement le rêve de l’authentification Teams-app – c’est-à-dire utiliser l’authentification Teams de l’utilisateur comme authentification pour votre application, vous n’avez donc pas besoin de vous connecter explicitement. (Documentation MS – notez que ce n’est pas encore prêt pour la production au moment de la rédaction).

Maintenant que le code fait sa part, ajoutons un enregistrement d’application dans notre locataire AAD pour que cela fonctionne réellement! Ce n’est pas difficile, donc je suppose que vous pouvez travailler cette partie par vous-même (ou suivre cette guider).

Une fois l’enregistrement terminé, accédez simplement au panneau d’authentification et cliquez sur Ajouter une plateforme, puis sélectionnez la toile. Dans le champ URI de redirection, ajoutez le domaine de votre application avec «/ auth / signinend» ajouté à la fin de celui-ci. Enfin, assurez-vous Jetons d’accès et Jetons d’identification les cases à cocher sont sélectionnées. Votre configuration devrait ressembler à quelque chose comme ci-dessous:

Maintenant que nous pouvons nous connecter et nous authentifier dans notre application Équipes, nous devons simplement implémenter notre logique pour exclure les utilisateurs de l’affichage de pages particulières s’ils ne sont pas connectés.

Il existe de nombreuses façons d’y parvenir, telles que les mises en page, les middlewares, les vérifications sur chaque page, etc. Mais étant donné que nous utilisons le routage côté client, nous pouvons suivre une approche très simple et élégante: Ne restituez pas les itinéraires des pages qui doivent être authentifiées.

Dans React, tout cela se résume à une seule ligne de code:

render() {
return (

      { this.state.loggedIn ? 
:  }

);
}

Vérifier ici pour l’implémentation de la classe RouterHelper.

C’est ça! Dans cet article, nous avons développé un site Web (construit à l’aide de React) qui peut être ajouté à MS Teams dans un onglet personnalisé. Notre application nous permet également de profiter de deux fonctions intégrées importantes: Theming et Authentication.

Merci d’avoir lu et j’espère que cela pourra vous aider dans votre prochain projet!