Objetos de evento

Esta página descreve a estrutura dos objetos de eventos dos complementos do Google Workspace.

Os objetos de evento são estruturas JSON que são construídas automaticamente e transmitidas como parâmetros para acionar ou chamar funções quando um usuário interage com um complemento. Os objetos de evento carregam informações do lado do cliente sobre o app host e o contexto atual para a função de callback do complemento do lado do servidor.

Os complementos do Google Workspace usam objetos de evento nos seguintes lugares:

• Acionadores da página inicial. Todas as funções homepageTrigger definidas são transmitidas automaticamente a um objeto de evento quando a função de gatilho da página inicial é disparada. É possível usar esse objeto na função de acionamento da página inicial para identificar o app host ativo, a plataforma do cliente, o local do usuário e outras informações.

  Os objetos de evento criados quando os gatilhos da página inicial são acionados não contêm todos os campos incluídos nos outros dois casos. Os campos relacionados a widgets e informações contextuais são omitidos.

• Acionadores contextuais. Cada aplicativo host fornece um conjunto diferente de acionadores contextuais que são acionados quando o usuário entra em um contexto específico. Exemplo:

  • O Gmail fornece um gatilho contextual para quando um usuário abre uma mensagem e outro quando um usuário compõe uma mensagem.
  • O Google Agenda oferece um acionador contextual para quando um usuário abre um evento.
  • O Google Drive oferece um acionador contextual para quando um usuário seleciona arquivos do Drive.

  Quando um gatilho contextual é acionado, o aplicativo host chama o runFunction correspondente listado no manifesto do complemento, transmitindo um objeto de evento como parâmetro. Os objetos de evento criados quando os acionadores contextuais são acionados contêm todos os campos incluídos nos objetos de evento de gatilho da página inicial, além de campos com informações contextuais.

• Ações do widget. Os objetos de evento também são usados para fornecer interatividade do widget, usando o mesmo modelo de ação que os complementos do Gmail usam. Os complementos do Google Workspace usam as mesmas funções de gerenciador de widgets, objetos Action e respostas de ação. No entanto, nos complementos do Google Workspace, os objetos de eventos de ação incluem ainda mais informações que uma função de callback pode usar.

  Os objetos de evento criados como resultado das ações do widget contêm todos os campos incluídos nos objetos de evento de gatilho contextual, além de campos com informações do widget.

• Acessar acionadores de links de visualização. Nos apps Documentos, Planilhas e Apresentações Google, é possível configurar visualizações de links para serviços de terceiros com base em padrões de URL específicos. Quando os usuários interagem com um link que atende ao padrão, o linkPreviewTriggers é acionado e um objeto de evento que contém o link é transmitido para a função de callback do acionador. Seu complemento pode usar esse objeto de evento para criar um ícone inteligente e um card que mostram informações sobre o link no aplicativo host. Também é possível criar ações de widgets para permitir que os usuários interajam com o card de visualização e o conteúdo dele.

• Acionadores do app Google Chat (prévia para desenvolvedores). No Google Chat, seu complemento aparece para os usuários como um app do Chat, e eles podem interagir com ele adicionando-o a espaços, enviando mensagens, usando comandos de barra e mais. Para criar recursos interativos, você configura e usa vários gatilhos do app Chat. Cada acionador envia um payload de objeto de evento diferente que ajuda a processar ou responder a cada tipo de interação.

Estrutura do objeto de evento

A tabela a seguir descreve a estrutura de nível superior dos objetos de eventos dos complementos do Google Workspace. A estrutura do objeto de evento inclui um campo de nível superior commonEventObject para informações independentes do host. Cada objeto de evento também pode ter um dos seguintes campos de nível superior específicos do host, determinado pelo app host ativo: gmailEventObject, calendarEventObject ou driveEventObject.

Para compatibilidade com versões anteriores, os objetos de eventos de complementos do Google Workspace também incluem todos os campos originais usados nos objetos de eventos de ação de complementos do Gmail. Esses campos estão listados na tabela abaixo em "Campos do complemento original do Gmail". As informações nesses campos são reproduzidas na nova estrutura de objetos.

Objeto de evento comum

O objeto de evento comum é a parte do objeto de evento geral que carrega informações gerais e independentes do host para o complemento do cliente do usuário. Essas informações incluem detalhes como a localidade do usuário, o app host e a plataforma.

Além dos acionadores contextuais e da página inicial, os complementos criam e transmitem objetos de evento para funções de callback de ação quando o usuário interage com widgets. A função de callback do seu complemento pode consultar o objeto de evento comum para determinar o conteúdo dos widgets abertos no cliente do usuário. Por exemplo, o complemento pode localizar o texto que um usuário inseriu em um widget TextInput no objeto eventObject.commentEventObject.formInputs.

Entradas do formulário do seletor de data e hora

As funções de callback de ação podem receber os valores atuais do widget no campo commonEventObject.formInputs. Isso inclui os valores de data ou hora selecionados do usuário nos widgets de seleção de data ou hora. No entanto, a estrutura das informações varia de acordo com a configuração do widget como um seletor de data e hora, um seletor de data ou um seletor de hora. As diferenças estruturais são descritas na tabela a seguir:

Objeto de evento do Chat

O objeto do evento do Chat é a parte do objeto do evento geral que contém informações sobre as interações de um usuário com um app do Chat. Ele só está presente em um objeto do evento se o complemento estender o Google Chat.

Payload

Dependendo do tipo de interação do app de chat, o evento contém um payload com um ou mais recursos da API Chat.

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}