Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

홈페이지

홈페이지는 하나 이상의 비컨텍스트 카드를 정의하는 기능을 제공하는 Google Workspace 부가기능입니다. 비컨텍스트 카드는 사용자가 열린 메일이나 임시보관함 없이 Gmail 받은편지함을 보는 등 특정 컨텍스트 외부에 있을 때 사용자 인터페이스를 표시합니다.

홈페이지를 사용하면 빠른 액세스 측면 패널(Google Keep, Google Calendar, Google Tasks)의 Google 앱과 유사한 비맥락 콘텐츠를 표시할 수 있습니다. 홈페이지는 사용자가 애드온을 처음 열 때 초기 시작 위치를 제공할 수도 있으며, 신규 사용자에게 애드온과 상호작용하는 방법을 알려주는 데 유용합니다.

프로젝트 매니페스트에 홈페이지를 지정하고 하나 이상의 homepageTrigger 함수를 구현하여 애드온의 홈페이지를 정의합니다 (홈페이지 구성 참고). 부가기능이 Google Chat을 확장하는 경우 홈페이지는 Chat 앱과의 1:1 채팅 메시지의 홈 탭에 표시되며 매니페스트 대신 Google Cloud 콘솔에서 구성됩니다 (Chat 홈페이지 구성 참고).

애드온이 확장하는 각 호스트 애플리케이션에 대해 홈페이지를 하나씩 여러 개 사용할 수 있습니다. 맞춤 홈페이지를 지정하지 않은 호스트에서 사용되는 단일 공통 기본 홈페이지를 정의할 수도 있습니다.

다음과 같은 경우 부가기능 홈페이지가 표시됩니다.

부가기능이 호스트에서 처음 열리거나(승인 후) 사용자가 Chat에서 Chat 앱과의 1:1 채팅 메시지에서 홈 탭을 열 때
부가기능이 열려 있는 동안 사용자가 컨텍스트 컨텍스트에서 비컨텍스트 컨텍스트로 전환하는 경우 예를 들어 캘린더 일정을 수정하는 것부터 기본 캘린더까지입니다.
사용자가 내부 스택에서 다른 모든 카드를 팝업할 만큼 뒤로 버튼을 여러 번 클릭하는 경우
비컨텍스트 카드에서의 UI 상호작용으로 인해 Navigation.popToRoot 호출이 발생하는 경우

홈페이지를 디자인하는 것이 좋습니다. 정의하지 않으면 사용자가 홈페이지로 이동할 때마다 애드온 이름이 포함된 일반 카드가 사용됩니다.

홈페이지 구성

Google Workspace 부가기능은 addOns.common.homepageTrigger 필드를 사용하여 부가기능 매니페스트에서 호스트 애플리케이션의 기본 홈페이지 (비컨텍스트) 부가기능 콘텐츠를 구성합니다.

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

runFunction: Google Workspace 부가기능 프레임워크가 홈페이지 부가기능 카드를 렌더링하기 위해 호출하는 Google Apps Script 함수의 이름입니다. 이 함수는 홈페이지 트리거 함수입니다. 이 함수는 홈페이지 UI를 구성하는 Card 객체의 배열을 빌드하고 반환해야 합니다. 두 개 이상의 카드가 반환되면 호스트 애플리케이션은 사용자가 선택할 수 있는 목록에 카드 헤더를 표시합니다 (여러 카드 반환 참고).
enabled: 이 범위에 홈페이지 카드를 사용 설정해야 하는지 여부입니다. 이 필드는 선택사항이며 기본값은 true입니다. 이 값을 false로 설정하면 해당 호스트에 대해 재정의되지 않는 한 모든 호스트에 대해 홈페이지 카드가 사용 중지됩니다 (호스트별 구성 참고).

호스트가 공통 홈페이지를 사용하려면 addOns.common.homepageTrigger와 호스트의 최상위 리소스가 모두 부가기능 매니페스트에 있어야 합니다. 예를 들어 addOns.gmail이 매니페스트에 없으면 Gmail에서 부가기능이 사용 중지되고 해당 호스트에 홈페이지나 기타 기능이 표시되지 않습니다.

공통 구성 외에도 동일한 구조의 호스트별 재정의는 각 호스트 애플리케이션의 구성에서 addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger 및 기타 호스트별 트리거에서 사용할 수 있습니다.

다음 예시는 일반적인 홈페이지 트리거가 정의되어 있지만 Calendar 및 Drive의 맞춤 함수로 재정의되고 Gmail에서는 사용 중지된 매니페스트를 보여줍니다. 이 구성에서는 재정의되거나 호스트가 사용 중지되어 공통 buildHomePage 함수가 실행되지 않습니다.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

