Cette page explique comment créer un module complémentaire Google Workspace permettant aux utilisateurs de Google Docs 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 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.
Comment les utilisateurs prévisualisent les liens
Pour prévisualiser des liens dans un document Google Docs, 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 courts du contenu du lien. Lorsque l'utilisateur passe la souris sur le chip, il voit une interface de carte 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:
Conditions préalables
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 pour la première fois un lien de votre service dans un document Google Docs, 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 depuis 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 des aperçus de liens pour votre module complémentaire, et comprend les étapes suivantes:
- Configurez les aperçus des liens dans la ressource de déploiement ou le fichier manifeste de votre module complémentaire.
- Créez l'interface de carte à puce intelligente et de carte pour vos liens.
Configurer les aperçus de lien
Pour configurer les aperçus de lien, 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 Google Docs. Dans le champ
docs
, implémentez le déclencheurlinkPreviewTriggers
qui inclut unrunFunction
(vous définirez cette fonction dans la section suivante, Créer le chip et la carte intelligents).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.
Par exemple, consultez la section oauthScopes
et addons
d'une ressource de déploiement 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"
}
}
]
}
}
}
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. Le module complémentaire spécifie trois formats d'URL pour les liens d'aperçu. Chaque fois qu'un lien correspond à l'un des formats d'URL d'un document Google Docs, la fonction de rappel caseLinkPreview
crée et affiche un chip intelligent et une carte.
Créer la puce et la carte intelligentes
Pour renvoyer une puce intelligente 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 docs.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, pour un module complémentaire spécifiant le format d'URL example.com/cases
, si un utilisateur affiche un aperçu du lien https://www.example.com/cases/123456
, 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 afin d'afficher des informations sur le lien. Vous pouvez également créer des actions permettant aux utilisateurs d'ouvrir le lien ou de modifier son contenu. Pour obtenir la liste des widgets et des actions disponibles, consultez la section Composants compatibles avec les fiches d'aperçu.
Pour créer le chip et la carte intelligents pour un aperçu de 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 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 la section Actions complémentaires.
Le code suivant crée la fonction de rappel caseLinkPreview
:
Apps Script ;
Node.js
Python
Java
Composants compatibles avec les cartes 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 du service de carte de paiement | 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 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 prise en charge. |
Exemple complet: module complémentaire pour la demande 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 et les profils d'employés d'une entreprise.
en effectuant les opérations suivantes :
- Les aperçus renvoient 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. - Aperçu des liens vers les agents de demande d'assistance, tels que
https://www.example.com/people/rosario-cruz
. Le chip intelligent affiche une icône de personne, et la fiche d'aperçu inclut le nom, l'adresse e-mail, le titre du poste et la photo de profil de l'employé. - Si les paramètres régionaux de l'utilisateur sont définis sur l'espagnol, le chip intelligent localise sa
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/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"
}
]
}
}
}
Code
Apps Script ;
Node.js
Python
Java
Ressources associées
- Prévisualiser des liens Google Livres avec les chips intelligents
- Tester votre module complémentaire
- Ressource de déploiement de Google Docs
- Interfaces des cartes pour les aperçus de liens