Cette page explique comment créer un module complémentaire Google Workspace permettant aux utilisateurs de Google Docs, Sheets et Slides de prévisualiser les liens d'un service tiers.
Un module complémentaire Google Workspace peut détecter les liens de votre service et inviter les utilisateurs à 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.
Comment les utilisateurs prévisualisent-ils les liens ?
Pour prévisualiser des liens, les utilisateurs interagissent avec des chips intelligents et des fiches.
Lorsque les utilisateurs saisissent ou collent une URL dans un document, Google Docs les invite à remplacer le lien par un chip intelligent. Le chip intelligent affiche une icône et un titre ou une description court du contenu du lien. Lorsque l'utilisateur pointe sur le chip, il voit une interface de fiche qui affiche plus d'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 fiche:
Prévisualisation des liens dans Sheets et Slides par les utilisateurs
Les chips intelligents tiers ne sont pas compatibles avec les aperçus de liens dans Sheets et Slides. Lorsque les utilisateurs saisissent ou collent une URL dans une feuille de calcul ou une présentation, Sheets ou Slides les invite à remplacer le lien par son titre en tant que texte lié plutôt que sous forme de chip. Lorsque l'utilisateur pointe sur le titre du lien, il voit une interface de fiche qui affiche un aperçu des informations sur le lien.
L'image suivante illustre le rendu d'un aperçu de lien dans Sheets et Slides:
Prérequis
Apps Script ;
- Un compte Google Workspace
- Un module complémentaire Google Workspace. Pour créer un module complémentaire, suivez ce quickstart.
Node.js
- Un compte Google Workspace
- Un module complémentaire Google Workspace. Pour créer un module complémentaire, suivez ce quickstart.
Python
- Un compte Google Workspace
- Un module complémentaire Google Workspace. Pour créer un module complémentaire, suivez ce quickstart.
Java
- Un compte Google Workspace
- Un module complémentaire Google Workspace. Pour créer un module complémentaire, suivez ce quickstart.
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 du service pour prévisualiser les liens. Cela signifie que lorsque les utilisateurs collent un lien de votre service dans un fichier Docs, Sheets ou Slides 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 la section 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 la section Connecter votre module complémentaire à un service tiers.
Configurer des aperçus de liens pour votre module complémentaire
Cette section explique comment configurer les aperçus des 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 de carte à puce intelligente pour vos liens.
Configurer les aperçus de lien
Pour configurer les aperçus de liens, spécifiez les sections et les 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 Docs, le champsheets
pour étendre Sheets et le champslides
pour étendre Slides. Dans chaque champ, implémentez le déclencheur
linkPreviewTriggers
qui inclut unrunFunction
(vous définissez cette fonction dans la section suivante, Créer le chip intelligent et la carte).Pour savoir quels champs 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.
Par exemple, consultez la section oauthScopes
et addons
de la ressource de déploiement suivante, qui configure les aperçus de lien 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"
}
}
]
},
"sheets": {
"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"
}
}
]
},
"slides": {
"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 affiche un aperçu des liens vers le service de demande d'assistance d'une entreprise. Celui-ci spécifie trois formats d'URL pour prévisualiser les liens. Chaque fois qu'un lien correspond à l'un des formats d'URL, la fonction de rappel caseLinkPreview
crée et affiche une fiche et un chip intelligent, ou bien dans Sheets et Slides, elle remplace l'URL par le titre du lien.
Créer une puce et une carte intelligentes
Pour renvoyer une puce ou une carte à puce 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
s'active et sa fonction de rappel transmet l'objet d'événement EDITOR_NAME.matchedUrl.url
en tant qu'argument. Vous utiliserez la charge utile de cet objet d'événement pour créer le chip intelligent et la carte pour l'aperçu de votre lien.
Par exemple, si un utilisateur prévisualise le lien https://www.example.com/cases/123456
dans Docs, la charge utile d'événement suivante est renvoyée:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Pour créer l'interface de la fiche, vous utilisez des widgets pour afficher des informations sur le lien. Vous pouvez également créer des actions qui permettent aux utilisateurs d'ouvrir le lien ou de modifier son contenu. Pour obtenir la liste des widgets et actions disponibles, consultez la section Composants compatibles pour les fiches d'aperçu.
Pour créer une icône et une carte intelligentes pour l'aperçu d'un lien, procédez comme suit:
- Implémentez la fonction que vous avez spécifiée dans la section
linkPreviewTriggers
de la ressource de déploiement de votre module complémentaire ou du fichier manifeste :- La fonction doit accepter un objet d'événement contenant
EDITOR_NAME.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 des fonctions de rappel qui fournissent une interactivité des widgets pour l'interface. Par exemple, si vous incluez un bouton "Afficher le lien", vous pouvez créer une action qui spécifie une fonction de rappel pour ouvrir le lien dans une nouvelle fenêtre. Pour en savoir plus sur les interactions avec les widgets, consultez Actions des modules complémentaires.
Le code suivant crée la fonction de rappel caseLinkPreview
pour Docs:
Apps Script ;
Node.js
Python
Java
Composants compatibles avec les fiches d'aperçu
Les modules complémentaires Google Workspace sont compatibles avec les actions et widgets suivants pour les fiches d'aperçu des liens:
Apps Script ;
Champ du 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 de la carte (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 pour les demandes d'assistance
L'exemple suivant présente un module complémentaire Google Workspace qui affiche un aperçu des liens vers les demandes d'assistance d'une entreprise dans Google Docs.
en effectuant les opérations suivantes :
- Aperçu des liens vers des demandes d'assistance, telles que
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. - Si les paramètres régionaux de l'utilisateur sont définis sur l'espagnol, le chip intelligent localise son
labelText
en espagnol.
Ressource de déploiement
Apps Script ;
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-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"
}
]
}
}
}
Coder
Apps Script ;
Node.js
Python
Java
Ressources associées
- Prévisualiser les liens de Google Livres avec les chips intelligents
- Tester votre module complémentaire
- Ressource pour le déploiement de Google Docs
- Interfaces des cartes pour les aperçus des liens