Pages d'accueil

Les pages d'accueil sont une fonctionnalité des modules complémentaires Google Workspace qui permet de définir une ou plusieurs cartes non contextuelles. Les cartes 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 ouvert.

Les pages d'accueil vous permettent d'afficher du contenu non contextuel, semblable à celui des applications Google du 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 à 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 homepageTrigger fonctions (voir Configuration de la page d'accueil).

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 seule page d'accueil par défaut commune qui est utilisée dans les hôtes où 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).
• Lorsque l'utilisateur passe d'un contexte contextuel à un contexte non contextuel alors que le module complémentaire est ouvert. Par exemple, lorsqu'il passe de la modification d'un événement Agenda à l'Agenda principal.
• Lorsque l'utilisateur clique suffisamment de fois sur le bouton "Retour" pour supprimer toutes les autres cartes des piles internes.
• Lorsqu'une interaction d'interface utilisateur dans une carte non contextuelle entraîne un Navigation.popToRoot appel.

Il est recommandé de concevoir une page d'accueil. Si vous n'en définissez aucune, une carte 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 par défaut (non contextuel) de la page d'accueil du module complémentaire pour les 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 des modules complémentaires Google Workspace appelle pour afficher les cartes de la page d'accueil du module complémentaire. Cette fonction est la fonction de déclenchement de la page d'accueil. Elle doit créer et renvoyer un tableau d'Card objets qui composent l'interface utilisateur de la page d'accueil. Si plusieurs cartes sont renvoyées, l' application hôte affiche les en-têtes des cartes dans une liste que l'utilisateur peut sélectionner (voir Renvoyer plusieurs cartes).

• enabled : indique si les cartes de la page d'accueil doivent être activées pour cette portée. Ce champ est facultatif et sa valeur par défaut est true. Si vous définissez cette valeur sur false, les cartes de la page d'accueil sont 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 utilise 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, dans 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 remplacée ou 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 le homepageTrigger par défaut et la configuration Gmail sont omis :

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

Aucune des sections homepageTrigger n'est obligatoire. L'interface utilisateur 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éclenchement de module complémentaire qui sont exécutées pour créer une interface utilisateur de page d'accueil pour différentes configurations de fichier manifeste :

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) décrite précédemment reçoit un objet d'événement contenant des données du contexte d'appel.

Les objets d'événement de la page d'accueil n'incluent pas d'informations sur les widgets ni de contexte. Les informations transmises sont limitées aux champs d'objet d'événement courants suivants :

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale et commonEventObject.userTimezone (consultez Accéder aux paramètres régionaux et au fuseau horaire de l'utilisateur pour obtenir des informations sur les restrictions ).

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

Autres cartes non contextuelles

L'interface utilisateur de votre module complémentaire peut contenir d'autres cartes non contextuelles qui ne sont pas des pages d'accueil. Par exemple, votre page d'accueil peut comporter un bouton qui ouvre une carte "Paramètres" pour 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 en savoir plus sur la création de transitions entre les cartes, consultez Méthodes de navigation.