이벤트 객체

이 페이지에서는 Google Workspace 부가기능 이벤트 객체의 구조를 간략하게 설명합니다.

이벤트 객체는 사용자가 부가기능과 상호작용할 때 트리거 또는 콜백 함수를 위해 자동으로 구성되고 매개변수로 전달되는 JSON 구조입니다. 이벤트 객체는 호스트 앱 및 현재 컨텍스트에 대한 클라이언트 측 정보를 부가기능의 서버 측 콜백 함수에 전달합니다.

Google Workspace 부가기능은 다음 위치에 이벤트 객체를 사용합니다.

• 홈페이지 트리거. 정의한 모든 homepageTrigger 함수는 홈페이지 트리거 함수가 실행될 때 이벤트 객체를 자동으로 전달합니다. 홈페이지 트리거 함수에서 이 객체를 사용하여 활성 호스트 앱, 클라이언트의 플랫폼, 사용자 언어, 기타 정보를 식별할 수 있습니다.

  홈페이지 트리거가 실행될 때 생성되는 이벤트 객체에는 다른 두 경우에 포함된 필드가 모두 포함되지는 않습니다. 위젯 및 컨텍스트 정보와 관련된 필드는 생략됩니다.

• 문맥 트리거. 각 호스트 애플리케이션은 사용자가 특정 컨텍스트를 입력할 때 실행되는 서로 다른 컨텍스트 트리거 집합을 제공합니다. 예를 들면 다음과 같습니다.

  • Gmail은 사용자가 메시지를 열 때와 사용자가 메시지를 작성할 때 상황에 맞는 트리거를 제공합니다.
  • Google Calendar는 사용자가 일정을 열 때 상황에 맞는 트리거를 제공합니다.
  • Google Drive는 사용자가 Drive 파일을 선택할 때 컨텍스트 트리거를 제공합니다.

  컨텍스트 트리거가 실행되면 호스트 애플리케이션이 부가기능 매니페스트에 나열된 상응하는 runFunction를 호출하여 이벤트 객체를 매개변수로 전달합니다. 문맥 트리거가 발생할 때 생성되는 이벤트 객체에는 홈페이지 트리거 이벤트 객체에 포함된 모든 필드와 컨텍스트 정보가 포함된 필드가 포함됩니다.

• 위젯 작업. 이벤트 객체는 Gmail 부가기능에서 사용하는 것과 동일한 작업 모델을 사용하여 위젯 상호작용을 제공하는 데에도 사용됩니다. Google Workspace 부가기능은 동일한 위젯 핸들러 함수, Action 객체, 작업 응답을 모두 사용합니다. 그러나 Google Workspace 부가기능의 작업 이벤트 객체에는 콜백 함수가 작업할 수 있는 더 많은 정보가 포함되어 있습니다.

  위젯 작업의 결과로 생성된 이벤트 객체에는 컨텍스트 트리거 이벤트 객체에 포함된 모든 필드와 위젯 정보가 포함된 필드가 포함됩니다.

• 미리보기 링크 트리거. Google Docs에서는 특정 URL 패턴을 기반으로 타사 서비스의 링크 미리보기를 구성할 수 있습니다. 사용자가 패턴을 충족하는 링크와 상호작용하면 linkPreviewTriggers가 실행되고 링크가 포함된 이벤트 객체가 트리거의 콜백 함수에 전달됩니다. 부가기능은 이 이벤트 객체를 사용하여 호스트 애플리케이션 내의 링크 관련 정보를 표시하는 스마트 칩과 카드를 구성할 수 있습니다. 사용자가 미리보기 카드 및 카드 콘텐츠와 상호작용할 수 있도록 위젯 작업을 빌드할 수도 있습니다.

이벤트 객체 구조

다음 표에서는 Google Workspace 부가기능 이벤트 객체의 최상위 구조를 설명합니다. 이벤트 객체 구조에는 호스트 독립적인 정보를 위한 commonEventObject 최상위 필드가 포함되어 있습니다. 각 이벤트 객체는 활성 호스트 앱에 의해 결정되는 gmailEventObject, calendarEventObject, driveEventObject 등의 호스트 관련 최상위 필드 중 하나를 가질 수도 있습니다.

이전 버전과의 호환성을 위해 Google Workspace 부가기능 이벤트 객체에는 Gmail 부가기능 작업 이벤트 객체에서 사용되는 모든 원래 필드도 포함됩니다. 이러한 필드는 아래 표의 '원본 Gmail 부가기능 필드'에 나열되어 있습니다. 이 필드의 정보는 새로운 객체 구조로 재현되었습니다.

공통 이벤트 객체

공통 이벤트 객체는 전체 이벤트 객체에서 사용자 클라이언트의 부가기능에 호스트와 상관없는 일반 정보를 전달하는 부분입니다. 이 정보에는 사용자의 언어, 호스트 앱 및 플랫폼과 같은 세부정보가 포함됩니다.

