Concevoir une carte ou une boîte de dialogue interactive

Cette page explique comment ajouter des widgets et des éléments d'interface utilisateur aux messages de fiche ou de boîte de dialogue afin que les utilisateurs puissent interagir avec votre application Google Chat, par exemple en cliquant sur un bouton ou en envoyant des informations.

Créez et prévisualisez des fiches avec Card Builder.

Ouvrez l'outil de création de cartes

Prérequis

  • Un compte Google Workspace ayant accès à Google Chat
  • Une application Chat publiée. Pour créer une application Chat, suivez ce quickstart.

    • Ajouter un bouton

    Le widget ButtonList affiche un ensemble de boutons. Les boutons peuvent afficher du texte, une icône, ou les deux. Chaque Button prend en charge une action OnClick qui se produit lorsque l'utilisateur clique sur le bouton. Exemple :

    • Ouvrez un lien hypertexte avec OpenLink afin de fournir des informations supplémentaires aux utilisateurs.
    • Exécutez un action qui exécute une fonction personnalisée, comme appeler une API.

    Pour des raisons d'accessibilité, les boutons prennent en charge le texte alternatif.

    Ajouter un bouton qui exécute une fonction personnalisée

    Voici une fiche composée d'un widget ButtonList avec deux boutons. Un bouton permet d'ouvrir la documentation pour les développeurs Google Chat dans un nouvel onglet. L'autre bouton exécute une fonction personnalisée appelée goToView() et transmet le paramètre viewType="BIRD EYE VIEW".

    Ajouter un bouton avec une couleur personnalisée et un bouton désactivé

    Vous pouvez empêcher les utilisateurs de cliquer sur un bouton en définissant "disabled": "true".

    L'exemple suivant affiche une fiche composée d'un widget ButtonList avec deux boutons. Un bouton utilise le champ Color pour personnaliser la couleur d'arrière-plan du bouton. L'autre bouton est désactivé avec le champ Disabled, ce qui empêche l'utilisateur de cliquer sur le bouton et d'exécuter la fonction.

    Ajouter un bouton avec une icône

    L'exemple suivant affiche une fiche composée d'un widget ButtonList avec deux widgets d'icône Button. Un bouton utilise le champ knownIcon pour afficher l'icône d'e-mail intégrée de Google Chat. L'autre bouton utilise le champ iconUrl pour afficher un widget d'icône personnalisée.

    Ajouter un bouton avec une icône et du texte

    L'exemple suivant affiche une fiche composée d'un widget ButtonList qui invite l'utilisateur à envoyer un e-mail. Le premier bouton affiche une icône d'e-mail et le deuxième affiche du texte. L'utilisateur peut cliquer sur l'icône ou sur le bouton de texte pour exécuter la fonction sendEmail.

    Ajouter des éléments d'interface utilisateur sélectionnables

    Le widget SelectionInput fournit un ensemble d'éléments sélectionnables, tels que des cases à cocher, des cases d'option, des boutons bascules ou un menu déroulant. Vous pouvez utiliser ce widget pour collecter des données définies et standardisées auprès des utilisateurs. Pour collecter des données non définies auprès des utilisateurs, utilisez plutôt le widget TextInput.

    Le widget SelectionInput accepte les suggestions, qui aident les utilisateurs à saisir des données uniformes, et les actions en cas de modification (Actions) qui s'exécutent lorsqu'une modification se produit dans un champ de saisie de sélection (par exemple, lorsqu'un utilisateur sélectionne ou désélectionne un élément).

    Les applications de chat peuvent recevoir et traiter la valeur des éléments sélectionnés. Pour en savoir plus sur l'utilisation des entrées de formulaire, consultez Recevoir des données de formulaire.

    Cette section fournit des exemples de fiches qui utilisent le widget SelectionInput. Les exemples utilisent différents types d'entrées de section:

    Ajouter une case à cocher

    Voici une boîte de dialogue qui demande à l'utilisateur de spécifier si un contact est professionnel, personnel ou les deux, avec un widget SelectionInput utilisant des cases à cocher:

    Ajouter une case d'option

    Voici une boîte de dialogue qui demande à l'utilisateur de spécifier si un contact est professionnel ou personnel avec un widget SelectionInput utilisant des cases d'option:

    Ajouter un bouton bascule

    La boîte de dialogue suivante demande à l'utilisateur de spécifier si un contact est professionnel, personnel ou les deux à l'aide d'un widget SelectionInput utilisant des contacteurs:

    Voici une boîte de dialogue qui demande à l'utilisateur de spécifier si un contact est professionnel ou personnel avec un widget SelectionInput utilisant un menu déroulant:

    Ajouter un menu multi-sélection

    La boîte de dialogue suivante affiche une demande à l'utilisateur de sélectionner des contacts dans un menu multi-sélection:

    Utiliser des sources de données pour les menus à sélection multiple

    La section suivante explique comment utiliser les menus multi-sélection pour insérer des données à partir de sources dynamiques, telles qu'une application Google Workspace ou une source de données externe.

    Sources de données de Google Workspace

    Vous pouvez remplir les éléments d'un menu multi-sélection à partir des sources de données suivantes dans Google Workspace:

    • Utilisateurs de Google Workspace: vous ne pouvez ajouter des utilisateurs qu'au sein de la même organisation Google Workspace.
    • Espaces Chat: l'utilisateur qui saisit des éléments dans le menu multi-sélection ne peut afficher et sélectionner que les espaces auxquels il appartient dans son organisation Google Workspace.

    Pour utiliser des sources de données Google Workspace, vous devez spécifier le champ platformDataSource. Contrairement aux autres types d'entrées de sélection, vous omettez les objets SectionItem, car ils proviennent de Google Workspace de manière dynamique.

    Le code suivant montre un menu multi-sélection d'utilisateurs Google Workspace. Pour renseigner les utilisateurs, l'entrée de sélection définit commonDataSource sur USER:

    JSON

    {
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

    Le code suivant montre un menu multi-sélection des espaces Chat. Pour renseigner les espaces, l'entrée de sélection spécifie le champ hostAppDataSource. Le menu multi-sélection définit également defaultToCurrentSpace sur true, ce qui fait de l'espace actuel la sélection par défaut dans le menu:

    JSON

    {
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}
    Sources de données en dehors de Google Workspace

    Les menus multi-sélection permettent également de renseigner des éléments à partir d'une source de données tierce ou externe. Par exemple, vous pouvez utiliser des menus à sélection multiple pour aider un utilisateur à faire son choix dans une liste de prospects commerciaux dans un système de gestion de la relation client (CRM).

    Pour utiliser une source de données externe, utilisez le champ externalDataSource pour spécifier une fonction qui renvoie des éléments à partir de la source de données.

    Pour réduire le nombre de requêtes adressées à une source de données externe, vous pouvez inclure des suggestions d'éléments qui s'affichent dans le menu multi-sélection avant que les utilisateurs ne saisissent du texte dans le menu. Par exemple, vous pouvez renseigner les contacts recherchés récemment pour l'utilisateur. Pour renseigner les éléments suggérés à partir d'une source de données externe, spécifiez des objets SelectionItem.

    Le code suivant affiche un menu de sélection multiple contenant les éléments d'un ensemble externe de contacts pour l'utilisateur. Le menu affiche un contact par défaut et exécute la fonction getContacts pour récupérer et insérer des éléments à partir de la source de données externe:

    JSON

    {
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 2,
    "externalDataSource": {
      "function": "getContacts"
    },
    "items": [
      {
        "text": "Contact 3",
        "value": "contact-3",
        "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
        "bottomText": "Contact three description",
        "selected": false
      }
    ]
  }
}

    Pour les sources de données externes, vous pouvez également utiliser la saisie semi-automatique pour les éléments que les utilisateurs commencent à saisir dans le menu multi-sélection. Par exemple, si un utilisateur commence à saisir Atl pour un menu qui renseigne les villes des États-Unis, votre application Chat peut suggérer automatiquement Atlanta avant que l'utilisateur ne termine sa saisie. La saisie semi-automatique peut contenir jusqu'à 100 éléments.

    Pour la saisie semi-automatique des éléments, vous devez créer une fonction qui interroge la source de données externe et renvoie des éléments chaque fois qu'un utilisateur saisit du texte dans le menu multi-sélection. La fonction doit effectuer les opérations suivantes:

    • Transmettez un objet d'événement qui représente l'interaction de l'utilisateur avec le menu.
    • Identifiez que la valeur invokedFunction de l'événement d'interaction correspond à la fonction du champ externalDataSource.
    • Lorsque les fonctions correspondent, renvoyez les éléments suggérés à partir de la source de données externe. Pour suggérer des éléments en fonction de ce que l'utilisateur saisit, obtenez la valeur de la clé autocomplete_widget_query. Cette valeur représente ce que l'utilisateur saisit dans le menu.

    Le code suivant effectue la saisie semi-automatique des éléments d'une ressource de données externe. Dans l'exemple précédent, l'application Chat suggère des éléments en fonction du moment où la fonction getContacts est déclenchée:

    Apps Script ;

    apps-script/selection-input/on-widget-update.gs
    /**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

    Node.js

    node/selection-input/on-widget-update.js
    /**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

    Ajouter un champ dans lequel l'utilisateur peut saisir du texte

    Le widget TextInput fournit un champ dans lequel les utilisateurs peuvent saisir du texte. Le widget accepte les suggestions, qui aident les utilisateurs à saisir des données uniformes, et des actions en cas de modification (Actions) qui s'exécutent lorsqu'une modification se produit dans le champ de saisie de texte (par exemple, si un utilisateur ajoute ou supprime du texte).

    Lorsque vous devez collecter des données abstraites ou inconnues auprès des utilisateurs, utilisez ce widget TextInput. Pour collecter des données définies auprès des utilisateurs, utilisez plutôt le widget SelectionInput.

    Pour traiter le texte saisi par les utilisateurs, consultez la section Recevoir des données de formulaire.

    Voici une fiche composée d'un widget TextInput:

    Permettre à un utilisateur de choisir une date et une heure

    Le widget DateTimePicker permet aux utilisateurs de saisir une date, une heure ou les deux. Les utilisateurs peuvent également utiliser le sélecteur pour sélectionner des dates et des heures. Si les utilisateurs saisissent une date ou une heure non valide, le sélecteur affiche une erreur les invitant à saisir correctement les informations.

    Pour traiter les valeurs de date et d'heure saisies par les utilisateurs, consultez la section Recevoir des données de formulaire.

    Voici une fiche composée de trois types de widgets DateTimePicker différents:

    Dépannage

    Lorsqu'une application ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche un message indiquant "Un problème est survenu" ou "Impossible de traiter votre demande". Il peut arriver que l'interface Chat n'affiche aucun message d'erreur, mais que l'application ou la fiche Chat génère un résultat inattendu. Par exemple, il est possible qu'un message de fiche ne s'affiche pas.

    Bien qu'aucun message d'erreur ne s'affiche dans l'interface Chat, des messages d'erreur descriptifs et des données de journal sont disponibles pour vous aider à corriger les erreurs lorsque la journalisation des erreurs est activée pour les applications Chat. Si vous avez besoin d'aide pour afficher, déboguer et corriger les erreurs, consultez Résoudre les erreurs Google Chat.