Cette page explique comment créer un module complémentaire Google Workspace permettant aux utilisateurs de Google Docs d'afficher un aperçu des liens depuis un service tiers.
Un module complémentaire Google Workspace peut détecter les liens de votre service et inviter les utilisateurs de Google Docs à les prévisualiser. Vous pouvez configurer un module complémentaire pour prévisualiser plusieurs formats d'URL, tels que des liens vers des demandes d'assistance, des prospects commerciaux et des profils d'employés.
Aperçu des liens par les utilisateurs
Pour prévisualiser les liens dans un document Google Docs, les utilisateurs interagissent avec des chips intelligents et des fiches:
Lorsque les utilisateurs saisissent ou collez une URL dans un document, Google Docs les invite à remplacer le lien par un chip intelligent. L'icône intelligente affiche une icône et un titre court ou une description pour le contenu du lien. Lorsque l'utilisateur pointe sur le chip, une interface de fiche s'affiche qui affiche un aperçu des informations sur le fichier ou le lien.
La vidéo suivante montre comment un utilisateur convertit un lien en chip intelligent et affiche un aperçu d'une carte:
Prérequis
Apps Script
- Un compte Google Workspace.
- Un module complémentaire Google Workspace Pour créer un module complémentaire, suivez ce guide de démarrage rapide.
Node.js
- Un compte Google Workspace.
- Un module complémentaire Google Workspace Pour créer un module complémentaire, suivez ce guide de démarrage rapide.
Python
- Un compte Google Workspace.
- Un module complémentaire Google Workspace Pour créer un module complémentaire, suivez ce guide de démarrage rapide.
Java
- Un compte Google Workspace.
- Un module complémentaire Google Workspace Pour créer un module complémentaire, suivez ce guide de démarrage rapide.
Facultatif: configurer l'authentification auprès d'un service tiers
Si votre module complémentaire se connecte à un service nécessitant une autorisation, les utilisateurs doivent s'authentifier auprès de ce service pour prévisualiser les liens. Cela signifie que lorsque les utilisateurs collez un lien de votre service dans un document Google Docs pour la première fois, votre module complémentaire doit appeler le flux d'autorisation.
Pour configurer un service OAuth ou une invite d'autorisation personnalisée, consultez l'un des guides suivants:
Si vous avez créé votre module complémentaire à l'aide d'Apps Script, consultez Se connecter à des services autres que Google à partir d'un module complémentaire Google Workspace.
Si vous avez créé votre module complémentaire à l'aide d'un autre environnement d'exécution, consultez Connecter votre module complémentaire à un service tiers.
Configurer des aperçus de liens pour votre module complémentaire
Cette section explique comment configurer des aperçus de liens pour votre module complémentaire, en procédant comme suit:
- Configurez les aperçus de liens dans la ressource de déploiement ou le fichier manifeste de votre module complémentaire.
- Créez l'interface intelligente pour la puce et la carte pour vos liens.
Configurer des aperçus de liens
Pour configurer les aperçus de liens, spécifiez les sections et champs suivants dans la ressource de déploiement ou le fichier manifeste de votre module complémentaire:
- Dans la section
addOns
, ajoutez le champdocs
pour étendre Google Docs. Dans le champ
docs
, implémentez le déclencheurlinkPreviewTriggers
qui inclut unrunFunction
(vous définissez cette fonction dans la section suivante, Créer la puce intelligente et la carte).Pour en savoir plus sur les champs que vous pouvez spécifier dans le déclencheur
linkPreviewTriggers
, consultez la documentation de référence sur les fichiers manifestes Apps Script ou les ressources de déploiement pour d'autres environnements d'exécution.Dans le champ
oauthScopes
, ajoutez le champ d'applicationhttps://www.googleapis.com/auth/workspace.linkpreview
afin que les utilisateurs puissent autoriser le module complémentaire à prévisualiser les liens en leur nom.
À titre d'exemple, consultez les sections oauthScopes
et addons
d'une ressource de déploiement qui configure l'aperçu des liens pour un service de demande d'assistance:
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://www.example.com/images/company-logo.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
}
}
}
Dans cet exemple, le module complémentaire Google Workspace Previews contient des liens vers le service de demande d'assistance d'une entreprise. Le module complémentaire spécifie trois formats d'URL pour prévisualiser les liens. Chaque fois qu'un lien correspond à l'un des formats d'URL dans un document Google Docs, la fonction de rappel caseLinkPreview
crée et affiche une icône ou une carte à puce.
Créer la puce intelligente et la carte
Pour renvoyer un chip intelligent et une carte pour un lien, vous devez implémenter toutes les fonctions que vous avez spécifiées dans l'objet linkPreviewTriggers
.
Lorsqu'un utilisateur interagit avec un lien correspondant à un format d'URL spécifié, le déclencheur linkPreviewTriggers
se déclenche et sa fonction de rappel transmet l'objet événement docs.matchedUrl.url
en tant qu'argument. Vous utilisez la charge utile de cet objet d'événement pour créer la puce intelligente et la carte pour l'aperçu du lien.
Par exemple, pour un module complémentaire qui spécifie le format d'URL example.com/cases
, si un utilisateur prévisualise le lien https://www.example.com/cases/123456
, la charge utile de l'événement suivante est renvoyée:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Pour créer l'interface de la carte, vous devez utiliser des widgets afin d'afficher des informations sur le lien. Vous pouvez également créer des actions permettant aux utilisateurs d'ouvrir le lien ou d'en modifier le contenu. Pour obtenir la liste des widgets et des actions disponibles, consultez Composants compatibles avec les fiches d'aperçu.
Pour créer l'icône et la carte à puce pour l'aperçu d'un lien:
- Mettez en œuvre la fonction que vous avez spécifiée dans la section
linkPreviewTriggers
de la ressource de déploiement ou du fichier manifeste de votre module complémentaire :- La fonction doit accepter un objet d'événement contenant
docs.matchedUrl.url
comme argument et renvoyer un seul objetCard
. - Si votre service nécessite une autorisation, la fonction doit également appeler le flux d'autorisation.
- La fonction doit accepter un objet d'événement contenant
- Pour chaque fiche d'aperçu, implémentez les fonctions de rappel utilisées pour permettre l'interactivité des widgets pour l'interface. Par exemple, si vous incluez un bouton dans l'interface, celui-ci doit être associé à une
Action
et à une fonction de rappel implémentée qui s'exécute lorsque l'utilisateur clique sur le bouton.
Le code suivant crée la fonction de rappel caseLinkPreview
:
Apps Script
Node.js
Python
Java
Composants compatibles avec les fiches d'aperçu
Les modules complémentaires Google Workspace sont compatibles avec les widgets et actions suivants pour les fiches d'aperçu des liens:
Apps Script
Champ "Service de carte" | Type |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
IconImage |
Widget |
ButtonSet |
Widget |
TextButton |
Widget |
ImageButton |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Action |
Navigation |
Action Seule la méthode updateCard est acceptée. |
JSON
Champ "Fiche" (google.apps.card.v1 ) |
Type |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
Icon |
Widget |
ButtonList |
Widget |
Button |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Action |
Navigation |
Action Seule la méthode updateCard est acceptée. |
Exemple complet: module complémentaire de demande d'assistance
L'exemple suivant présente un module complémentaire Google Workspace qui affiche un lien vers les demandes d'assistance et les profils des employés de l'entreprise.
en effectuant les opérations suivantes :
- Les aperçus pointent vers des demandes d'assistance, comme
https://www.example.com/support/cases/1234
. Le chip intelligent affiche une icône d'assistance, et la fiche d'aperçu inclut le numéro de demande et une description. - Permet de prévisualiser les liens vers les agents de la demande d'assistance, tels que
https://www.example.com/people/rosario-cruz
. L'icône intelligente affiche une icône représentant une personne, et la fiche d'aperçu contient le nom, l'adresse e-mail, l'intitulé du poste et la photo du profil de l'employé. - Si les paramètres régionaux de l'utilisateur sont en espagnol, le chip intelligent localise son
labelText
en espagnol.
Ressource de déploiement
Apps Script
{
"timeZone": "America/New_York",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/link-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
},
{
"runFunction": "peopleLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/link-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
},
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}
Coder
Apps Script
Node.js
Python
Java
Ressources associées
- Tester votre module complémentaire
- Ressource de déploiement de Google Docs
- Interfaces de fiche pour les aperçus de liens