En esta página, se explica cómo compilar un complemento de Google Workspace que permita a los usuarios de Documentos de Google obtener una vista previa de los vínculos de un servicio de terceros.
Un complemento de Google Workspace puede detectar los vínculos de tu servicio y solicitar a los usuarios de Documentos de Google que obtengan una vista previa de ellos. Puedes configurar un complemento para obtener una vista previa de varios patrones de URL, como vínculos a casos de ayuda, clientes potenciales de venta y perfiles de empleados.
Cómo los usuarios obtienen una vista previa de los vínculos
Para obtener una vista previa de los vínculos de un documento de Documentos de Google, los usuarios interactúan con chips y tarjetas inteligentes:
Cuando los usuarios escriben o pegan una URL en un documento, Documentos de Google les pide que reemplacen el vínculo por un chip inteligente. El chip inteligente muestra un ícono y un título corto o una descripción del contenido del vínculo. Cuando el usuario se desplaza sobre el chip, ve una interfaz de tarjeta en la que se muestra una vista previa de más información sobre el archivo o el vínculo.
En el siguiente video, se muestra cómo un usuario convierte un vínculo en un chip inteligente y obtiene una vista previa de una tarjeta:
Requisitos previos
Apps Script
- Una cuenta de Google Workspace
- Un complemento de Google Workspace Para compilar un complemento, sigue esta guía de inicio rápido.
Node.js
- Una cuenta de Google Workspace
- Un complemento de Google Workspace Para compilar un complemento, sigue esta guía de inicio rápido.
Python
- Una cuenta de Google Workspace
- Un complemento de Google Workspace Para compilar un complemento, sigue esta guía de inicio rápido.
Java
- Una cuenta de Google Workspace
- Un complemento de Google Workspace Para compilar un complemento, sigue esta guía de inicio rápido.
Configura la autenticación para un servicio de terceros (opcional)
Si tu complemento se conecta a un servicio que requiere autorización, los usuarios deben autenticarse en el servicio para obtener una vista previa de los vínculos. Esto significa que, cuando los usuarios pegan un vínculo de tu servicio en un documento de Documentos de Google por primera vez, tu complemento debe invocar el flujo de autorización.
Para configurar un servicio de OAuth o una solicitud de autorización personalizada, consulta una de las siguientes guías:
Si creaste tu complemento con Apps Script, consulta Cómo conectarse a servicios que no son de Google desde un complemento de Google Workspace.
Si compilaste tu complemento con un entorno de ejecución diferente, consulta Conecta tu complemento a un servicio de terceros.
Configura las vistas previas de vínculos para tu complemento
En esta sección, se explica cómo configurar las vistas previas de vínculos para tu complemento, que incluye los siguientes pasos:
- Configura las vistas previas de vínculos en el recurso de implementación o el archivo de manifiesto del complemento.
- Compila el chip inteligente y la interfaz de la tarjeta para tus vínculos.
Configura vistas previas de vínculos
Para configurar las vistas previas de vínculos, especifica las siguientes secciones y campos en el archivo de manifiesto o recurso de implementación del complemento:
- En la sección
addOns
, agrega el campodocs
para extender Documentos de Google. En el campo
docs
, implementa el activadorlinkPreviewTriggers
que incluye unrunFunction
(debes definir esta función en la siguiente sección, Compila el chip y la tarjeta inteligentes).Si deseas obtener información sobre qué campos puedes especificar en el activador
linkPreviewTriggers
, consulta la documentación de referencia de los archivos de manifiesto de Apps Script o los recursos de implementación para otros entornos de ejecución.En el campo
oauthScopes
, agrega el permisohttps://www.googleapis.com/auth/workspace.linkpreview
para que los usuarios puedan autorizar el complemento a fin de obtener una vista previa de los vínculos en su nombre.
Como ejemplo, consulta las secciones oauthScopes
y addons
de un recurso de implementación que configura vistas previas de vínculos para un servicio de casos de ayuda:
{
"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"
}
}
]
}
}
}
En el ejemplo, los complementos de Google Workspace de la vista previa del servicio de caso de ayuda de una empresa. El complemento especifica tres patrones de URL para obtener una vista previa de los vínculos. Cada vez que un vínculo coincide con uno de los patrones de URL de un documento de Documentos de Google, la función de devolución de llamada caseLinkPreview
compila y muestra un chip y una tarjeta inteligentes.
Compila el chip y la tarjeta inteligentes
Si quieres que se muestren un chip y una tarjeta inteligentes para un vínculo, debes implementar cualquier función que hayas especificado en el objeto linkPreviewTriggers
.
Cuando un usuario interactúa con un vínculo que coincide con un patrón de URL especificado, el activador linkPreviewTriggers
se activa y su función de devolución de llamada pasa el objeto de evento docs.matchedUrl.url
como argumento. Usa la carga útil de este objeto de evento a fin de compilar el chip y la tarjeta inteligentes para la vista previa de tu vínculo.
Por ejemplo, en el caso de un complemento que especifica el patrón de URL example.com/cases
,
si un usuario obtiene una vista previa del vínculo https://www.example.com/cases/123456
, se mostrará
la siguiente carga útil:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Para crear la interfaz de la tarjeta, usa widgets a fin de mostrar información sobre el vínculo. También puedes crear acciones que les permitan a los usuarios abrir el vínculo o modificar su contenido. Si deseas obtener una lista de widgets y acciones disponibles, consulta Componentes compatibles con tarjetas de vista previa.
Sigue estos pasos para compilar el chip y la tarjeta inteligentes a fin de obtener una vista previa de un vínculo:
- Implementa la función que especificaste en la sección
linkPreviewTriggers
del archivo de manifiesto o recurso de implementación del complemento:- La función debe aceptar un objeto de evento que contenga
docs.matchedUrl.url
como argumento y mostrar un solo objetoCard
. - Si tu servicio requiere autorización, la función también debe invocar el flujo de autorización.
- La función debe aceptar un objeto de evento que contenga
- En cada tarjeta de vista previa, implementa las funciones de devolución de llamada usadas a fin de proporcionar interactividad de widget para la interfaz. Por ejemplo, si incluyes un botón en la interfaz, debería tener un
Action
adjunto y una función de devolución de llamada implementada que se ejecute cuando se haga clic en el botón.
El siguiente código crea la función de devolución de llamada caseLinkPreview
:
Apps Script
Node.js
Python
Java
Componentes compatibles con tarjetas de vista previa
Los complementos de Google Workspace admiten los siguientes widgets y acciones para las tarjetas de vista previa de vínculos:
Apps Script
Campo Servicio de tarjeta | Tipo |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
IconImage |
Widget |
ButtonSet |
Widget |
TextButton |
Widget |
ImageButton |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Acción |
Navigation |
Acción Solo se admite el método updateCard . |
JSON
Campo de tarjeta (google.apps.card.v1 ) |
Tipo |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
Icon |
Widget |
ButtonList |
Widget |
Button |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Acción |
Navigation |
Acción Solo se admite el método updateCard . |
Ejemplo completo: complemento de caso de asistencia
En el siguiente ejemplo, se presenta un complemento de Google Workspace que ofrece una vista previa de vínculos a casos de ayuda y perfiles de empleados de una empresa.
En el ejemplo, se realizan las acciones siguientes:
- El vínculo de vista previa para casos de ayuda, como
https://www.example.com/support/cases/1234
El chip inteligente muestra un ícono de asistencia, y la tarjeta de vista previa incluye el ID del caso y una descripción. - Vistas previas de vínculos a agentes de casos de asistencia, como
https://www.example.com/people/rosario-cruz
El chip inteligente muestra el ícono de una persona y la tarjeta de vista previa incluye el nombre, el correo electrónico, el cargo y la foto de perfil del empleado. - Si la configuración regional del usuario está configurada en español, el chip inteligente localiza su
labelText
en español.
Recurso de implementación
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"
}
]
}
}
}
Programa
Apps Script
Node.js
Python
Java
Recursos relacionados
- Prueba el complemento
- Objetos de eventos
- Cómo compilar interfaces de Editor
- Recurso de manifiesto del editor