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 à un outil externe et de l'utiliser depuis Chat.

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

Ouvrir Card Builder

Prérequis

Node.js

Une application Google Chat qui reçoit des événements d'interaction et y répond. 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 qui reçoit des événements d'interaction et y répond. 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 qui reçoit des événements d'interaction et y répond. 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 qui reçoit des événements d'interaction et y répond. Pour créer une application Chat interactive dans Apps Script, suivez ce guide de démarrage rapide.

Configurer l'accueil de l'application pour votre application Chat

Pour prendre en charge l'accueil de l'application, vous devez configurer votre application Chat pour qu'elle reçoive APP_HOME événements d'interaction, 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 modifier vos paramètres de configuration dans la console Google Cloud, procédez comme suit :

Dans la console Google Cloud, cliquez sur Menu > API et services > API et services activés > API Google Chat > Configuration. Accéder à la configuration de l'API Chat
Sous Fonctionnalités interactives, accédez à la section Fonctionnalité, puis sélectionnez Prise en charge de l'accueil de l'application.
Si votre application Chat utilise un service HTTP, accédez à Paramètres de connexion et spécifiez un point de terminaison pour le URL de l'accueil de l'application champ. Vous pouvez utiliser la même URL que celle que vous avez spécifiée dans le champ URL du point de terminaison HTTP.
Cliquez sur Enregistrer.

Créer une fiche d'accueil de l'application

Lorsqu'un utilisateur ouvre l'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 une 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 auxquels elle peut répondre avec des fiches supplémentaires ou 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 indique l'heure à laquelle la fiche mise à jour a été créée.

Node.js

node/app-home/index.js

Afficher sur GitHub

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

Afficher sur GitHub

@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

Afficher sur GitHub

// 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 qui est appelée après tous les événements d'interaction APP_HOME :

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

apps-script/app-home/app-home.gs

Afficher sur GitHub

/**
 * 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 de l'accueil de l'application

Si votre fiche d'accueil initiale 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 updateCard navigation. Pour en savoir plus sur la gestion des widgets interactifs, consultez Traiter les informations saisies par les utilisateurs.

Dans l'exemple précédent, la fiche d'accueil initiale comprenait 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 illustré dans le code suivant :

Node.js

node/app-home/index.js

Afficher sur GitHub

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

Python

python/app-home/main.py

Afficher sur GitHub

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

Afficher sur GitHub

// 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 fiche en renvoyant le JSON de la fiche. Vous pouvez également utiliser le service de fiche Apps Script.

apps-script/app-home/app-home.gs

Afficher sur GitHub

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

Ouvrir des boîtes de dialogue

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

Boîte de dialogue comportant différents widgets. — **Figure 3** : Boîte de dialogue invitant un utilisateur à ajouter un contact.

Pour ouvrir une boîte de dialogue à partir de l'accueil de l'application, traitez l'événement d'interaction associé en renvoyant renderActions avec updateCard navigation qui contient un Card objet. Dans l'exemple suivant, une application Chat répond à un clic sur un bouton à partir d'une fiche d'accueil de l'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.

Consultez des exemples d'applications Chat qui utilisent l'accueil de l'application.
Ouvrir des boîtes de dialogue et y répondre.

Créer une page d'accueil pour une application Google Chat Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Prérequis

Node.js

Python

Java

Apps Script

Configurer l'accueil de l'application pour votre application Chat

Créer une fiche d'accueil de l'application

Node.js

Python

Java

Apps Script

Répondre aux interactions de l'accueil de l'application

Node.js

Python

Java

Apps Script

Ouvrir des boîtes de dialogue

Articles associés

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