Объекты событий

На этой странице описана структура объектов событий дополнений Google Workspace.

Объекты событий представляют собой структуры JSON, которые автоматически создаются и передаются в качестве параметров функциям запуска или обратного вызова при взаимодействии пользователя с дополнением. Объекты событий передают информацию о хост-приложении и текущем контексте на стороне клиента функции обратного вызова дополнения на стороне сервера.

В надстройках Google Workspace объекты событий используются в следующих местах:

• Триггеры домашней страницы . Каждой определенной вами функции homepageTrigger автоматически передается объект события при срабатывании этой функции. Вы можете использовать этот объект в своей функции homepageTrigger для определения активного хост-приложения, платформы клиента, языковых настроек пользователя и другой информации.

  Объекты событий, создаваемые при срабатывании триггера главной страницы, не содержат всех полей, включенных в другие случаи; поля, относящиеся к виджетам и контекстной информации, опущены.

• Контекстные триггеры . Каждое хост-приложение предоставляет свой набор контекстных триггеров, которые срабатывают, когда пользователь переходит в определенный контекст:

  • Когда пользователь:
    • открывает сообщение
    • составляет сообщение .
    • открывает событие .
  • Google Drive активирует контекстный триггер, когда пользователь выбирает файлы в меню Drive .

  Когда срабатывает контекстный триггер, хост-приложение вызывает соответствующую runFunction указанную в манифесте дополнения, передавая ей объект события в качестве параметра. Объекты событий, создаваемые при срабатывании контекстных триггеров, содержат все поля, включенные в объекты событий триггера главной страницы, а также поля, содержащие контекстную информацию.

• Действия виджетов . Объекты событий обеспечивают интерактивность виджетов , используя ту же модель действий , что и дополнения Gmail. Дополнения Google Workspace используют те же функции обработчика виджетов, объекты Action и ответы на действия. В дополнениях Google Workspace объекты событий действий содержат больше информации, на которую может воздействовать функция обратного вызова.

  Объекты событий, создаваемые на основе действий виджета, содержат все поля, включенные в контекстные объекты событий-триггеров, а также поля, содержащие информацию о виджете.

• Предварительный просмотр ссылок . В Google Docs, Sheets и Slides можно настроить предварительный просмотр ссылок для сторонних сервисов на основе определенных шаблонов URL-адресов. Когда пользователи взаимодействуют со ссылкой, соответствующей шаблону, срабатывает событие linkPreviewTriggers , и объект события, содержащий ссылку, передается в функцию обратного вызова триггера. Ваше дополнение может использовать этот объект события для создания смарт-чипа и карточки, отображающих информацию о ссылке в основном приложении. Вы также можете создавать действия виджетов, чтобы пользователи могли взаимодействовать с карточкой предварительного просмотра и ее содержимым.

• Триггеры приложения Google Chat . В Google Chat ваше дополнение отображается пользователям как приложение чата, и пользователи могут взаимодействовать с ним, добавляя его в пространства, отправляя сообщения, используя команды с косой чертой и многое другое. Для создания интерактивных функций вы настраиваете и используете различные триггеры приложения чата. Каждый триггер отправляет различную полезную нагрузку объекта события , которая помогает вам обрабатывать или реагировать на каждый тип взаимодействия.

Структура объекта события

В следующей таблице описана структура верхнего уровня объектов событий дополнений Google Workspace. Структура включает поле верхнего уровня commonEventObject для информации, не зависящей от хоста. Каждый объект события также может иметь одно из следующих полей верхнего уровня, специфичных для хоста и определяемых активным приложением хоста: gmailEventObject , calendarEventObject или driveEventObject .

Для обеспечения обратной совместимости объекты событий дополнений Google Workspace включают исходные поля, используемые в объектах событий действий дополнений Gmail . Эти поля находятся в разделе «Исходные поля дополнений Gmail» и не являются частью commonEventObject .

Оригинальные поля дополнения Gmail устарели. При разработке или миграции дополнения Google Workspace используйте вместо них более новую структуру объекта события. Эти поля могут быть удалены в будущем обновлении.

Общий объект события

Общий объект события — это часть общего объекта события, которая передает в дополнение от клиентского приложения пользователя общую информацию, не зависящую от хоста. Эта информация включает такие сведения, как локаль пользователя, приложение-хост и платформа.

В дополнение к триггерам главной страницы и контекстным триггерам, дополнения создают и передают объекты событий функциям обратного вызова действий , когда пользователь взаимодействует с виджетами. Функция обратного вызова вашего дополнения может запрашивать общий объект события, чтобы определить содержимое открытых виджетов в клиенте пользователя. Например, ваше дополнение может найти текст, введенный пользователем в виджет TextInput в объекте eventObject.commentEventObject.formInputs .

Форма для выбора даты и времени

Функции обратного вызова действий могут получать текущие значения виджетов в поле commonEventObject.formInputs . Это включает в себя выбранные пользователем значения даты или времени в виджетах выбора даты или времени. Структура информации различается в зависимости от того, был ли виджет настроен как виджет выбора даты и времени, только даты или только времени. Структурные различия описаны в следующей таблице:

Объект события чата

Объект события «Чат» — это часть общего объекта события, содержащая информацию о взаимодействии пользователя с приложением «Чат». Он присутствует в объекте события только в том случае, если дополнение расширяет функциональность Google Chat .

Полезная нагрузка

В зависимости от типа взаимодействия с приложением чата, событие содержит полезную нагрузку с одним или несколькими ресурсами API чата.

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

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

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