Pages d'accueil

Les pages d'accueil sont une fonctionnalité des modules complémentaires Google Workspace qui permet de définir une ou plusieurs fiches non contextuelles. Les fiches non contextuelles affichent une interface utilisateur lorsque l'utilisateur se trouve en dehors d'un contexte spécifique, par exemple lorsqu'il consulte sa boîte de réception Gmail sans message ni brouillon ouverts.

Les pages d'accueil vous permettent d'afficher du contenu non contextuel, comme les applications Google dans le panneau latéral Accès rapide (Google Keep, Google Agenda et Google Tasks). Les pages d'accueil peuvent également servir de point de départ lorsqu'un utilisateur ouvre votre module complémentaire pour la première fois. Elles sont utiles pour apprendre aux nouveaux utilisateurs comment interagir avec votre module complémentaire.

Définissez une page d'accueil pour votre module complémentaire en la spécifiant dans le fichier manifeste de votre projet et en implémentant une ou plusieurs fonctions homepageTrigger (voir Configuration de la page d'accueil). Si votre module complémentaire étend Google Chat, sa page d'accueil s'affiche dans l'onglet Accueil d'un message privé avec l'application Chat et est configurée dans la console Google Cloud au lieu du fichier manifeste (voir Configurer une page d'accueil pour Chat).

Vous pouvez avoir plusieurs pages d'accueil, une pour chaque application hôte que votre module complémentaire étend. Vous pouvez également définir une page d'accueil par défaut unique et commune qui sera utilisée sur les hôtes pour lesquels vous n'avez pas spécifié de page d'accueil personnalisée.

La page d'accueil de votre module complémentaire s'affiche dans les cas suivants :

  • Lorsque le module complémentaire est ouvert pour la première fois dans l'hôte (après autorisation) ou lorsqu'un utilisateur ouvre l'onglet Accueil dans un message privé avec votre application Chat dans Chat.
  • Lorsque l'utilisateur passe d'un contexte contextuel à un contexte non contextuel alors que le module complémentaire est ouvert. Par exemple, de la modification d'un événement d'agenda à l'agenda principal.
  • Lorsque l'utilisateur clique sur le bouton "Retour" suffisamment de fois pour faire sortir une carte sur deux des piles internes.
  • Lorsqu'une interaction avec l'UI dans une fiche non contextuelle entraîne un appel Navigation.popToRoot.

Nous vous recommandons de concevoir une page d'accueil. Si vous n'en définissez aucune, une fiche générique contenant le nom de votre module complémentaire est utilisée chaque fois qu'un utilisateur accède à la page d'accueil.

Configuration de la page d'accueil

Les modules complémentaires Google Workspace utilisent le champ addOns.common.homepageTrigger pour configurer le contenu de la page d'accueil par défaut (non contextuel) des applications hôtes dans le fichier manifeste du module complémentaire :

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

  • runFunction : nom de la fonction Google Apps Script que le framework de modules complémentaires Google Workspace appelle pour afficher les fiches de modules complémentaires de la page d'accueil. Cette fonction est la fonction de déclenchement de la page d'accueil. Cette fonction doit créer et renvoyer un tableau d'objets Card qui composent l'UI de la page d'accueil. Si plusieurs cartes sont renvoyées, l'application hôte affiche les en-têtes de carte dans une liste que l'utilisateur peut sélectionner (voir Renvoi de plusieurs cartes).

  • enabled : indique si les fiches de la page d'accueil doivent être activées pour ce champ d'application. Ce champ est facultatif et la valeur par défaut est true. Si vous définissez cette valeur sur false, les fiches de la page d'accueil seront désactivées pour tous les hôtes (sauf si elles sont remplacées pour cet hôte ; consultez la configuration spécifique à l'hôte).

Pour qu'un hôte puisse utiliser la page d'accueil commune, addOns.common.homepageTrigger et la ressource de premier niveau de l'hôte doivent être présents dans le manifeste du module complémentaire. Par exemple, si addOns.gmail n'est pas présent dans le fichier manifeste, le module complémentaire est désactivé pour Gmail et n'affiche pas de page d'accueil ni d'autres fonctionnalités dans cet hôte.

En plus de la configuration commune, des remplacements par hôte de structure identique sont disponibles dans la configuration de chaque application hôte, au niveau de addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger et d'autres déclencheurs spécifiques à l'hôte.

