En esta página, se explica cómo compilar un complemento de Google Workspace que permita a los usuarios de Documentos, Hojas de cálculo y Presentaciones 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 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 ventas y perfiles de empleados.
Cómo pueden los usuarios obtener una vista previa de los vínculos
Para obtener una vista previa de los vínculos, los usuarios interactúan con chips inteligentes y tarjetas.
Cuando los usuarios escriben o pegan una URL en un documento, Documentos de Google les solicita 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 coloca el cursor sobre el chip, ve una interfaz de tarjeta con una vista previa de más información sobre el archivo o 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:
Cómo los usuarios obtienen una vista previa de los vínculos en Hojas de cálculo y Presentaciones
Los chips inteligentes de terceros no son compatibles con las vistas previas de vínculos en Hojas de cálculo y Presentaciones. Cuando los usuarios escriben o pegan una URL en una hoja de cálculo o presentación, Hojas de cálculo o Presentaciones les solicitará que reemplacen el vínculo por su título como texto vinculado en lugar de un chip. Cuando el usuario coloca el cursor sobre el título del vínculo, ve una interfaz de tarjeta con una vista previa de la información del vínculo.
En la siguiente imagen, se muestra cómo se renderiza una vista previa de vínculos en Hojas de cálculo y Presentaciones:
Requisitos previos
Apps Script
- Una cuenta de Google Workspace
- Un complemento de Google Workspace Para compilar un complemento, sigue esta quickstart.
Node.js
- Una cuenta de Google Workspace
- Un complemento de Google Workspace Para compilar un complemento, sigue esta quickstart.
Python
- Una cuenta de Google Workspace
- Un complemento de Google Workspace Para compilar un complemento, sigue esta quickstart.
Java
- Una cuenta de Google Workspace
- Un complemento de Google Workspace Para compilar un complemento, sigue esta quickstart.
Opcional: Configura la autenticación en un servicio de terceros
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 archivo de Documentos, Hojas de cálculo o Presentaciones por primera vez, el complemento debe invocar el flujo de autorización.
Para configurar un servicio de OAuth o un mensaje de autorización personalizada, consulta una de las siguientes guías:
Si compilaste tu complemento con Apps Script, consulta Cómo conectarse a servicios ajenos a 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, lo que incluye los siguientes pasos:
- Configura las vistas previas de vínculos en el recurso de implementación o en el archivo de manifiesto de tu complemento.
- Compila la interfaz de tarjetas y chips inteligentes para tus vínculos.
Cómo configurar las vistas previas de vínculos
Para configurar las vistas previas de vínculos, especifica las siguientes secciones y campos en el recurso de implementación o en el archivo de manifiesto de tu complemento:
- En la sección
addOns
, agrega el campodocs
para extender Documentos, el camposheets
para extender Hojas de cálculo y el camposlides
para extender Presentaciones. En cada campo, implementa el activador
linkPreviewTriggers
que incluye unrunFunction
(la función se define en la siguiente sección, Cómo compilar el chip inteligente y la tarjeta).Para obtener información sobre qué campos puedes especificar en el activador
linkPreviewTriggers
, consulta la documentación de referencia sobre 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 alcancehttps://www.googleapis.com/auth/workspace.linkpreview
para que los usuarios puedan autorizar el complemento y obtener una vista previa de los vínculos en su nombre.
A modo de ejemplo, consulta la sección oauthScopes
y addons
del siguiente recurso de implementación que configura las 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"
}
}
]
},
"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"
}
}
]
}
}
}
En el ejemplo, el complemento de Google Workspace ofrece una vista previa de los vínculos del servicio de casos de asistencia de una empresa. El complemento especifica tres patrones de URL para obtener una vista previa de los vínculos. Cuando un vínculo coincide con uno de los patrones de URL, la
función de devolución de llamada caseLinkPreview
compila y
muestra una tarjeta y un chip inteligente, o bien en Hojas de cálculo y
Presentaciones, reemplaza la URL con el
título del vínculo.
Crea el chip inteligente y la tarjeta
Si quieres mostrar un chip inteligente y una tarjeta para un vínculo, debes implementar las funciones
que especificaste en el objeto linkPreviewTriggers
.
Cuando un usuario interactúa con un vínculo que coincide con un patrón de URL específico, se activa el activador linkPreviewTriggers
y su función de devolución de llamada pasa el objeto de evento EDITOR_NAME.matchedUrl.url
como argumento. Usa la carga útil de este objeto de evento para compilar el chip inteligente y la tarjeta para la vista previa del vínculo.
Por ejemplo, si un usuario obtiene una vista previa del vínculo https://www.example.com/cases/123456
en Documentos, se muestra la siguiente carga útil de evento:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Para crear la interfaz de la tarjeta, usa widgets que muestren información sobre el vínculo. También puedes crear acciones que 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 para tarjetas de vista previa.
Si quieres compilar el chip inteligente y la tarjeta para obtener una vista previa del vínculo, haz lo siguiente:
- Implementa la función que especificaste en la sección
linkPreviewTriggers
del recurso de implementación o el archivo del manifiesto de tu complemento:- La función debe aceptar un objeto de evento que contenga
EDITOR_NAME.matchedUrl.url
como argumento y mostrar un solo objetoCard
. - Si el 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
- Para cada tarjeta de vista previa, implementa cualquier función de devolución de llamada que proporcione interactividad del widget para la interfaz. Por ejemplo, si incluyes un botón que dice "Ver vínculo", puedes crear una acción que especifique una función de devolución de llamada para abrir el vínculo en una ventana nueva. Para obtener más información sobre las interacciones del widget, consulta Acciones de complementos.
El siguiente código crea la función de devolución de llamada caseLinkPreview
para Documentos:
Apps Script
Node.js
Python
Java
Componentes compatibles para tarjetas de vista previa
Los complementos de Google Workspace admiten los siguientes widgets y acciones para tarjetas de vista previa de vínculos:
Apps Script
Campo del Servicio de tarjetas | 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 con una vista previa de los vínculos a los casos de asistencia de una empresa en Documentos de Google.
En el ejemplo, se realizan las acciones siguientes:
- Obtén una vista previa de los vínculos a 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. - Si la configuración regional del usuario está establecida en español, el chip inteligente localiza su
labelText
al español.
Recurso de implementación
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"
}
]
}
}
}
Escribe código
Apps Script
Node.js
Python
Java
Recursos relacionados
- Obtén una vista previa de vínculos de Google Libros con chips inteligentes
- Prueba tu complemento
- Recurso de implementación de Documentos de Google
- Interfaces de tarjetas para las vistas previas de vínculos