유니버설 액션

범용 작업은 선택 시 사용자가 새 웹페이지를 열거나 새 UI 카드를 표시하거나 특정 Apps Script 기능을 실행할 수 있는 메뉴 항목 요소입니다. 작동하는 방식은 카드 작업과 매우 유사하지만, 범용 작업은 현재 부가기능 컨텍스트와 관계없이 부가기능의 모든 카드에 항상 배치된다는 점이 다릅니다.

범용 작업을 사용하면 사용자가 상호작용하는 부가기능과 상관없이 특정 기능에 항상 액세스할 수 있습니다. 다음은 범용 작업의 몇 가지 사용 사례입니다.

  • 설정 웹페이지를 열거나 설정 카드를 표시합니다.
  • 사용자에게 도움말 정보를 표시합니다.
  • '새 고객 추가'와 같은 새 워크플로를 시작합니다.
  • 사용자가 부가기능에 관한 의견을 보낼 수 있는 카드를 표시합니다.

현재 컨텍스트에 종속되지 않는 작업이 있을 때마다 보편적인 작업으로 만드는 것을 고려해야 합니다.

범용 작업 사용

범용 작업은 부가기능의 프로젝트 매니페스트에서 구성됩니다. 범용 작업을 구성하면 부가기능 사용자가 항상 사용할 수 있습니다. 사용자가 카드를 보고 있는 경우 정의한 범용 작업 세트는 항상 카드에 정의한 카드 작업 다음에 카드 메뉴에 표시됩니다. 범용 작업은 부가기능의 매니페스트에서 정의된 순서와 동일한 순서로 카드 메뉴에 표시됩니다.

범용 작업 구성

부가기능의 매니페스트에서 범용 작업을 구성합니다. 자세한 내용은 매니페스트를 참고하세요.

각 작업에서 해당 작업의 메뉴에 표시할 텍스트를 지정합니다. 그런 다음 openLink 필드를 지정하여 작업이 새 탭에서 웹페이지를 직접 열어야 함을 나타낼 수 있습니다. 또는 범용 작업이 선택될 때 실행할 Apps Script 콜백 함수를 지정하는 runFunction 필드를 지정할 수 있습니다.

runFunction를 사용하는 경우 지정된 콜백 함수는 일반적으로 다음 중 하나를 실행합니다.

  • 빌드된 UniversalActionResponse 객체를 반환하여 즉시 표시할 UI 카드를 빌드합니다.
  • 다른 작업을 실행한 후 빌드된 UniversalActionResponse 객체를 반환하여 URL을 엽니다.
  • 새 카드로 전환하거나 URL을 열지 않는 백그라운드 작업을 실행합니다. 이 경우 콜백 함수는 아무것도 반환하지 않습니다.

호출되면 열린 카드 및 부가기능 컨텍스트에 대한 정보가 포함된 이벤트 객체가 콜백 함수에 전달됩니다.

다음 코드 스니펫은 Gmail을 확장하는 동안 범용 작업을 사용하는 Google Workspace 부가기능의 매니페스트 발췌 예를 보여줍니다. 코드는 부가기능이 공개 메시지를 보낸 사람을 확인할 수 있도록 메타데이터 범위를 명시적으로 설정합니다.

  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata"
  ],
  "addOns": {
    "common": {
      "name": "Universal Actions Only Addon",
      "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
      "openLinkUrlPrefixes": [
        "https://www.google.com",
        "https://www.example.com/urlbase"
      ],
      "universalActions": [{
          "label": "Open google.com",
          "openLink": "https://www.google.com"
        }, {
          "label": "Open contact URL",
          "runFunction": "openContactURL"
        }, {
          "label": "Open settings",
          "runFunction": "createSettingsResponse"
        }, {
          "label": "Run background sync",
          "runFunction": "runBackgroundSync"
      }],
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "getContextualAddOn"
        }
      ]
    },
    ...
  },
  ...

앞의 예에서 정의한 세 가지 범용 작업은 다음을 실행합니다.

  • google.com 열기를 클릭하면 새 탭에서 https://www.google.com이 열립니다.
  • 연락처 URL 열기는 열 URL을 결정하는 함수를 실행한 다음 OpenLink 객체를 사용하여 새 탭에서 엽니다. 이 코드는 발신자의 이메일 주소를 사용하여 URL을 작성합니다.
  • 설정 열기는 부가기능 스크립트 프로젝트에 정의된 createSettingsCards() 함수를 실행합니다. 이 함수는 부가기능 설정 및 기타 정보가 있는 카드 집합이 포함된 유효한 UniversalActionResponse 객체를 반환합니다. 함수에서 이 객체의 빌드를 완료하면 UI에 카드 목록이 표시됩니다 (여러 카드 반환 참고).
  • 백그라운드 동기화 실행은 부가기능 스크립트 프로젝트에 정의된 runBackgroundSync() 함수를 실행합니다. 이 함수는 카드를 빌드하는 대신 UI를 변경하지 않는 다른 백그라운드 작업을 실행합니다. 이 함수는 UniversalActionResponse를 반환하지 않으므로 함수가 완료될 때 UI에 새 카드가 표시되지 않습니다. 대신 함수가 실행되는 동안 UI에 로드 표시기 스피너가 표시됩니다.

다음은 openContactURL(), createSettingsResponse(), runBackgroundSync() 함수를 구성하는 방법의 예시입니다.

/**
 * Open a contact URL.
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function openContactURL(e) {
  // Activate temporary Gmail scopes, in this case so that the
  // open message metadata can be read.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Build URL to open based on a base URL and the sender's email.
  // This URL must be included in the openLinkUrlPrefixes whitelist.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var sender = message.getFrom();
  var url = "https://www.example.com/urlbase/" + sender;
  return CardService.newUniversalActionResponseBuilder()
      .setOpenLink(CardService.newOpenLink()
          .setUrl(url))
      .build();
}

/**
 * Create a collection of cards to control the add-on settings and
 * present other information. These cards are displayed in a list when
 * the user selects the associated "Open settings" universal action.
 *
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function createSettingsResponse(e) {
  return CardService.newUniversalActionResponseBuilder()
      .displayAddOnCards(
          [createSettingCard(), createAboutCard()])
      .build();
}

/**
 * Create and return a built settings card.
 * @return {Card}
 */
function createSettingCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('Settings'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newSelectionInput()
              .setType(CardService.SelectionInputType.CHECK_BOX)
              .addItem("Ask before deleting contact", "contact", false)
              .addItem("Ask before deleting cache", "cache", false)
              .addItem("Preserve contact ID after deletion", "contactId", false))
          // ... continue adding widgets or other sections here ...
      ).build();   // Don't forget to build the card!
}

/**
 * Create and return a built 'About' informational card.
 * @return {Card}
 */
function createAboutCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('About'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newTextParagraph()
              .setText('This add-on manages contact information. For more '
                  + 'details see the <a href="https://www.example.com/help">'
                  + 'help page</a>.'))
      // ... add other information widgets or sections here ...
      ).build();  // Don't forget to build the card!
}

/**
 * Run background tasks, none of which should alter the UI.
 * Also records the time of sync in the script properties.
 *
 * @param {Object} e an event object
 */
function runBackgroundSync(e) {
  var props = PropertiesService.getUserProperties();
  props.setProperty("syncTime", new Date().toString());

  syncWithContacts();  // Not shown.
  updateCache();       // Not shown.
  validate();          // Not shown.

  // no return value tells the UI to keep showing the current card.
}