Collecter et traiter les informations des utilisateurs de Google Chat

Ce guide explique comment les applications Google Chat peuvent collecter et traiter des informations des utilisateurs en créant des entrées de formulaire dans des interfaces basées sur des cartes.

<ph type="x-smartling-placeholder">
</ph> Boîte de dialogue présentant différents widgets.
Figure 1 : exemple Application Chat qui ouvre une boîte de dialogue permettant de recueillir les coordonnées.

Les applications Chat demandent des informations aux utilisateurs pour effectuer des actions dans ou en dehors de Chat, y compris de la manière suivante :

  • Configurez les paramètres. Par exemple, pour permettre aux utilisateurs de personnaliser les paramètres de notification ou de configurer et d'ajouter l'application Chat à un ou plusieurs espaces.
  • Créer ou mettre à jour des informations dans d'autres applications Google Workspace Par exemple, autorisez les utilisateurs à créer un événement Google Agenda.
  • Autorisez les utilisateurs à accéder aux ressources d'autres applications ou services Web, et à les mettre à jour. Par exemple, une application Chat peut aider les utilisateurs à mettre à jour l'état d'une demande d'assistance directement depuis un espace Chat.

Prérequis

Une application Google Chat avec des fonctionnalités interactives. Pour créer un interactive, suivez l'un des guides de démarrage rapide suivants sur l'architecture de l'application que vous souhaitez utiliser:

Créer des formulaires à l'aide de fiches

Pour collecter des informations, les applications Chat conçoivent des formulaires et des données saisies, et les intégrer dans des cartes. Pour afficher des cartes aux utilisateurs, les applications Chat peuvent utiliser les interfaces Chat suivantes :

  • Messages contenant une ou plusieurs cartes
  • Pages d'accueil Il s'agit d'une fiche qui apparaît dans l'onglet Accueil messages avec l'application Chat.
  • Les boîtes de dialogue, qui sont des fiches qui s'ouvrent dans une nouvelle fenêtre à partir des messages et des pages d'accueil.

Les applications de chat peuvent créer les fiches à l'aide des widgets suivants:

  • Widgets de saisie de formulaire qui demandent des informations aux utilisateurs. Vous pouvez également ajouter une validation aux widgets de saisie de formulaires pour vous assurer que les utilisateurs saisissent et formatent correctement les informations. Les applications de chat peuvent utiliser les widgets de saisie de formulaire suivants:

    • Saisie de texte (textInput) pour le texte libre ou suggéré.
    • Données de sélection (selectionInput) sont des éléments d'interface utilisateur sélectionnables, comme des cases à cocher, des cases d'option et des menus déroulants. Les widgets de saisie de sélection peuvent également renseigner des éléments à partir de sources de données statiques ou dynamiques. Par exemple, les utilisateurs peuvent sélectionner un salon Chat parmi une liste de salons auxquels ils sont membres.
    • Sélecteurs de date et heure (dateTimePicker) pour les entrées de date et d'heure.

  • Un widget button afin que les utilisateurs puissent envoyer les valeurs qu'ils ont saisies dans la fiche. Une fois qu'un utilisateur a cliqué sur le bouton, l'application Chat peut traiter les informations qu'elle reçoit.

L'exemple suivant affiche une fiche composée de trois types d'entrées de date et d'heure différents :

Pour plus d'exemples de widgets interactifs que vous pouvez utiliser pour collecter pour en savoir plus, consultez Concevez une fiche ou une boîte de dialogue interactive.

Recevoir des données à partir de widgets interactifs

Chaque fois qu'un utilisateur clique sur un bouton, les applications Chat reçoivent un événement d'interaction CARD_CLICKED contenant des informations sur l'interaction. La charge utile des événements d'interaction CARD_CLICKED contient un objet common.formInputs avec toutes les valeurs saisies par l'utilisateur.

Vous pouvez récupérer les valeurs de l'objet common.formInputs.WIDGET_NAME, où WIDGET_NAME est le champ name que vous avez spécifié pour le widget. Les valeurs sont renvoyées en tant que type de données spécifique pour le widget (représenté par un objet Inputs). Dans l'exemple suivant, une fiche collecte des informations de contact à l'aide d'une zone de saisie de texte, d'un sélecteur de date et d'un widget de saisie de sélection :