다음 매니페스트 발췌문은 기본 homepageTrigger와 Gmail 구성이 생략되었지만 이전 예와 동일합니다.

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

homepageTrigger 섹션은 필수가 아닙니다. 호스트 제품에 표시되는 애드온 UI는 해당 매니페스트 필드의 존재 여부와 연결된 homepageTrigger의 존재 여부에 따라 달라집니다. 다음 예는 다양한 매니페스트 구성에 대해 홈페이지 UI를 만들기 위해 실행되는 부가기능 트리거 함수를 보여줍니다.

애드온 홈페이지 트리거 함수 실행 흐름을 보여주는 다이어그램

Chat 홈페이지 구성하기

다른 Google Workspace 호스트 애플리케이션과 달리 Chat을 확장하는 부가기능은 오른쪽의 빠른 액세스 패널에 홈페이지를 표시하지 않으며 매니페스트에서 addOns.common.homepageTrigger를 사용하지 않습니다. 대신 Chat 앱과의 1:1 채팅 메시지의 홈 탭에 홈페이지가 카드로 표시됩니다.

Google Cloud 콘솔에서 Chat 부가기능의 앱 홈 트리거를 사용 설정하고 구성하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 메뉴 > API 및 서비스 > 사용 설정된 API 및 서비스 > Google Chat API > 구성으로 이동합니다.

Google Chat API 구성으로 이동
양방향 기능에서 양방향 기능 사용 설정이 사용 설정되어 있는지 확인한 다음 앱 홈 지원 체크박스를 선택합니다.
연결 설정 > 트리거에서 부가기능 아키텍처에 따라 앱 홈 필드에 앱 홈 핸들러를 지정합니다.
- HTTP: App Home 요청을 처리하는 HTTPS 엔드포인트 URL을 입력합니다 (또는 공통 HTTP 엔드포인트 URL이 모든 이벤트를 수신하도록 비워 둡니다).
- Google Apps Script: 홈페이지 카드를 빌드하고 반환하는 Google Apps Script 콜백 함수의 이름을 입력합니다 (기본값은 onAppHome).
저장을 클릭합니다.

사용자가 Chat 앱과의 채팅 메시지에서 홈 탭을 열면 Chat에서 앱 홈 트리거 이벤트를 엔드포인트 또는 함수로 전송합니다. 홈페이지를 렌더링하려면 pushCard 탐색 작업이 있는 RenderActions 객체를 반환합니다. 홈페이지 카드에서 버튼을 클릭하는 것에 대한 응답으로 홈페이지를 업데이트할 때는 updateCard을 사용합니다.

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

채팅 트리거를 처리하고 작업을 반환하는 방법에 관한 자세한 내용은 사용자 상호작용 수신 및 응답을 참고하세요.

Homepage event objects(홈페이지 이벤트 객체)

호출되면 이전에 설명한 홈페이지 트리거 함수 (runFunction) 또는 앱 홈 엔드포인트에 호출 컨텍스트의 데이터가 포함된 이벤트 객체가 전달됩니다.

홈페이지 이벤트 객체에는 위젯 또는 컨텍스트 정보가 포함되지 않습니다. 전달되는 정보에는 다음 공통 이벤트 객체 필드가 포함됩니다.

commonEventObject.clientPlatform
commonEventObject.hostApp
commonEventObject.userLocale 및 commonEventObject.userTimezone (제한 정보는 사용자 언어 및 시간대 액세스 참고)

Chat에서 앱 홈 이벤트 객체에는 사용자 및 상호작용 시간에 관한 정보가 포함된 chat 필드도 포함됩니다.

chat.user: 홈 탭을 연 Chat 사용자입니다.
chat.eventTime: 사용자가 홈 탭을 연 시점의 타임스탬프입니다.

자세한 내용은 이벤트 객체를 참고하세요.

기타 비맥락 카드

부가기능 UI에는 홈페이지가 아닌 추가 비컨텍스트 카드가 포함될 수 있습니다. 예를 들어 홈페이지에 부가기능 설정을 조정하는 '설정' 카드를 여는 버튼이 있을 수 있습니다 (이러한 설정은 일반적으로 컨텍스트와 독립적임).

비컨텍스트 카드는 다른 카드와 마찬가지로 빌드됩니다. 유일한 차이점은 카드를 생성하고 표시하는 작업 또는 이벤트입니다. 카드 간 전환을 만드는 방법은 탐색 메서드를 참고하세요.

홈페이지 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.