Associer une application de chat à d'autres services et outils

Bien que les applications soient performantes en elles-mêmes, elles fonctionnent souvent de concert avec d'autres systèmes et nécessitent des applications associées pour connecter des comptes, autoriser l'accès aux données, afficher des données supplémentaires ou configurer les préférences utilisateur.

Demander la configuration de l'application

En plus de présenter les URL dans le cadre d'une réponse normale, les applications peuvent présenter une URL de configuration en privé à l'utilisateur en réponse à un message.

Renvoyer une URL de configuration

Si l'exécution d'une requête nécessite une configuration supplémentaire impossible à effectuer directement dans l'application, renvoyez une réponse au format suivant:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "<your-config-URL>"
  }
}

Cela indique à Google Chat de présenter à l'utilisateur une invite privée, avec un lien permettant d'accéder à l'URL de configuration fournie pour l'authentification, l'autorisation ou la configuration. Une réponse request-config s'exclut mutuellement avec un message de réponse standard. Le texte, les fiches et les autres attributs sont ignorés.

Chaque événement vers votre application inclut également un paramètre configCompleteRedirectUrl. Cette URL devrait être encodée dans votre URL de configuration pour être utilisée à la fin du processus. La redirection vers cette URL indique à Google Chat que la requête de configuration a été traitée.

Au démarrage de l'application, le flux peut dépendre du message reçu. En réponse à un message tel que @app help, une application doit renvoyer un message sans nécessiter de configuration supplémentaire.

Lorsqu'un utilisateur est correctement redirigé vers le configCompleteRedirectUrl fourni dans le message d'origine, Google Chat effectue les étapes suivantes:

1. Effacer l'invite qui a été présentée à l'utilisateur initial
2. Convertir le message d'origine en public et le rendre visible pour les autres membres de l'espace
3. Distribuer une seconde fois le message d'origine dans la même application

Visiter un configCompleteRedirectUrl n'affecte qu'un seul message de l'utilisateur. Si un utilisateur a essayé d'envoyer plusieurs messages à une application et reçu plusieurs invites, le fait de cliquer sur une invite particulière et de terminer le processus d'authentification / de configuration n'affecte que ce message / invite. Les autres messages et invites ne sont pas modifiés.

Lorsqu'un événement est redirigé de cette manière, il doit normalement être identique à l'événement d'origine. Toutefois, dans certains cas, les événements peuvent différer. Par exemple, lorsqu'un message mentionne à la fois l'application A et l'application B, l'utilisateur peut modifier le texte du message si l'application A renvoie un message standard avant de s'authentifier auprès de l'application B. Dans ce cas, l'application B recevra le message modifié une fois que l'utilisateur aura terminé l'authentification.

Identifier l'utilisateur dans les messages de l'application

Chaque message envoyé à votre application inclut l'identité de l'utilisateur qui interagit avec elle.

L'exemple de fragment JSON ci-dessous montre le format attendu de l'identité de l'utilisateur dans un message adressé à votre application.

{
  ...,
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Sasha",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "sasha@example.com"
  }
}

Utilisez la valeur de la propriété users.name comme ID principal pour l'utilisateur. La valeur correspond à un identifiant unique et stable pour chaque utilisateur.

Identifier l'utilisateur Chat en dehors de Google Chat

Dans certains cas, par exemple pour demander une autorisation OAuth pour une API, votre application doit être associée à une URL externe à Google Chat tout en conservant l'identité de l'utilisateur. Le meilleur moyen d'identifier l'utilisateur dans ce cas est de protéger l'application de destination avec Google Sign-In.

Utilisez le jeton d'identité émis lors de la connexion pour obtenir l'ID utilisateur. La revendication sub contient l'ID unique de l'utilisateur et peut être corrélé à l'ID de Google Chat.

Bien que les deux ID ne soient pas exactement identiques, ils peuvent facilement être forcés. Pour forcer la valeur de la revendication sub pour un nom d'utilisateur Google Chat, ajoutez "users/" en tant que valeur. Par exemple, la valeur de revendication de 123 est équivalente au nom d'utilisateur users/123 dans les messages envoyés à votre application Chat.

Exemple complet

L'application MyProfile montre comment lancer la configuration de l'application à l'aide de la réponse REQUEST_CONFIG et utilise le jeton d'identité de la réponse Google Sign-In pour identifier l'utilisateur.