Nesta página, explicamos como criar um complemento do Google Workspace que permite que os usuários dos apps Documentos, Planilhas e Apresentações Google visualizem links de um serviço de terceiros.
Um complemento do Google Workspace pode detectar os links do seu serviço e solicitar que os usuários os visualizem. É possível configurar um complemento para visualizar vários padrões de URL, como links para casos de suporte, leads de vendas e perfis de funcionários.
Como os usuários visualizam os links
Para visualizar links, os usuários interagem com ícones inteligentes e cards.
Quando os usuários digitam ou colam um URL em um documento, o app Documentos Google solicita que eles substituam o link por um ícone inteligente. O ícone inteligente exibe um ícone e um título curto ou uma descrição do conteúdo do link. Quando o usuário passa o cursor sobre o ícone, é exibida uma interface de card com mais informações sobre o arquivo ou o link.
O vídeo a seguir mostra como um usuário converte um link em um ícone inteligente e visualiza um card:
Como os usuários visualizam links no Planilhas e no Apresentações
Não é possível usar ícones inteligentes de terceiros nas visualizações de links nas Planilhas e Apresentações. Quando os usuários digitam ou colam um URL em uma planilha ou apresentação, o app Planilhas ou o Apresentações solicita que eles substituam o link pelo título como texto vinculado, em vez de um ícone. Quando o usuário passa o cursor sobre o título do link, é exibida uma interface de card com as informações sobre o link.
A imagem a seguir mostra como a visualização de um link é renderizada em Planilhas e Apresentações:
Pré-requisitos
Apps Script
- Uma conta do Google Workspace.
- Um complemento do Google Workspace. Para criar um complemento, siga este quickstart.
Node.js
- Uma conta do Google Workspace.
- Um complemento do Google Workspace. Para criar um complemento, siga este quickstart.
Python
- Uma conta do Google Workspace.
- Um complemento do Google Workspace. Para criar um complemento, siga este quickstart.
Java
- Uma conta do Google Workspace.
- Um complemento do Google Workspace. Para criar um complemento, siga este quickstart.
Opcional: configurar a autenticação em um serviço de terceiros
Se o complemento se conectar a um serviço que exige autorização, os usuários precisarão fazer a autenticação no serviço para visualizar os links. Isso significa que, quando os usuários colam um link do seu serviço em um arquivo dos Documentos, Planilhas ou Apresentações pela primeira vez, seu complemento precisa invocar o fluxo de autorização.
Para configurar um serviço OAuth ou uma solicitação de autorização personalizada, consulte um dos seguintes guias:
Se você criou o complemento usando o Apps Script, consulte Como se conectar a serviços que não são do Google usando um complemento do Google Workspace.
Se você criou o complemento usando um ambiente de execução diferente, consulte Conectar o complemento a um serviço de terceiros.
Configurar prévias de links do complemento
Esta seção explica como configurar visualizações de links para seu complemento, incluindo as seguintes etapas:
- Configure visualizações de links no recurso de implantação ou no arquivo de manifesto do seu complemento.
- Crie a interface de cards e ícones inteligentes para seus links.
Configurar visualizações de links
Para configurar visualizações de links, especifique as seguintes seções e campos no recurso de implantação ou no arquivo de manifesto do complemento:
- Na seção
addOns
, adicione o campodocs
para estender os Documentos Google, o camposheets
para estender as Planilhas e o camposlides
para estender as Apresentações. Em cada campo, implemente o gatilho
linkPreviewTriggers
que inclui umrunFunction
. Defina essa função na seção a seguir, Criar o ícone e o cartão inteligentes.Para saber mais sobre quais campos podem ser especificados no acionador
linkPreviewTriggers
, consulte a documentação de referência dos arquivos de manifesto do Apps Script ou dos recursos de implantação para outros ambientes de execução.No campo
oauthScopes
, adicione o escopohttps://www.googleapis.com/auth/workspace.linkpreview
para que os usuários possam autorizar o complemento a visualizar os links em nome deles.
Como exemplo, consulte a seção oauthScopes
e addons
do recurso de implantação a seguir, que configura visualizações de link para um serviço de caso de suporte.
{
"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"
}
}
]
}
}
}
No exemplo, o complemento do Google Workspace mostra os links do serviço de
caso de suporte de uma empresa. O complemento especifica três padrões de URL
para visualizar links. Sempre que um link corresponder a um dos padrões de URL, a função de callback caseLinkPreview
criará e exibirá um card e um ícone inteligente ou, no Planilhas e Apresentações, substituirá o URL pelo título do link.
Criar o ícone e o cartão inteligentes
Para retornar um ícone inteligente e um cartão de um link, implemente todas as funções
especificadas no objeto linkPreviewTriggers
.
Quando um usuário interage com um link que corresponde a um padrão de URL especificado, o
acionador linkPreviewTriggers
é disparado e a função de callback transmite o objeto
de evento EDITOR_NAME.matchedUrl.url
como um argumento. Use o payload desse objeto de evento para criar o ícone inteligente e o cartão da visualização do link.
Por exemplo, se um usuário visualizar o link https://www.example.com/cases/123456
no Documentos, o seguinte payload do evento será retornado:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Para criar a interface do card, use widgets para exibir informações sobre o link. Você também pode criar ações que permitam aos usuários abrir o link ou modificar o conteúdo dele. Para conferir uma lista dos widgets e ações disponíveis, consulte Componentes compatíveis com cards de visualização.
Para criar o ícone e o card inteligentes para a visualização de um link, faça o seguinte:
- Implemente a função especificada na seção
linkPreviewTriggers
do recurso de implantação ou arquivo de manifesto do complemento:- A função precisa aceitar um objeto de evento que contenha
EDITOR_NAME.matchedUrl.url
como argumento e retornar um único objetoCard
. - Se o serviço exigir autorização, a função também precisará invocar o fluxo de autorização.
- A função precisa aceitar um objeto de evento que contenha
- Para cada card de visualização, implemente todas as funções de callback que ofereçam interatividade de widget para a interface. Por exemplo, se você incluir um botão que diz "Visualizar link", será possível criar uma ação que especifique uma função de callback para abrir o link em uma nova janela. Para saber mais sobre as interações com o widget, consulte Ações de complementos.
O código a seguir cria a função de callback caseLinkPreview
para o Documentos Google:
Apps Script
Node.js
Python
Java
Componentes compatíveis com cards de visualização
Os complementos do Google Workspace são compatíveis com os seguintes widgets e ações em cards de visualização de links:
Apps Script
Campo "Card Service" | Tipo |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
IconImage |
Widget |
ButtonSet |
Widget |
TextButton |
Widget |
ImageButton |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Ação |
Navigation |
Ação Somente o método updateCard é compatível. |
JSON
Campo do cartão (google.apps.card.v1 ) |
Tipo |
---|---|
TextParagraph |
Widget |
DecoratedText |
Widget |
Image |
Widget |
Icon |
Widget |
ButtonList |
Widget |
Button |
Widget |
Grid |
Widget |
Divider |
Widget |
OpenLink |
Ação |
Navigation |
Ação Somente o método updateCard é compatível. |
Exemplo completo: complemento de caso de suporte
O exemplo a seguir apresenta um complemento do Google Workspace que exibe links para os casos de suporte de uma empresa nos Documentos Google.
O exemplo faz o seguinte:
- Prévia de links para casos de suporte, como
https://www.example.com/support/cases/1234
. O ícone inteligente mostra um ícone de suporte, e o card de visualização inclui o ID do caso e uma descrição. - Se a localidade do usuário estiver definida como espanhol, o ícone inteligente vai localizar o
labelText
para esse idioma.
Recurso de desenvolvimento
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"
}
]
}
}
}
Código
Apps Script
Node.js
Python
Java
Recursos relacionados
- Visualizar links do Google Livros com os ícones inteligentes
- Testar seu complemento
- Recurso de implantação do Documentos Google
- Interfaces do card para visualizações de link