{
  "textInput": {
    "name": "contactName",
    "label": "First and last name",
    "type": "SINGLE_LINE"
  }
}, {
  "dateTimePicker": {
    "name": "contactBirthdate",
    "label": "Birthdate",
    "type": "DATE_ONLY"
  }
}, {
  "selectionInput": {
    "name": "contactType",
    "label": "Contact type",
    "type": "RADIO_BUTTON",
    "items": [
      {
        "text": "Work",
        "value": "Work",
        "selected": false
      },
      {
        "text": "Personal",
        "value": "Personal",
        "selected": false
      }
    ]
  }
}

Gérer l'événement d'interaction

Lorsqu'un utilisateur saisit des données dans une fiche ou une boîte de dialogue, votre application Chat reçoit un événement d'interaction CARD_CLICKED de l'application Chat contenant les valeurs saisies par l'utilisateur.

Voici une partie d'un événement d'interaction CARD_CLICKED où Un utilisateur a saisi des valeurs pour chaque widget:

HTTP

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps Script 

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

Pour recevoir les données, votre application Chat gère les d'interaction pour obtenir les valeurs saisies par les utilisateurs dans les widgets. Le tableau suivant montre comment obtenir la valeur d'un widget de saisie de formulaire donné. Pour chaque widget, le tableau indique le type de données accepté par le widget, l'emplacement où la valeur est stockée dans l'événement d'interaction et un exemple de valeur.

Widget de saisie de formulaire Type de données d'entrée Valeur de saisie de l'événement d'interaction Exemple de valeur
textInput stringInputs events.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Pour obtenir la première ou la seule valeur, events.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker qui n'accepte que des dates. dateInput events.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

Transférer des données vers une autre carte

Après qu'un utilisateur a fourni des informations à partir d'une carte, il se peut que vous deviez renvoyer cartes supplémentaires pour effectuer les opérations suivantes:

  • Aidez les utilisateurs à remplir des formulaires plus longs en créant des sections distinctes.
  • Permettez aux utilisateurs de prévisualiser et de confirmer les informations de la fiche initiale afin qu'ils puissent vérifier leurs réponses avant de les envoyer.
  • Renseignez dynamiquement les autres parties du formulaire. Par exemple, pour inviter les utilisateurs à créer un rendez-vous, une application Chat peut afficher une fiche initiale qui demande le motif du rendez-vous, puis renseigner une autre fiche qui indique les heures disponibles en fonction du type de rendez-vous.

Pour transférer les données saisies à partir de la fiche initiale, vous pouvez créer le widget button avec actionParameters contenant le name du widget et la valeur saisie par l'utilisateur, comme illustré dans l'exemple suivant :

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

Où WIDGET_NAME correspond au name du widget et USER_INPUT_VALUE correspond à ce que l'utilisateur saisit. Par exemple, pour une saisie de texte qui collecte le nom d'une personne, le nom du widget est contactName et un exemple de valeur est Kai O.

Lorsqu'un utilisateur clique sur le bouton, votre application Chat reçoit un événement d'interaction CARD_CLICKED. Pour récupérer les valeurs, vous pouvez utiliser l'objet event.common.parameters.

L'exemple suivant montre comment transmettre des paramètres contenant des données saisies par l'utilisateur à une fonction qui ouvre la fiche suivante :

Node.js

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

Python

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

Apps Script 

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

Répondre à un envoi de formulaire

Après avoir reçu les données d'un message ou d'une boîte de dialogue de carte, l'application Chat répond en confirmant la réception ou en renvoyant une erreur.

Dans l'exemple suivant, une application Chat envoie un SMS pour confirmer qu'il a bien reçu un formulaire envoyé par message de fiche.

Apps Script 

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

Pour traiter et fermer une boîte de dialogue, vous renvoyez un objet ActionResponse qui spécifie si vous souhaitez envoyer un message de confirmation, mettre à jour le message ou la fiche d'origine, ou simplement fermer la boîte de dialogue. Pour connaître la procédure à suivre, consultez la section Fermer une boîte de dialogue.

Résoudre les problèmes

Lorsqu'une application ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche le message "Un problème est survenu". ou "Impossible de traiter votre demande." Il arrive que l'interface utilisateur de Chat n'affiche aucun message d'erreur, mais que l'application ou la fiche Chat produise un résultat inattendu. Par exemple, un message de fiche peut ne pas s'afficher.

Même s'il est possible qu'aucun message d'erreur ne s'affiche dans l'interface utilisateur de Chat, Des messages d'erreur descriptifs et des données de journaux sont disponibles pour vous aider à corriger les erreurs. Lorsque la journalisation des erreurs est activée pour les applications Chat. Pour savoir comment afficher, déboguer et corriger les erreurs, consultez Résoudre et corriger les erreurs Google Chat.