Nesta página, descrevemos a estrutura dos objetos de evento de complementos do Google Workspace.
Objetos de evento são estruturas JSON que são construídas e transmitidas automaticamente como parâmetros para acionar ou acionar 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 locais:
Acionadores da página inicial. Cada função
homepageTrigger
definida é transmitida automaticamente a um objeto de evento quando a função de acionamento 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, a localidade do usuário e outras informações.Os objetos de evento criados quando os acionadores de página inicial são disparados não contêm todos os campos incluídos nos outros dois casos. Os campos pertencentes a widgets e informações contextuais são omitidos.
Acionadores contextuais. Cada aplicativo host fornece um conjunto diferente de acionadores contextuais que são disparados quando o usuário insere um contexto específico. Por exemplo:
- O Gmail fornece um acionador contextual para quando um usuário abrir uma mensagem e outro quando um usuário escrever uma mensagem.
- O Google Agenda fornece um acionador contextual para quando um usuário abrir um evento.
- O Google Drive fornece um acionador contextual para quando um usuário seleciona arquivos do Google Drive.
Quando um acionador contextual é disparado, o aplicativo host chama o
runFunction
correspondente listado no manifesto do complemento, passando um objeto de evento como um parâmetro. Os objetos de evento criados quando os acionadores de contexto são disparados contêm todos os campos incluídos nos objetos de evento de acionador da página inicial, além dos campos que contêm 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 usado pelos complementos do Gmail. 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 evento de ação incluem ainda mais informações sobre as quais uma função de callback pode agir.Os objetos de evento criados como resultado das ações do widget contêm todos os campos incluídos nos objetos de evento de acionador contextual e os campos que contêm informações do widget.
Acionadores de link de visualização (Visualização do desenvolvedor). No Documentos 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
previewLinkTrigger
é acionado, 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 e um cartão inteligente que exibem 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 cartão de visualização e o conteúdo dele.
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 de complementos do Google Workspace também incluem todos os campos originais usados em objetos de evento de ação de complemento do Gmail. Esses campos são listados na tabela abaixo, em "Campos complementares originais do Gmail". As informações neles são reproduzidas em uma nova estrutura de objetos.
Objeto de evento | |
---|---|
eventObject.commonEventObject |
Common fields object
Um objeto que contém informações comuns a todos os objetos de evento, independentemente do aplicativo host. |
eventObject.calendar |
Calendar event object
Disponível apenas se o organizador da chamada for o Google Agenda. Um objeto que contém informações da agenda e do evento. |
eventObject.drive |
Drive event object
Disponível apenas se o organizador da chamada for o Google Drive. Um objeto que contém informações do Drive. |
eventObject.gmail |
Gmail event object
Disponível apenas se o host de chamada for o Gmail. Um objeto que contém informações do Gmail. |
eventObject.docs |
Docs event object
Disponível apenas se o organizador da chamada for o Documentos Google. Um objeto que contém informações sobre documentos. |
eventObject.sheets |
Sheets event object
Disponível apenas se o organizador da chamada for o Planilhas Google. Um objeto que contém informações do Planilhas. |
eventObject.slides |
Slides event object
Disponível apenas se o organizador da chamada for um arquivo do Apresentações Google. Objeto que contém informações do Apresentações. |
Campos adicionais do Gmail | |
eventObject.messageMetadata.accessToken |
string Obsoleto. Um token de acesso. Você pode usá-lo para ativar o acesso aos dados do usuário usando escopos complementares do Gmail.
Para complementos do Google Workspace, encontre essas informações no campo
|
eventObject.messageMetadata.messageId |
string Obsoleto. O código da mensagem da conversa é aberto na IU do Gmail.
Para complementos do Google Workspace, encontre essas informações no campo
|
eventObject.clientPlatform |
string Obsoleto. Indica a origem do evento (Web, iOS ou Android).
Para complementos do Google Workspace, encontre essas informações no campo
|
eventObject.formInput |
object Obsoleto. Um mapa dos valores atuais de todos os widgets de formulário no cartão, restrito a um valor por widget. As chaves são os IDs das strings associadas aos widgets, e os valores são as strings. O objeto de evento fornece formInput como uma conveniência para quando você precisa ler dados de vários widgets com valores singulares esperados, como entradas de texto e interruptores. Para widgets de vários valores, como caixas de seleção, é possível ler cada valor de formInputs .
Para complementos do Google Workspace, encontre essas informações no campo
|
eventObject.formInputs |
object Obsoleto. Um mapa de valores atuais de widgets no cartão, apresentado como listas de strings. As chaves são os códigos de string associados ao widget. Para widgets de valor único, o valor é apresentado em uma matriz de elemento único. Para widgets de vários valores, como grupos de caixas de seleção, todos os valores são apresentados em uma lista.
Para complementos do Google Workspace, encontre essas informações no campo
|
eventObject.parameters |
object Obsoleto. Um mapa dos parâmetros adicionais que você fornece ao Action usando
Action.setParameters() . As chaves e os valores do mapa são strings.
Para complementos do Google Workspace, encontre essas informações no campo
|
eventObject.userCountry |
string Obsoleto e desativado por padrão. O código de duas letras que indica o país ou a região do usuário. Também pode ser um código numérico de país UN M49.
Para complementos do Google Workspace, encontre essas informações no campo
|
eventObject.userLocale |
string Obsoleto e desativado por padrão. O código ISO 639 de duas letras que indica o idioma do usuário. Consulte Como acessar a localidade e o fuso horário do usuário para mais detalhes.
Para complementos do Google Workspace, encontre essas informações no campo
|
eventObject.userTimezone.id |
string Obsoleto e desativado por padrão. O identificador de fuso horário do fuso horário do usuário. Por exemplo: America/New_York , Europe/Vienna e Asia/Seoul . Consulte
Como acessar a localidade e o fuso horário do usuário para mais detalhes.
Para complementos do Google Workspace, encontre essas informações no campo
|
eventObject.userTimezone.offset |
string Obsoleto e desativado por padrão. O ajuste de horário em relação ao Tempo Universal Coordenado (UTC, na sigla em inglês) do fuso horário do usuário, medido em milissegundos. Consulte Como acessar a localidade e o fuso horário do usuário para mais detalhes.
Para complementos do Google Workspace, encontre essas informações no campo
|
Objeto de evento comum
O objeto de evento comum é a parte do objeto de evento geral que transporta 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 da página inicial e contextual, 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, seu complemento pode localizar o texto que um usuário digitou em um
widget TextInput
no
objeto eventObject.commentEventObject.formInputs
.
Campos comuns do objeto de evento | |
---|---|
commonEventObject.platform |
string Indica onde o evento se origina ("WEB", "IOS" ou "ANDROID"). |
commonEventObject.formInputs |
object Um mapa que contém os valores atuais dos widgets no card exibido. As chaves do mapa são os IDs de string atribuídos a cada widget. A estrutura do objeto de valor do mapa depende do tipo de widget:
|
commonEventObject.hostApp |
string Indica o app host em que o complemento está ativo quando o objeto de evento é gerado. Os valores possíveis incluem:
|
commonEventObject.parameters |
object Todos os parâmetros adicionais fornecidos ao
Action usando
Action.setParameters() .
|
commonEventObject.userLocale |
string Desativado por padrão. O idioma do usuário e o identificador do país/região no formato do código de idioma ISO 639 (código do país/região ISO 3166). Por exemplo, en-US .
Para ativar esse campo, defina |
commonEventObject.timeZone |
string Desativado por padrão. O ID do fuso horário e o deslocamento. Para ativar esse campo, defina addOns.common.useLocaleFromApp como true no manifesto do complemento.
A lista de escopo do complemento também precisa incluir https://www.googleapis.com/auth/script.locale .
Consulte
Como acessar a localidade e o fuso horário do usuário para mais detalhes.
|
commonEventObject.timeZone.id |
string O identificador de fuso horário do fuso horário do usuário. Por exemplo: America/New_York , Europe/Vienna e Asia/Seoul . Para ativar esse campo, defina addOns.common.useLocaleFromApp como true no manifesto do complemento.
A lista de escopo do complemento também precisa incluir https://www.googleapis.com/auth/script.locale . Consulte
Como acessar a localidade e o fuso horário do usuário para mais detalhes.
|
commonEventObject.timeZone.offset |
string O ajuste de horário do fuso horário universal do usuário (UTC) do fuso horário do usuário, medido em milissegundos. Consulte Como acessar a localidade e o fuso horário do usuário para mais detalhes. |
Entradas de formulário do seletor de data e hora
As funções de callback de ação podem receber valores de widget atuais no campo commonEventObject.formInputs
.
Isso inclui os valores de data ou hora selecionados pelo usuário nos widgets de seletor de data ou hora.
No entanto, a estrutura das informações varia dependendo se o widget foi configurado como um seletor de data e hora, um seletor de data ou um seletor de somente tempo. As diferenças estruturais estão descritas na tabela a seguir:
Objeto de evento do Agenda
O objeto de evento do Agenda é a parte do objeto de evento geral que carrega informações sobre a agenda do usuário e os eventos da agenda. Ele só estará presente em um objeto de evento se o aplicativo host for o Google Agenda.
A tabela a seguir lista os campos presentes no campo calendarEventObject
de um objeto de evento. Os campos marcados como Dados gerados pelo usuário estarão presentes no objeto de evento somente se os dados estiverem presentes no evento do Agenda e o complemento definir o campo addOns.calendar.currentEventAccess
manifesto como READ
ou READ_WRITE
.
Objeto de evento do Agenda | |
---|---|
calendar.attendees[] |
list of attendee objects Dados gerados pelo usuário. Uma lista dos participantes do evento da agenda. |
calendar.calendarId |
string O ID da agenda. |
calendar.capabilities |
object Dados gerados pelo usuário. Um objeto que descreve os recursos do complemento para visualizar ou atualizar informações de eventos. |
calendar.capabilities.canAddAttendees |
boolean Dados gerados pelo usuário. true se o complemento puder adicionar novos participantes à lista de participantes do evento. Caso contrário, false . |
calendar.capabilities.canSeeAttendees |
boolean Dados gerados pelo usuário. true se o complemento puder ler a lista de participantes do evento. Caso contrário, false . |
calendar.capabilities.canSeeConferenceData |
boolean Dados gerados pelo usuário. true
se o complemento puder ler os dados da conferência do evento. Caso contrário,
false . |
calendar.capabilities.canSetConferenceData |
boolean Dados gerados pelo usuário. true se o complemento puder atualizar os dados da conferência do evento. Caso contrário, false . |
calendar.capabilities.canAddAttachments |
boolean Dados gerados pelo usuário. true se o complemento puder adicionar novos anexos ao evento. Caso contrário, false .
|
calendar.conferenceData |
Conference data object Dados gerados pelo usuário. Um objeto que representa os dados de videoconferência associados a este evento, como os detalhes da videoconferência do Google Meet. |
calendar.id |
string O ID do evento. |
calendar.organizer |
object Um objeto que representa o organizador do evento. |
calendar.organizer.email |
string O endereço de e-mail do organizador do evento. |
calendar.recurringEventId |
string O ID de um evento recorrente. |
Participante
Os objetos dos convidados carregam informações sobre os participantes individuais dos eventos do Google Agenda. Essas informações estarão presentes no objeto de evento apenas se os dados estiverem presentes no evento do Agenda e o complemento definir o campo addOns.calendar.currentEventAccess
manifesto como READ
ou READ_WRITE
.
Objeto de participante | |
---|---|
attendee.additionalGuests |
number O número de convidados adicionais que o participante indicou que vai levar. Assume zero como padrão. |
attendee.comment |
string O comentário da resposta do participante, se houver. |
attendee.displayName |
string O nome exibido pelo participante. |
attendee.email |
string O endereço de e-mail do participante. |
attendee.optional |
boolean true se a participação deste participante estiver marcada como opcional. Caso contrário, false .
|
attendee.organizer |
boolean true se o participante for um organizador deste evento.
|
attendee.resource |
boolean true se o participante representar um
recurso, como sala ou equipamento. Caso contrário,
false .
|
attendee.responseStatus |
string O status da resposta do participante. Os valores possíveis incluem:
|
attendee.self |
boolean true se o convidado representar a agenda em que o evento aparece. Caso contrário, será false .
|
Dados da conferência
Os objetos de dados de conferência contêm informações sobre conferências anexadas a eventos do Google Agenda. Podem ser soluções de videoconferência do Google, como o Google Meet, ou conferências de terceiros. Essas informações estarão presentes no objeto de evento apenas se os dados estiverem presentes no evento do Agenda e o complemento definir o campo addOns.calendar.currentEventAccess
manifesto como READ
ou READ_WRITE
.
Objeto de dados de conferência | |
---|---|
conferenceData.conferenceId |
string O ID da conferência. Esse ID permite que os aplicativos acompanhem as videoconferências. Não mostre esse ID aos usuários. |
conferenceData.conferenceSolution |
object Um objeto que representa a solução de conferência, como o Hangouts ou o Google Meet. |
conferenceData.conferenceSolution.iconUri |
string O URI do ícone visível ao usuário que representa esta solução de conferência. |
conferenceData.conferenceSolution.key |
object A chave que identifica exclusivamente a solução de conferência para esse evento. |
conferenceData.conferenceSolution.key.type |
string O tipo de solução de conferência. Os valores possíveis incluem:
|
conferenceData.conferenceSolution.name |
string O nome visível desta solução de conferência (não localizado) para o usuário. |
conferenceData.entryPoints[] |
list of entry point objects
A lista de pontos de entrada da conferência, como URLs ou números de telefone. |
conferenceData.notes |
string Observações adicionais (como instruções do administrador do domínio ou avisos legais) sobre a videoconferência a serem exibidas ao usuário. Pode conter HTML. O tamanho máximo é de 2.048 caracteres. |
conferenceData.parameters |
object Um objeto que contém um mapa de dados de parâmetros definidos para serem usados pelo complemento. |
conferenceData.parameters.addOnParameters |
object Um mapa de chaves e valores de string de parâmetro. Essas chaves e valores são definidos pelo desenvolvedor do complemento para anexar informações a uma conferência específica para uso do complemento. |
Ponto de entrada
Os objetos de ponto de entrada carregam informações sobre os meios estabelecidos para acessar uma determinada conferência, como por telefone ou vídeo. Essas informações estarão presentes no objeto de evento apenas se os dados estiverem presentes no evento do Agenda e o complemento definir o campo manifesto addOns.calendar.currentEventAccess
como READ
ou READ_WRITE
.
Objeto do ponto de entrada | |
---|---|
entryPoint.accessCode |
string O código de acesso usado para acessar a conferência. O tamanho máximo é de 128 caracteres. Normalmente, os provedores de videoconferência usam apenas um subconjunto de { accessCode , meetingCode , passcode , password , pin } para fornecer acesso às conferências. Faça a correspondência e exiba apenas os campos usados pelo provedor da conferência.
|
entryPoint.entryPointFeatures |
list Recursos do ponto de entrada. Atualmente, esses recursos se aplicam somente a pontos de entrada phone :
|
entryPoint.entryPointType |
string O tipo de ponto de entrada. Os valores possíveis são os seguintes:
|
entryPoint.label |
string O rótulo visível ao usuário para o URI do ponto de entrada (não localizado). |
entryPoint.meetingCode |
string O código da reunião usado para acessar a conferência. O tamanho máximo é de 128 caracteres. Normalmente, os provedores de videoconferência usam apenas um subconjunto de { accessCode , meetingCode , passcode , password , pin } para fornecer acesso às conferências. Faça a correspondência e exiba apenas os campos usados pelo provedor da conferência.
|
entryPoint.passcode |
string A senha usada para acessar a conferência. O tamanho máximo é de 128 caracteres. Normalmente, os provedores de videoconferência usam apenas um subconjunto de { accessCode , meetingCode , passcode , password , pin } para fornecer acesso às conferências. Faça a correspondência e exiba apenas os campos usados pelo provedor da conferência.
|
entryPoint.password |
string A senha usada para acessar a conferência. O tamanho máximo é de 128 caracteres. Normalmente, os provedores de videoconferência usam apenas um subconjunto de { accessCode , meetingCode , passcode , password , pin } para fornecer acesso às conferências. Faça a correspondência e exiba apenas os campos usados pelo provedor da conferência.
|
entryPoint.pin |
string O PIN usado para acessar a conferência. O tamanho máximo é de 128 caracteres. Normalmente, os provedores de videoconferência usam apenas um subconjunto de { accessCode , meetingCode , passcode , password , pin } para fornecer acesso às conferências. Faça a correspondência e exiba apenas os campos usados pelo provedor da conferência.
|
entryPoint.regionCode |
string Código regional do número de telefone. Necessário por usuários se o URI não incluir um código de país. Os valores são baseados na lista pública de códigos de região CLDR (em inglês). |
entryPoint.uri |
string O URI do ponto de entrada. O tamanho máximo é de 1.300 caracteres. A formatação depende do tipo de ponto de entrada:
|
Objeto de evento do Drive
O objeto de evento do Google Drive é a parte do objeto de evento geral que carrega informações sobre o Google Drive de um usuário e seu conteúdo. Ele só estará presente em um objeto de evento se o aplicativo host for o Google Drive.
Objeto de evento do Drive | |
---|---|
drive.activeCursorItem |
Drive item object O item do Drive está ativo no momento. |
drive.selectedItems[] |
list of Drive item objects Uma lista de itens (arquivos ou pastas) selecionados no Drive. |
Item do Drive
Os objetos de itens do Drive contêm informações sobre itens específicos do Drive, como arquivos ou pastas.
Objeto do item do Drive | |
---|---|
item.addonHasFileScopePermission |
boolean Se true , o complemento solicitou e recebeu autorização de escopo https://www.googleapis.com/auth/drive.file para esse item. Caso contrário, esse campo será false .
|
item.id |
string O ID do item selecionado. |
item.iconUrl |
string O URL do ícone que representa o item selecionado. |
item.mimeType |
string O tipo MIME do item selecionado. |
item.title |
string O título do item selecionado. |
Objeto de evento do Gmail
O objeto de evento do Gmail é a parte do objeto de evento geral que transporta informações sobre as mensagens do Gmail de um usuário. Ele só estará presente em um objeto de evento se o aplicativo host for o Gmail.
Objeto de evento do Gmail | |
---|---|
gmail.accessToken |
string O token de acesso específico do Gmail. Você pode usar esse token com o método GmailApp.setCurrentMessageAccessToken(accessToken) para conceder ao complemento acesso temporário à mensagem aberta do Gmail de um usuário ou permitir que o complemento escreva novos rascunhos.
|
gmail.bccRecipients[] |
list of strings Desativado por padrão. A lista de endereços de e-mail de destinatários em "Cco:" atualmente incluída em um rascunho que o complemento está compondo. Para ativar esse campo, defina o campo addOns.gmail.composeTrigger.draftAccess no manifesto como METADATA .
|
gmail.ccRecipients[] |
list of strings Desativado por padrão. A lista de endereços de e-mail de destinatários "CC:" atualmente incluídos em um rascunho que o complemento está escrevendo. Para ativar esse campo, defina o campo addOns.gmail.composeTrigger.draftAccess no manifesto como METADATA .
|
gmail.messageId |
string O ID da mensagem do Gmail aberta no momento. |
gmail.threadId |
string O ID da conversa do Gmail aberta no momento. |
gmail.toRecipients[] |
list of strings Desativado por padrão. A lista de endereços de e-mail de destinatários "Para:" atualmente incluídos em um rascunho que o complemento está escrevendo. Para ativar esse campo, defina o campo addOns.gmail.composeTrigger.draftAccess no manifesto como METADATA .
|
Objeto de evento do Documentos
O objeto de evento do Documentos é a parte do objeto de evento geral que carrega informações sobre o documento de um usuário e seu conteúdo. Ele só estará presente em um objeto de evento se o aplicativo host for o Documentos Google.
Objeto de evento do Documentos | |
---|---|
docs.id |
string Somente presente se o escopo
https://www.googleapis.com/auth/drive.file tiver sido autorizado pelo usuário.O ID do documento aberto na IU do Documentos. |
docs.title |
string Presente apenas se o escopo
https://www.googleapis.com/auth/drive.file tiver sido autorizado pelo usuário.O título do documento aberto na IU do Documentos. |
docs.addonHasFileScopePermission |
boolean Se true , o complemento solicitou e recebeu a autorização de escopo https://www.googleapis.com/auth/drive.file para o documento aberto na IU do Documentos. Caso contrário, esse campo será false .
|
docs.matchedUrl.url |
string
presente apenas se as seguintes condições forem atendidas:
O URL do link que gera uma visualização no Documentos Google. Para usar esse campo, configure o LinkPreviewTriggers no manifesto do complemento. Consulte Visualizar links no Documentos Google para mais detalhes.
Exemplo de payload para quando um usuário visualiza o link "docs" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |
Objeto de evento do Planilhas
O objeto de evento do Planilhas é a parte do objeto de evento geral que carrega informações sobre o documento e o conteúdo de um usuário. Ele só estará presente em um objeto de evento se o aplicativo host for o Planilhas Google.
Objeto de evento do Planilhas | |
---|---|
sheets.id |
string Só estará presente se o escopo
https://www.googleapis.com/auth/drive.file tiver sido autorizado pelo usuário. O ID da planilha aberta na IU do Planilhas.
|
sheets.title |
string Só estará presente se o escopo
https://www.googleapis.com/auth/drive.file tiver sido autorizado pelo usuário. O título da planilha é aberto na IU do Planilhas.
|
sheets.addonHasFileScopePermission |
boolean Se true , o complemento solicitou e recebeu a autorização de escopo https://www.googleapis.com/auth/drive.file para a planilha aberta na IU do Planilhas. Caso contrário, esse campo será false .
|
Objeto de evento do Apresentações
O objeto de evento do Apresentações é a parte do objeto de evento geral que carrega informações sobre o documento e o conteúdo de um usuário. Ele só estará presente em um objeto de evento se o aplicativo host for o Apresentações Google.
Objeto de evento do Apresentações | |
---|---|
slides.id |
string Só estará presente se o escopo
https://www.googleapis.com/auth/drive.file tiver sido autorizado pelo usuário. O ID da apresentação aberto na IU do Apresentações.
|
slides.title |
string Só estará presente se o escopo
https://www.googleapis.com/auth/drive.file tiver sido autorizado pelo usuário. O título da apresentação é aberto na IU do Apresentações.
|
slides.addonHasFileScopePermission |
boolean Se true , o complemento solicitou e recebeu uma autorização de escopo https://www.googleapis.com/auth/drive.file para a apresentação aberta na IU do Apresentações. Caso contrário, esse campo será false .
|