Créer une page d'accueil pour une application Google Chat

Cette page explique comment créer une page d'accueil pour les messages privés avec votre application Google Chat. Une page d'accueil, appelée accueil de l'application dans l'API Google Chat, est une interface de fiche personnalisable qui s'affiche dans l'onglet Accueil des espaces de messages privés entre un utilisateur et une application Chat.

Fiche d'accueil de l'application avec deux widgets.
Figure 1: Exemple de page d'accueil qui s'affiche dans les messages privés avec une application Chat

Vous pouvez utiliser l'accueil de l'application pour partager des conseils sur l'interaction avec l'application Chat ou pour permettre aux utilisateurs d'accéder à un service ou outil externe et de l'utiliser depuis Chat.

Utilisez Card Builder pour concevoir et prévisualiser la messagerie et les interfaces utilisateur des applications Chat:

Ouvrir Card Builder

Prérequis

Node.js

Une application Google Chat pour laquelle les fonctionnalités interactives sont activées. Pour créer une application Chat interactive à l'aide d'un service HTTP, suivez ce guide de démarrage rapide.

Python

Une application Google Chat pour laquelle les fonctionnalités interactives sont activées. Pour créer une application Chat interactive à l'aide d'un service HTTP, suivez ce guide de démarrage rapide.

Java

Une application Google Chat pour laquelle les fonctionnalités interactives sont activées. Pour créer une application Chat interactive à l'aide d'un service HTTP, suivez ce guide de démarrage rapide.

Apps Script

Une application Google Chat pour laquelle les fonctionnalités interactives sont activées. Pour créer une application Chat interactive dans Apps Script, suivez ce guide de démarrage rapide.

Configurer la page d'accueil de votre application Chat

Pour prendre en charge l'accueil de l'application, vous devez configurer votre application Chat pour qu'elle reçoive les événements d'interaction APP_HOME. Votre application Chat reçoit cet événement chaque fois qu'un utilisateur clique sur l'onglet Accueil à partir d'un message privé avec l'application Chat.

Pour mettre à jour vos paramètres de configuration dans la console Google Cloud, procédez comme suit:

  1. Dans la console Google Cloud, accédez à Menu > Autres produits > Google Workspace > Bibliothèque de produits > API Google Chat.

    Accéder à l'API Google Chat

  2. Cliquez sur Gérer, puis sur l'onglet Configuration.

  3. Sous Fonctionnalités interactives, accédez à la section Fonctionnalité pour configurer l'accueil de l'application:

    1. Cochez la case Recevoir des messages privés.
    2. Cochez la case Prise en charge de l'accueil de l'application.

  4. Si votre application Chat utilise un service HTTP, accédez à Paramètres de connexion et spécifiez un point de terminaison pour le champ URL d'accueil de l'application. Vous pouvez utiliser la même URL que celle spécifiée dans le champ URL du point de terminaison HTTP.

  5. Cliquez sur Enregistrer.

Créer une fiche d'accueil d'application

Lorsqu'un utilisateur ouvre l'écran d'accueil de l'application, votre application Chat doit gérer l'événement d'interaction APP_HOME en renvoyant une instance de RenderActions avec la navigation pushCard et un Card. Pour créer une expérience interactive, la fiche peut contenir des widgets interactifs, tels que des boutons ou des entrées de texte, que l'application Chat peut traiter et auxquelles l'application Chat peut répondre par le biais de fiches supplémentaires ou d'une boîte de dialogue.

Dans l'exemple suivant, l'application Chat affiche une fiche d'accueil initiale qui indique l'heure à laquelle la fiche a été créée et un bouton. Lorsqu'un utilisateur clique sur le bouton, l'application Chat renvoie une fiche mise à jour qui affiche l'heure à laquelle elle a été créée.

Node.js

node/app-home/index.js
app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Python

python/app-home/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Process Google Chat events
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

Apps Script

Implémentez la fonction onAppHome appelée après tous les événements d'interaction APP_HOME:

Cet exemple envoie un message de carte en renvoyant un fichier JSON de carte. Vous pouvez également utiliser le service de carte Apps Script.

apps-script/app-home/app-home.gs
/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Répondre aux interactions avec l'écran d'accueil de l'application

Si la fiche d'accueil initiale de votre application contient des widgets interactifs, tels que des boutons ou des entrées de sélection, votre application Chat doit gérer les événements d'interaction associés en renvoyant une instance de RenderActions avec la navigation updateCard. Pour en savoir plus sur la gestion des widgets interactifs, consultez la section Traiter les informations saisies par les utilisateurs.

Dans l'exemple précédent, la fiche d'accueil de l'application initiale incluait un bouton. Chaque fois qu'un utilisateur clique sur le bouton, un événement d'interaction CARD_CLICKED déclenche la fonction updateAppHome pour actualiser la fiche d'accueil de l'application, comme indiqué dans le code suivant:

Node.js

node/app-home/index.js
// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Python

python/app-home/main.py
def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

Apps Script

Cet exemple envoie un message de carte en renvoyant un fichier JSON de carte. Vous pouvez également utiliser le service de carte Apps Script.

apps-script/app-home/app-home.gs
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}

Ouvrir les boîtes de dialogue

Votre application Chat peut également répondre aux interactions dans la page d'accueil de l'application en ouvrant des boîtes de dialogue.

Boîte de dialogue contenant différents widgets
Figure 3: Boîte de dialogue invitant l'utilisateur à ajouter un contact.

Pour ouvrir une boîte de dialogue depuis l'accueil de l'application, traitez l'événement d'interaction associé en renvoyant renderActions avec la navigation updateCard contenant un objet Card. Dans l'exemple suivant, une application Chat répond à un clic sur un bouton depuis la fiche d'accueil d'une application en traitant l'événement d'interaction CARD_CLICKED et en ouvrant une boîte de dialogue:

{ renderActions: { action: { navigations: [{ updateCard: { sections: [{
  header: "Add new contact",
  widgets: [{ "textInput": {
    label: "Name",
    type: "SINGLE_LINE",
    name: "contactName"
  }}, { textInput: {
    label: "Address",
    type: "MULTIPLE_LINE",
    name: "address"
  }}, { decoratedText: {
    text: "Add to favorites",
    switchControl: {
      controlType: "SWITCH",
      name: "saveFavorite"
    }
  }}, { decoratedText: {
    text: "Merge with existing contacts",
    switchControl: {
      controlType: "SWITCH",
      name: "mergeContact",
      selected: true
    }
  }}, { buttonList: { buttons: [{
    text: "Next",
    onClick: { action: { function: "openSequentialDialog" }}
  }]}}]
}]}}]}}}

Pour fermer une boîte de dialogue, traitez les événements d'interaction suivants:

  • CLOSE_DIALOG: ferme la boîte de dialogue et revient à la fiche d'accueil initiale de l'application Chat.
  • CLOSE_DIALOG_AND_EXECUTE: ferme la boîte de dialogue et actualise la fiche d'accueil de l'application.

L'exemple de code suivant utilise CLOSE_DIALOG pour fermer une boîte de dialogue et revenir à la fiche d'accueil de l'application:

{ renderActions: { action: {
  navigations: [{ endNavigation: { action: "CLOSE_DIALOG" }}]
}}}

Pour collecter des informations auprès des utilisateurs, vous pouvez également créer des boîtes de dialogue séquentielles. Pour savoir comment créer des boîtes de dialogue séquentielles, consultez Ouvrir des boîtes de dialogue et y répondre.