Crie ícones inteligentes para visualização de links no Documentos Google

DEZ 19, 2023
Chanel Greco Developer Advocate Google Workspace

No início deste ano, anunciamos a disponibilidade geral de ícones inteligentes de terceiros no Documentos Google. Esse novo recurso permite adicionar, visualizar e interagir com informações críticas de apps de terceiros diretamente no Documentos Google. Vários parceiros, incluindo Asana, Atlassian, Figma, Loom, Miro, Tableau e Whimsical, já criaram ícones inteligentes para que os usuários possam começar a incorporar conteúdo de seus apps diretamente ao Documentos Google. Sourabh Choraria, Especialista do Google Developers para o Google Workspace e desenvolvedor por hobby, publicou uma solução de ícone inteligente de terceiros chamada "Link Previews" no Google Workspace Marketplace. Esse app adiciona informações ao Documentos Google a partir de várias ferramentas SaaS comumente usadas.

Nesta postagem do blog, você verá como criar seus próprios ícones inteligentes para o Documentos Google.

image1
Exemplo de um ícone inteligente que foi criado para visualizar informações de um sistema de gerenciamento de eventos

Como funcionam os ícones inteligentes de serviços de terceiros

Os ícones inteligentes de terceiros usam complementos do Google Workspace e podem ser publicados no Google Workspace Marketplace. A partir desse ponto, um administrador ou usuário pode instalar o complemento para que apareça na barra lateral da direita no Documentos Google.

O complemento do Google Workspace detecta os links de um serviço e solicita que os usuários do Documentos Google visualizem esses links. Isso significa que você pode criar ícones inteligentes para qualquer serviço que tenha um URL publicamente acessível. É possível configurar um complemento para visualizar vários padrões de URL, como links para casos de suporte, leads de vendas, perfis de funcionários e muito mais. Essa configuração é feita no arquivo de manifesto do complemento.

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/workspace.linkpreview",
    "https://www.googleapis.com/auth/script.external_request"
  ],
  "addOns": {
    "common": {
      "name": "Preview Books Add-on",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/library-icon.png",
      "layoutProperties": {
        "primaryColor": "#dd4b39"
      }
    },
    "docs": {
      "linkPreviewTriggers": [
        {
          "runFunction": "bookLinkPreview",
          "patterns": [
            {
              "hostPattern": "*.google.*",
              "pathPrefix": "books"
            },
            {
              "hostPattern": "*.google.*",
              "pathPrefix": "books/edition"
            }
          ],
          "labelText": "Book",
          "logoUrl": "https://developers.google.com/workspace/add-ons/images/book-icon.png",
          "localizedLabelText": {
            "es": "Libros"
          }
        }
      ]
    }
  }
}

O arquivo de manifesto contém o padrão de URL para a API do Google Livros

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 cartão que exibe uma prévia com mais informações sobre o arquivo ou link. É possível personalizar a interface do cartão que aparece quando o usuário passa o mouse sobre um ícone inteligente. Para criar a interface do cartão, são usados widgets para exibir informações sobre o link. Também é possível criar ações que permitam aos usuários abrir o link ou modificar seu conteúdo. Para obter uma lista de todos os componentes suportados para cartões de visualização, confira a documentação do desenvolvedor.

function getBook(id) {
// Code to fetch the data from the Google Books API
}
 
function bookLinkPreview(event) {
 if (event.docs.matchedUrl.url) {
// Through getBook(id) the relevant data is fetched and used to build the smart chip and card
 
    const previewHeader = CardService.newCardHeader()
      .setSubtitle('By ' + bookAuthors)
      .setTitle(bookTitle);
 
    const previewPages = CardService.newDecoratedText()
      .setTopLabel('Page count')
      .setText(bookPageCount);
 
    const previewDescription = CardService.newDecoratedText()
      .setTopLabel('About this book')
      .setText(bookDescription).setWrapText(true);
 
    const previewImage = CardService.newImage()
      .setAltText('Image of book cover')
      .setImageUrl(bookImage);
 
    const buttonBook = CardService.newTextButton()
      .setText('View book')
      .setOpenLink(CardService.newOpenLink()
        .setUrl(event.docs.matchedUrl.url));
 
    const cardSectionBook = CardService.newCardSection()
      .addWidget(previewImage)
      .addWidget(previewPages)
      .addWidget(CardService.newDivider())
      .addWidget(previewDescription)
      .addWidget(buttonBook);
 
    return CardService.newCardBuilder()
    .setHeader(previewHeader)
    .addSection(cardSectionBook)
    .build();
  }
}

Este é o código do script de apps para criar um ícone inteligente.

image2
Estado de um ícone inteligente ao passar o cursor. Os dados exibidos são obtidos do URL de postagem do blog do Google for Developers que foi colado pelo usuário.

Para obter um tutorial detalhado do código usado nessa postagem, confira o tutorial de exemplo Visualizar links do Google Livros com ícones inteligentes.

Como escolher a tecnologia para o complemento

Ao criar ícones inteligentes para visualização de links, você pode escolher entre duas tecnologias diferentes para criar o complemento: Google Apps Script ou um ambiente de execução alternativo.

O Apps Script é uma plataforma de desenvolvimento rápido de aplicativos integrada ao Google Workspace. Por esse motivo, o Apps Script é uma boa opção para prototipar e validar uma solução de ícone inteligente, pois não requer um ambiente de desenvolvimento preexistente. Mas o Apps Script não é usado apenas para prototipagem, pois alguns desenvolvedores optam por criar o complemento do Google Workspace com ele e até mesmo publicá-lo no Google Workspace Marketplace para que os usuários possam fazer a instalação.

Se você quiser criar seu ícone inteligente com o Apps Script, confira o vídeo abaixo, no qual aprenderá a criar um ícone inteligente para visualização de links no Documentos Google do início ao fim. Quer o código usado no tutorial em vídeo? Então confira a página de exemplo Visualizar links do Google Livros com ícones inteligentes.

Link to Youtube Video (visible only when JS is disabled)

Se você preferir criar o complemento do Google Workspace usando seu próprio ambiente de desenvolvimento, sua linguagem de programação, sua hospedagem, seus pacotes etc., então o ambiente de execução alternativo será a escolha certa. Você pode escolher entre diferentes linguagens de programação, como Node.js, Java, Python e muito mais. A hospedagem do código do ambiente de execução do complemento pode estar em qualquer nuvem ou infraestrutura local, desde que esse código possa ser exposto como um endpoint HTTP(S) público. Para saber mais sobre como criar ícones inteligentes usando ambientes de execução alternativos, confira a documentação do desenvolvedor.

Como compartilhar o complemento com outras pessoas

Você pode compartilhar o complemento com outras pessoas no Google Workspace Marketplace. Digamos que você queira disponibilizar sua solução de ícone inteligente para sua equipe. Nesse caso, será possível publicar o complemento na organização do Google Workspace, também conhecida como app particular. Por outro lado, para compartilhar o complemento com alguém que tenha uma conta do Google, você poderá publicá-lo como um app público.

Para saber mais sobre como publicar no Google Workspace Marketplace, assista a este vídeo que orientará você durante o processo.

Primeiros passos

Saiba mais sobre como criar ícones inteligentes para visualização de links na documentação do desenvolvedor. Lá você encontrará mais informações e exemplos de código para basear sua solução. Mal podemos esperar para ver quais soluções de ícones inteligentes você criará.