Objetos de evento

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

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

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

• Acionadores da página inicial. Cada função homepageTrigger definida recebe automaticamente um objeto de evento quando a função de gatilho da página inicial é disparada. Você pode usar esse objeto na função de acionamento da página inicial para identificar o app host ativo, a plataforma do cliente, a localidade 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 ativados quando o usuário entra em um contexto específico. Exemplo:

  • O Gmail oferece um gatilho contextual quando um usuário abre uma mensagem e outro quando ele escreve uma mensagem.
  • O Google Agenda oferece um gatilho contextual quando um usuário abre um evento.
  • O Google Drive oferece um acionador contextual 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 um parâmetro. Os objetos de evento criados quando os acionadores contextuais são disparados contêm todos os campos incluídos nos objetos de evento de acionador 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 de widget, usando o mesmo modelo de ação que os complementos do Gmail usam. Os complementos do Google Workspace usam todas as mesmas funções de manipulador de widgets, objetos Action e respostas de ação. No entanto, nos complementos do Google Workspace, os objetos de evento 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 acionamento contextual, além de campos com informações do widget.

• Acionadores de link 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 é disparado, e um objeto de evento que contém o link é transmitido para a função de callback do gatilho. 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. Você também pode criar ações de widget para permitir que os usuários interajam com o card de prévia e o conteúdo dele.

• Gatilhos do app Google Chat. No Google Chat, seu complemento aparece para os usuários como um app do Chat, e eles podem interagir com ele adicionando a espaços, enviando mensagens, usando comandos de barra e muito mais. Para criar recursos interativos, configure e use vários gatilhos do app Chat. Cada gatilho envia um payload de objeto de evento diferente que ajuda você 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 evento de 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, determinados pelo app host ativo: gmailEventObject, calendarEventObject ou driveEventObject.

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

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, o app host e a plataforma do usuário.

Além da página inicial e dos gatilhos contextuais, 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 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 de 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 pelo usuário em widgets de seleção de data ou hora. No entanto, a estrutura das informações varia dependendo de se o widget foi configurado como um seletor de data e hora, um seletor somente de data ou um seletor somente de hora. As diferenças estruturais estão descritas na tabela a seguir:

Objeto de evento do chat

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

Payload

Dependendo do tipo de interação do app do 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"
  }
}