홈페이지 및 문맥 트리거 외에도 부가기능은 사용자가 위젯과 상호작용할 때 이벤트 객체를 구성하고 작업 콜백 함수에 전달합니다. 부가기능의 콜백 함수는 공통 이벤트 객체를 쿼리하여 사용자의 클라이언트에서 열려 있는 위젯의 내용을 확인할 수 있습니다. 예를 들어 부가기능은 사용자가 eventObject.commentEventObject.formInputs 객체의 TextInput 위젯에 입력한 텍스트를 찾을 수 있습니다.

날짜/시간 선택 도구 양식 입력

작업 콜백 함수는 commonEventObject.formInputs 필드에서 현재 위젯 값을 수신할 수 있습니다. 여기에는 날짜 또는 시간 선택 도구 위젯에서 사용자가 선택한 날짜 또는 시간 값이 포함됩니다. 그러나 정보의 구조는 위젯이 날짜 시간 선택 도구로 구성되었는지, 날짜 전용 선택 도구로 구성되었는지, 시간 전용 선택 도구로 구성되었는지에 따라 다릅니다. 구조적 차이점은 다음 표에 설명되어 있습니다.

캘린더 일정 객체

캘린더 이벤트 객체는 전체 이벤트 객체에서 사용자의 캘린더 및 캘린더 이벤트에 대한 정보를 전달하는 부분입니다. 호스트 애플리케이션이 Google Calendar인 경우에만 이벤트 객체에 있습니다.

다음 표에는 이벤트 객체의 calendarEventObject 필드에 있는 필드가 나와 있습니다. 사용자 생성 데이터로 표시된 필드는 캘린더 이벤트에 데이터가 있고 부가기능이 addOns.calendar.currentEventAccess 매니페스트 필드를 READ 또는 READ_WRITE로 설정하는 경우에만 이벤트 객체에 표시됩니다.

참석자

참석자 객체는 개별 참석자에 대한 정보를 Google 캘린더 일정에 전달합니다. 이 정보는 캘린더 일정에 데이터가 있고 부가기능이 addOns.calendar.currentEventAccess 매니페스트 필드를 READ 또는 READ_WRITE로 설정하는 경우에만 이벤트 객체에 표시됩니다.

회의 데이터

회의 데이터 객체는 Google Calendar 일정에 첨부된 회의에 대한 정보를 전송합니다. Google Meet과 같은 Google 회의 솔루션이거나 서드 파티 회의일 수 있습니다. 이 정보는 캘린더 일정에 데이터가 있고 부가기능이 addOns.calendar.currentEventAccess 매니페스트 필드를 READ 또는 READ_WRITE로 설정하는 경우에만 이벤트 객체에 표시됩니다.

대화 시작 지점

진입점 객체는 전화나 동영상 등 특정 회의에 액세스하기 위해 설정된 수단에 대한 정보를 전달합니다. 이 정보는 캘린더 일정에 데이터가 있고 부가기능이 addOns.calendar.currentEventAccess 매니페스트 필드를 READ 또는 READ_WRITE로 설정하는 경우에만 이벤트 객체에 표시됩니다.

Drive 이벤트 객체

드라이브 이벤트 객체는 사용자의 Google 드라이브 및 콘텐츠에 대한 정보를 전달하는 전체 이벤트 객체의 일부입니다. 호스트 애플리케이션이 Google Drive인 경우에만 이벤트 객체에 있습니다.

Drive 항목

Drive 항목 객체는 파일 또는 폴더와 같은 특정 Drive 항목에 대한 정보를 전달합니다.

Gmail 이벤트 객체

Gmail 이벤트 객체는 사용자의 Gmail 메시지에 대한 정보를 전달하는 전체 이벤트 객체의 일부입니다. 이 ID는 호스트 애플리케이션이 Gmail인 경우에만 이벤트 객체에 있습니다.

Docs 이벤트 객체

문서 이벤트 객체는 전체 이벤트 객체에서 사용자의 문서 및 콘텐츠에 대한 정보를 전달하는 부분입니다. 호스트 애플리케이션이 Google 문서인 경우에만 이벤트 객체에 있습니다.

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

Sheets 이벤트 객체

스프레드시트 이벤트 객체는 사용자 문서 및 내용에 대한 정보를 전달하는 전체 이벤트 객체의 일부입니다. 호스트 애플리케이션이 Google 스프레드시트인 경우에만 이벤트 객체에 존재합니다.

Slides 이벤트 객체

Slides 이벤트 객체는 사용자 문서 및 내용에 대한 정보를 전달하는 전체 이벤트 객체의 일부입니다. 호스트 애플리케이션이 Google Slides인 경우에만 이벤트 객체에 있습니다.