Nesta página, explicamos como criar um complemento do Google Workspace que permite que os usuários dos Documentos 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 dos Documentos Google 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 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 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, uma interface de card com mais informações sobre o arquivo ou o link é mostrada.
O vídeo a seguir mostra como um usuário converte um link em um ícone inteligente e visualiza um card:
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 para 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 do Documentos Google pela primeira vez, o complemento precisa invocar o fluxo de autorização.
Para configurar um serviço OAuth ou um prompt de autorização personalizada, consulte um dos seguintes guias:
Se você criou seu complemento usando o Apps Script, consulte Como se conectar a serviços de terceiros 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 para seu complemento
Nesta seção, você verá 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 dos ícones e cards 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 seu complemento:
- Na seção
addOns
, adicione o campodocs
para estender os Documentos Google. No campo
docs
, implemente o gatilholinkPreviewTriggers
que inclui umrunFunction
. Você define essa função na seção 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 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 exibe 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 corresponde a um dos padrões de URL em um
documento do Documentos Google, a função de callback caseLinkPreview
cria e
mostra um ícone e um cartão inteligente.
Criar o ícone e o cartão inteligentes
Para retornar um ícone inteligente e card 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 docs.matchedUrl.url
como um argumento. Use o payload desse objeto de evento para criar o ícone inteligente e o card para a 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 seguinte payload de evento será retornado:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Para criar a interface do card, use widgets para mostrar informações sobre o link. Também é possível criar ações que permitem aos usuários abrir o link ou modificar o conteúdo dele. Para conferir uma lista de widgets e ações disponíveis, consulte Componentes compatíveis com cards de visualização.
Para criar o ícone e o card inteligentes de uma visualização de 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 contendo
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 contendo
- Para cada card de visualização, implemente qualquer função de callback que ofereça interatividade de widget para a interface. Por exemplo, se você incluir um botão com o texto "Link da visualização", poderá 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 de widget, consulte Ações de complementos.
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 oferecem suporte aos 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 visualiza links para os casos de suporte e perfis de funcionários de uma empresa.
O exemplo faz o seguinte:
- As visualizações estão vinculadas a casos de suporte, como
https://www.example.com/support/cases/1234
. O ícone inteligente exibe um ícone de suporte, e o card de visualização inclui o ID do caso e uma descrição. - Prévia de links para agentes do caso de suporte, como
https://www.example.com/people/rosario-cruz
. O ícone inteligente mostra um ícone de pessoa, e o card de visualização inclui o nome, e-mail, cargo e foto do perfil do funcionário. - Se a localidade do usuário estiver definida como espanhol, o ícone inteligente vai localizar o
labelText
para o espanhol.
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/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