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 la page d'accueil de l'application pour partager des conseils sur l'interaction avec application de chat, ou autoriser les utilisateurs à accéder à une application d'un service ou d'un outil externe depuis Chat.

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

Ouvrir l'outil de création de cartes

Prérequis

Node.js

Une application Google Chat avec des fonctionnalités interactives. Pour créer un une application Chat interactive utilisant 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 avec des fonctionnalités interactives. 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 l'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 indiquée dans le URL du point de terminaison HTTP.

  5. Cliquez sur Enregistrer.

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

<ph type="x-smartling-placeholder">

Lorsqu'un utilisateur ouvre la page d'accueil de l'application, celle-ci doit gérer l'événement d'interaction APP_HOME en renvoyant une instance de RenderActions avec la navigation pushCard et 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 de l'application qui affiche l'heure à laquelle la carte 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 la fiche mise à jour 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
 *
 * @param event Event from chat.
 * @return GenericJson
 * @throws Exception
 */
@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() {
  GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
  textParagraph.setText("Here is the app home 🏠 It's " + new Date());

  GoogleAppsCardV1Widget textParagraphWidget = new GoogleAppsCardV1Widget();
  textParagraphWidget.setTextParagraph(textParagraph);

  GoogleAppsCardV1Action action = new GoogleAppsCardV1Action();
  action.setFunction("updateAppHome");

  GoogleAppsCardV1OnClick onClick = new GoogleAppsCardV1OnClick();
  onClick.setAction(action);

  GoogleAppsCardV1Button button = new GoogleAppsCardV1Button();
  button.setText("Update app home");
  button.setOnClick(onClick);

  GoogleAppsCardV1ButtonList buttonList = new GoogleAppsCardV1ButtonList();
  buttonList.setButtons(List.of(button));

  GoogleAppsCardV1Widget buttonListWidget = new GoogleAppsCardV1Widget();
  buttonListWidget.setButtonList(buttonList);

  GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
  section.setWidgets(List.of(textParagraphWidget, buttonListWidget));

  GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
  card.setSections(List.of(section));

  return card;
}

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 fichier JSON de la 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 interactions des widgets, consultez l'article Traiter les informations saisies par les utilisateurs.

Dans l'exemple précédent, la fiche d'accueil initiale de l'application incluait un bouton. À tout moment 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 fichier JSON de la carte. Vous pouvez également utiliser Service de cartes 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.

<ph type="x-smartling-placeholder">
</ph> Boîte de dialogue présentant 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 à partir d'une fiche d'accueil d'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 la section Ouvrir et répondre aux boîtes de dialogue.