Nesta página, explicamos como criar um complemento do Google Workspace que permite que os usuários do Documentos Google visualizem links de um serviço de terceiros.
Um complemento do Google Workspace pode detectar os links do serviço e solicitar que os usuários do Documentos Google visualizem esses links. É 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 os links em um arquivo do Documentos Google, os usuários interagem com ícones inteligentes e cards:
Quando os usuários digitam ou colam um URL em um documento, o 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, ele vê uma interface de card que mostra mais informações sobre o arquivo ou link.
O vídeo a seguir mostra como um usuário converte um link em um ícone inteligente e visualiza um cartão:
Pré-requisitos
Apps Script
- Uma conta do Google Workspace.
- Um complemento do Google Workspace Para criar um complemento, siga este guia de início rápido.
Node.js
- Uma conta do Google Workspace.
- Um complemento do Google Workspace Para criar um complemento, siga este guia de início rápido.
Python
- Uma conta do Google Workspace.
- Um complemento do Google Workspace Para criar um complemento, siga este guia de início rápido.
Java
- Uma conta do Google Workspace.
- Um complemento do Google Workspace Para criar um complemento, siga este guia de início rápido.
Opcional: configurar a autenticação em um serviço de terceiros
Se seu complemento se conectar a um serviço que exija autorização, os usuários precisarão se autenticar no serviço para visualizar os links. Isso significa que, quando os usuários colam um link do seu serviço em um documento do Documentos Google 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 seu complemento usando um ambiente de execução diferente, consulte Conectar seu complemento a um serviço de terceiros.
Configurar visualizações de links para seu complemento
Esta seção explica como configurar visualizações de links para seu complemento, incluindo as seguintes etapas:
- Configure as visualizações de link no recurso de implantação do complemento ou no arquivo de manifesto.
- Crie a interface de chip e cartão inteligente para seus links.
Configurar visualizações de links
Para configurar as visualizações de link, especifique as seguintes seções e campos no recurso de implantação do complemento ou no arquivo de manifesto:
- Na seção
addOns
, adicione o campodocs
para estender o Documentos Google. No campo
docs
, implemente o gatilholinkPreviewTriggers
que inclui umrunFunction
. Você define essa função na seção a seguir, Criar o chip inteligente e o cartão.Para saber quais campos podem ser especificados no acionador
linkPreviewTriggers
, consulte a documentação de referência para arquivos de manifesto do Apps Script ou 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 links em nome deles.
Como exemplo, consulte as seções oauthScopes
e addons
de um recurso de implantação que configura visualizações de links 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"
}
}
]
}
}
}
No exemplo, o complemento do Google Workspace visualiza links para o 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 corresponde a um dos padrões de URL em um documento do Documentos Google, a função de callback caseLinkPreview
cria e exibe um ícone e um cartão inteligentes.
Criar o chip e o cartão inteligentes
Para retornar um ícone e um cartão inteligentes de um link, implemente as funções
que você especificou no objeto linkPreviewTriggers
.
Quando um usuário interage com um link que corresponde a um padrão de URL especificado, o gatilho linkPreviewTriggers
é acionado e sua função de callback transmite o objeto de evento docs.matchedUrl.url
como um argumento. Use o payload desse objeto de evento para criar o ícone inteligente e o card da visualização do link.
Por exemplo, para um complemento que especifica o padrão de URL example.com/cases
, se um usuário visualizar o link https://www.example.com/cases/123456
, o payload de evento a seguir será retornado:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Para criar a interface do cartão, 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. Para uma lista de widgets e ações disponíveis, consulte Componentes compatíveis para cartões de visualização.
Para criar o ícone inteligente e o card e visualizar o link:
- Implemente a função especificada na seção
linkPreviewTriggers
do recurso de implantação do complemento ou do arquivo de manifesto:- A função precisa aceitar um objeto de evento que contenha
docs.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 as funções de callback usadas para fornecer
a interatividade do widget para a interface. Por exemplo, se você incluir um botão
na interface, ele precisará ter um
Action
anexado e uma função de callback implementada que será executada quando o botão for clicado.
O código a seguir cria a função de callback caseLinkPreview
:
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 para 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 e os perfis de funcionários de uma empresa.
O exemplo faz o seguinte:
- As visualizações vinculam a casos de suporte, como
https://www.example.com/support/cases/1234
. O ícone inteligente exibe um ícone de suporte, e o cartão de visualização inclui o ID do caso e uma descrição. - Visualiza links para agentes de caso de suporte, como
https://www.example.com/people/rosario-cruz
. O ícone inteligente exibe um ícone de pessoa, e o cartão de visualização inclui o nome, o e-mail, o cargo e a foto do perfil do funcionário. - Se a localidade do usuário estiver definida como espanhol, o chip inteligente localizará o
labelText
em espanhol.
Recurso de desenvolvimento
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"
}
]
}
}
}
Código
Apps Script
Node.js
Python
Java
Recursos relacionados
- Testar seu complemento
- Objetos de evento
- Como criar interfaces do Editor
- Recurso do manifesto do editor