메시지 UI 확장

Gmail을 확장하는 Google Workspace 부가기능은 사용자가 메일을 읽을 때 사용자 인터페이스를 제공할 수 있습니다. 이를 통해 Google Workspace 부가기능은 메일과 관련된 추가 정보를 표시, 검색 또는 전송하는 등 메일 콘텐츠에 응답하는 작업을 자동화할 수 있습니다.

부가기능 메시지 UI 액세스

부가기능의 메시지 UI를 보는 방법에는 두 가지가 있습니다. 첫 번째 방법은 부가기능이 이미 열려 있는 동안 메시지를 여는 것입니다 (예: Gmail 받은편지함 창에서 부가기능 홈페이지를 볼 때). 두 번째 방법은 메시지를 보는 동안 부가기능을 시작하는 것입니다.

어느 경우든 부가기능 매니페스트에 정의된 상응하는 문맥 트리거 함수가 실행됩니다. 또한 부가기능이 열려 있는 동안 사용자가 다른 메시지로 전환하면 트리거가 실행됩니다. 문맥 트리거 함수는 해당 메시지의 메시지 UI를 빌드하고 Gmail은 이를 사용자에게 표시합니다.

메시지 부가기능 빌드

다음과 같은 일반적인 단계에 따라 부가기능에 메시지 기능을 추가할 수 있습니다.

  1. 메시지 기능에 필요한 범위를 비롯하여 부가기능 스크립트 프로젝트 매니페스트에 적절한 필드를 추가합니다. 매니페스트에 unconditional 값이 {}인 조건부 트리거 필드를 추가해야 합니다.
  2. 사용자가 메시지에서 부가기능을 선택할 때 메시지 UI를 빌드하는 문맥 트리거 함수를 구현합니다.
  3. 사용자의 UI 상호작용에 응답하는 데 필요한 연결된 함수를 구현합니다.

문맥 트리거

메시지를 읽을 때 사용자에게 도움을 제공하기 위해 Google Workspace 부가기능은 매니페스트에서 문맥 트리거를 정의할 수 있습니다. 사용자가 트리거 기준을 충족하는 Gmail 메일을 열면 (부가기능이 열려 있는 상태)* 트리거가 실행됩니다. 실행된 트리거는 부가기능 사용자 인터페이스를 생성하고 Gmail에 표시되도록 반환하는 문맥 트리거 함수를 실행합니다. 이 시점에서 사용자는 앱과 상호작용을 시작할 수 있습니다.

문맥 트리거는 부가기능의 프로젝트 매니페스트에 정의됩니다. 트리거 정의는 Gmail에 어떤 조건에서 어떤 트리거 함수를 실행할지 알려줍니다. 예를 들어 이 매니페스트 스니펫은 메시지가 열릴 때 트리거 함수 onGmailMessageOpen()를 호출하는 무조건 트리거를 설정합니다.

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

문맥 트리거 함수

모든 문맥 트리거에는 부가기능의 사용자 인터페이스를 구성하는 상응하는 트리거 함수가 있어야 합니다. 이 함수는 매니페스트의 onTriggerFunction 필드에 지정합니다. 이 함수를 구현하여 작업 이벤트 객체 인수를 수락하고 단일 Card 객체 또는 Card 객체 배열을 반환합니다.

특정 Gmail 메일에 대해 문맥 트리거가 실행되면 이 함수를 호출하고 작업 이벤트 객체를 전달합니다. 트리거 함수는 이 이벤트 객체에서 제공된 메일 ID를 사용하여 Apps Script의 Gmail 서비스를 통해 메일 텍스트 및 기타 세부정보를 가져오는 경우가 많습니다. 예를 들어 트리거 함수는 다음 함수를 사용하여 메시지 콘텐츠를 추출할 수 있습니다.

  // Activate temporary Gmail scopes, in this case to allow
  // the add-on to read message metadata and content.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Read message metadata and content. This requires the Gmail scope
  // https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();
  var body = message.getPlainBody();
  var messageDate = message.getDate();

  // Setting the access token with a gmail.addons.current.message.readonly
  // scope also allows read access to the other messages in the thread.
  var thread = message.getThread();
  var threadMessages = thread.getMessages();

  // Using this link can avoid the need to copy message or thread content
  var threadLink = thread.getPermalink();

그러면 트리거 함수가 이 데이터에 대해 작업하여 인터페이스에 필요한 정보를 추출할 수 있습니다. 예를 들어 판매 수치를 요약하는 부가기능은 메일 본문에서 판매 수치를 수집하고 카드에 표시할 수 있도록 정리할 수 있습니다.

트리거 함수는 빌드된 Card 객체의 배열을 빌드하고 반환해야 합니다. 예를 들어 다음은 메일의 제목과 발신자를 나열하는 단일 카드로 부가기능을 빌드합니다.

  function onGmailMessageOpen(e) {
    // Activate temporary Gmail scopes, in this case to allow
    // message metadata to be read.
    var accessToken = e.gmail.accessToken;
    GmailApp.setCurrentMessageAccessToken(accessToken);

    var messageId = e.gmail.messageId;
    var message = GmailApp.getMessageById(messageId);
    var subject = message.getSubject();
    var sender = message.getFrom();

    // Create a card with a single card section and two widgets.
    // Be sure to execute build() to finalize the card construction.
    var exampleCard = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader()
            .setTitle('Example card'))
        .addSection(CardService.newCardSection()
            .addWidget(CardService.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }