유니버설 액션

범용 작업은 사용자가 새 창을 열 수 있는 메뉴 항목 요소입니다. 새 UI 카드를 표시하거나, 특정 Apps Script 기능을 실행할 수 있습니다. 선택합니다. 작동 시 이들은 카드 액션 범용 작업은 항상 부가기능의 모든 카드에 배치된다는 점을 제외하고 현재 부가기능 컨텍스트와 관계없이

범용 작업을 사용하면 사용자가 항상 어떤 부가기능이 상호작용하는지와 상관없이 있습니다. 다음은 범용 작업의 몇 가지 사용 사례입니다.

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

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

범용 작업 사용

범용 작업이 부가기능의 프로젝트에서 구성됩니다. 매니페스트). GCP 콘솔에서 범용 작업을 실행하는 경우 부가기능 사용자는 항상 사용할 수 있습니다. 사용자가 카드를 조회하는 경우 정의한 범용 액션 집합이 항상 표시됩니다. 표시된 카드 액션 지정해야 합니다. 범용 작업은 부가기능의 매니페스트에 정의된 순서와 동일한 순서를 따릅니다.

범용 작업 구성

부가기능의 매니페스트에서 범용 작업을 구성합니다. 보기 매니페스트 를 참조하세요.

작업별로 메뉴에 표시할 텍스트를 지정합니다. 있습니다. 그러면 작업을 나타내는 openLink 필드를 지정할 수 있습니다. 새 탭에서 웹페이지가 바로 열립니다. 또는 다음을 수행할 Apps Script 콜백 함수를 지정하는 runFunction 필드 범용 작업이 선택되면 실행됩니다.

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

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

호출되면 콜백 함수가 이벤트 객체 열려 있는 카드와 부가기능 컨텍스트에 관한 정보가 포함되어 있습니다.

예

다음 코드 스니펫은 범용 작업을 사용하는 Google Workspace 부가기능 동시에 Gmail을 확장합니다. 코드는 메타데이터 범위를 명시적으로 설정하므로 부가기능에서 열려 있는 메시지를 누가 보냈는지 확인할 수 있습니다.

  "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.
}