L'exemple suivant montre un fichier manifeste dans lequel un déclencheur de page d'accueil commun est défini, mais remplacé par des fonctions personnalisées pour Agenda et Drive, et désactivé pour Gmail. Dans cette configuration, la fonction buildHomePage commune ne s'exécute jamais, car elle est soit remplacée, soit l'hôte est désactivé.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

L'extrait de fichier manifeste suivant est équivalent à l'exemple précédent, même si la homepageTrigger par défaut et la configuration Gmail sont omises :

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

Aucune des sections homepageTrigger n'est obligatoire. L'UI affichée pour un module complémentaire dans un produit hôte dépend de la présence du champ de fichier manifeste correspondant et de l'existence d'un homepageTrigger associé. L'exemple suivant montre les fonctions de déclencheur de module complémentaire qui sont exécutées pour créer une UI de page d'accueil pour différentes configurations de fichier manifeste :

Diagramme illustrant le flux d'exécution de la fonction de déclencheur de la page d'accueil du module complémentaire

Configurer une page d'accueil pour Chat

Contrairement aux autres applications hôtes Google Workspace, les modules complémentaires qui étendent Chat n'affichent pas de page d'accueil dans le panneau d'accès rapide de droite et n'utilisent pas addOns.common.homepageTrigger dans le fichier manifeste. Au lieu de cela, Chat affiche votre page d'accueil sous forme de fiche dans l'onglet Accueil d'un message privé avec l'application Chat.

Pour activer et configurer un déclencheur de page d'accueil de l'application pour votre module complémentaire Chat dans la console Google Cloud :

  1. Dans la console Google Cloud, accédez à Menu > API et services > API et services activés > API Google Chat > Configuration.

    Accéder à la configuration de l'API Google Chat

  2. Sous Fonctionnalités interactives, assurez-vous que l'option Activer les fonctionnalités interactives est activée, puis cochez la case Prise en charge de l'accueil de l'application.

  3. Sous Paramètres de connexion > Déclencheurs, spécifiez votre gestionnaire App Home dans le champ App Home en fonction de l'architecture de votre module complémentaire :

    • HTTP : saisissez l'URL du point de terminaison HTTPS qui gère les requêtes de la page d'accueil de l'application (ou laissez-la vide pour que votre URL de point de terminaison HTTP commun reçoive tous les événements).
    • Google Apps Script : saisissez le nom de la fonction de rappel Google Apps Script qui crée et renvoie la fiche de votre page d'accueil (la valeur par défaut est onAppHome).

  4. Cliquez sur Enregistrer.

Lorsqu'un utilisateur ouvre l'onglet Accueil d'un message privé avec votre application Chat, Chat envoie un événement de déclenchement Accueil de l'application à votre point de terminaison ou fonction. Pour afficher la page d'accueil, renvoyez un objet RenderActions avec une action de navigation pushCard (ou utilisez updateCard lorsque vous mettez à jour la page d'accueil en réponse à un clic sur un bouton de la fiche de la page d'accueil) :

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

Pour en savoir plus sur la gestion des déclencheurs Chat et des actions de retour, consultez Recevoir des interactions utilisateur et y répondre.

Objets d'événement de la page d'accueil

Lorsqu'elle est appelée, la fonction de déclenchement de la page d'accueil (runFunction) ou le point de terminaison App Home décrit précédemment reçoit un objet d'événement contenant des données du contexte d'invocation.

Les objets d'événement de la page d'accueil n'incluent pas d'informations sur les widgets ni de contexte. Les informations transmises incluent les champs suivants de l'objet d'événement commun :

Dans Chat, l'objet d'événement "App Home" inclut également le champ chat avec des informations sur l'utilisateur et le temps d'interaction :

  • chat.user : utilisateur Chat qui a ouvert l'onglet Accueil.
  • chat.eventTime : code temporel indiquant le moment où l'utilisateur a ouvert l'onglet Accueil.

Pour en savoir plus, consultez Objet d'événement.

Autres fiches non contextuelles

L'UI de votre module complémentaire peut contenir des fiches non contextuelles supplémentaires qui ne sont pas des pages d'accueil. Par exemple, votre page d'accueil peut comporter un bouton qui ouvre une fiche "Paramètres" permettant d'ajuster les paramètres du module complémentaire (ces paramètres sont généralement indépendants du contexte).

Les cartes non contextuelles sont créées comme n'importe quelle autre carte. La seule différence réside dans l'action ou l'événement qui génère et affiche la carte. Pour savoir comment créer des transitions entre les cartes, consultez Méthodes de navigation.