홈페이지는 하나 이상의 문맥 외 카드를 정의하는 기능을 제공하는 새로운 Google Workspace 부가기능입니다.
문맥 외 카드는 사용자가 특정 컨텍스트 외부에 있을 때 사용자 인터페이스를 표시하는 데 사용됩니다(예: 사용자가 Gmail 받은편지함을 보고 있지만 메시지 또는 답장을 열지 않은 경우).
홈페이지에서는 빠른 액세스 측면 패널 의 Google 앱(Keep, Calendar, Tasks)과 마찬가지로 문맥과 관련 없는 콘텐츠를 표시할 수 있습니다. 홈페이지는 사용자가 부가기능을 처음 열 때의 시작 지점이 될 수도 있으며 신규 사용자에게 부가기능과 상호작용하는 방법을 안내하는 데 유용합니다.
프로젝트 매니페스트에서 홈페이지를 지정하고 하나 이상의 homepageTrigger 함수를 구현하여 부가기능의 홈페이지를 정의할 수 있습니다 (홈페이지 구성 참고).
부가기능이 확장하는 호스트 애플리케이션마다 하나씩 여러 개의 홈페이지를 보유할 수 있습니다. 맞춤 홈페이지를 지정하지 않은 호스트에서 사용되는 단일 공통 기본 홈페이지를 정의할 수도 있습니다.
부가기능 홈페이지는 다음 조건 중 하나가 충족될 때 표시됩니다.
호스트에서 부가기능이 처음 열릴 때 (승인 후)
부가기능이 열려 있는 동안 사용자가 문맥 컨텍스트에서 비문맥 컨텍스트로 전환할 때 예를 들어 Calendar 일정을 수정하는 작업에서 기본 Calendar로 이동하는 경우
runFunction: Google Workspace 부가기능 프레임워크가 홈페이지 부가기능 카드를 렌더링하기 위해 호출하는 Apps Script 함수의 이름입니다.
이 함수는 홈페이지 트리거 함수입니다. 이 함수는 홈페이지 UI를 구성하는 Card 객체 배열을 빌드하고 반환해야 합니다. 카드가 두 개 이상 반환되면 호스트 애플리케이션은 사용자가 선택할 수 있는 목록에 카드 헤더를 표시합니다 (여러 카드 반환 참고).
enabled: 이 범위에 홈페이지 카드를 사용 설정해야 하는지 여부 이 필드는 선택사항이며 기본값은 true입니다. 이 값을 false로 설정하면 해당 호스트에서 재정의하지 않는 한 모든 호스트에서 홈페이지 카드가 사용 중지됩니다 (아래 참고).
공통 구성 외에도 각 호스트 애플리케이션의 구성(addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger 등)에서 동일한 구조의 호스트별 재정의를 사용할 수 있습니다.
{
...
"addOns": {
...
"common": {
// By default, call 'buildHomePage' to render homepage content
// in all hosts. Since calendar.homepageTrigger below overrides
// this in Calendar and Drive and the homepageTrigger is disabled
// for Gmail, this homepage function never executes.
"homepageTrigger": { "runFunction": "buildHomePage" }
},
"calendar": {
// Show customized homepage content for Calendar only.
"homepageTrigger": { "runFunction": "buildCalendarHomepage" }
},
"drive": {
// Show customized homepage content for Drive only.
"homepageTrigger": { "runFunction": "buildDriveHomepage" }
}
"gmail": {
// Disable homepage add-on content in Gmail.
"homepageTrigger": { "enabled": false }
},
...
}
}
homepageTrigger 섹션은 모두 선택사항입니다. 그러나 특정 호스트 제품의 부가기능에 표시되는 UI는 해당 매니페스트 필드의 존재 여부와 연결된 homepageTrigger의 유무에 따라 다릅니다. 다음 예는 다양한 매니페스트 구성의 홈페이지 UI를 만들기 위해 실행되는 부가기능 트리거 함수 (있는 경우)를 보여줍니다.
홈페이지 이벤트 객체
호출 시 위에 설명된 홈페이지 트리거 함수 (runFunction)에는 호출 컨텍스트의 데이터가 포함된 이벤트 객체가 전달됩니다.
홈페이지 이벤트 객체에는 위젯 또는 문맥 정보가 포함되지 않습니다. 전달되는 정보는 다음 공통 이벤트 객체 필드로 제한됩니다.
commonEventObject.clientPlatform
commonEventObject.hostApp
commonEventObject.userLocale 및 commonEventObject.userTimezone (제한사항 정보는 사용자 언어 및 시간대 액세스 참고).
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-01(UTC)"],[[["\u003cp\u003eHomepages in Google Workspace add-ons display non-contextual content, similar to built-in apps like Keep and Calendar, offering a starting point for users.\u003c/p\u003e\n"],["\u003cp\u003eYou can customize the homepage content by specifying a homepage trigger function in your add-on's manifest, potentially creating different homepages for each supported host application.\u003c/p\u003e\n"],["\u003cp\u003eAdd-ons can have multiple non-contextual cards, with the homepage acting as the primary entry point and other cards serving specific functions, such as settings or help.\u003c/p\u003e\n"],["\u003cp\u003eAlthough not mandatory, designing a homepage is recommended to improve the user experience, as a generic card is used otherwise.\u003c/p\u003e\n"],["\u003cp\u003eHomepage triggers are invoked without contextual information, relying on limited event object fields like client platform, host application, user locale, and timezone.\u003c/p\u003e\n"]]],["Google Workspace add-ons can utilize \"homepages,\" which are non-contextual cards displayed when users are outside a specific context or first open an add-on. Developers define homepages in the project manifest using `homepageTrigger` functions, which generate the UI. Multiple homepages can be specified for different host applications, or a default one can be used. Homepages are triggered when the add-on opens, transitions out of context, or navigates to the root. It's highly recommended to create a homepage, else a basic card is used.\n"],null,["# Homepages\n\n*Homepages* are a new Google Workspace add-ons feature\nthat provides the ability to define one or more *non-contextual cards*.\nNon-contextual cards are used to display a user interface when the user is\noutside a specific context, such as when the user is viewing their Gmail inbox\nbut hasn't opened a message or draft.\n\nHomepages let you show non-contextual content, just like the\nGoogle apps in the\n[quick-access side panel](https://workspaceupdates.googleblog.com/2018/08/use-quick-access-side-panel-to-do-more.html)\n(Keep, Calendar, and Tasks). Homepages can also provide an initial starting\nplace for when a user first opens your add-on, and are useful for teaching\nnew users how to interact with your add-on.\n\nYou can define a homepage for your add-on by specifying it in your project\nmanifest and implementing one or more `homepageTrigger` functions (see\n[Homepage configuration](#homepage_configuration)).\n\nYou can have multiple homepages, one for each host application that your add-on\nextends. You can also decide to define a single common default homepage that is\nused in hosts where you haven't specified a custom homepage.\n\nYour add-on homepage is displayed when one of the following conditions are met:\n\n- When the add-on is first opened in the host (after authorization).\n- When the user switches from a contextual context to a non-contextual context while the add-on is open. For example, from editing a Calendar event to the main Calendar.\n- When the user clicks the back button enough times to [pop every other card off of the internal stacks](/workspace/add-ons/how-tos/navigation).\n- When a UI interaction in a non-contextual card results in a [`Navigation.popToRoot()`](/apps-script/reference/card-service/navigation#popToRoot()) call.\n\nDesigning a homepage isn't mandatory but highly recommended; if you do not define any, a generic card\ncontaining your add-on name is used whenever a user would otherwise navigate\nto the homepage.\n\nHomepage configuration\n----------------------\n\nGoogle Workspace add-ons use the\n[`addOns.common.homepageTrigger`](/apps-script/manifest/addons#Common.FIELDS.homepageTrigger)\nfield to configure the default homepage (non-contextual) add-on content for\nall host applications in the add-on\n[manifest](/workspace/add-ons/concepts/workspace-manifests): \n\n {\n // ...\n \"addOns\": {\n // ...\n \"common\": {\n // ...\n \"homepageTrigger\": {\n \"runFunction\": \"myFunction\",\n \"enabled\": true\n }\n }\n }\n }\n\n- `runFunction`: The name of the Apps Script function that the\n Google Workspace add-ons framework invokes to render homepage add-on cards.\n This function is the *homepage trigger function* . This function must build\n and return an array of [`Card`](/apps-script/reference/card-service/card)\n objects that make up the homepage UI. If more than one card is returned, the\n host application shows the card headers in a list that the user can select\n from (see\n [Returning multiple cards](/workspace/add-ons/how-tos/navigation#returning_multiple_cards)).\n\n- `enabled`: Whether homepage cards should be enabled for this scope. This\n field is optional, and defaults to `true`. Setting this to `false` causes\n homepage cards to be disabled for all hosts (unless overridden for that\n host; see below).\n\n| **Note:** In order for a host to use the common homepage, both [`addOns.common.homepageTrigger`](/apps-script/manifest/addons#Common.FIELDS.homepageTrigger) and the host's top-level resource must be present in the add-on [manifest](/workspace/add-ons/concepts/workspace-manifests). For example, if [`addOns.gmail`](/apps-script/manifest/addons#AddOns.FIELDS.gmail) isn't present in the manifest, then the add-on is disabled for Gmail and will not show a homepage (or any other functionality in that host).\n\nIn addition to the common configuration, there are also\nidentically-structured per-host overrides available in each host application's\nconfig, at `addOns.gmail.homepageTrigger`, `addOns.calendar.homepageTrigger`,\nand so forth: \n\n {\n ...\n \"addOns\": {\n ...\n \"common\": {\n // By default, call 'buildHomePage' to render homepage content\n // in all hosts. Since calendar.homepageTrigger below overrides\n // this in Calendar and Drive and the homepageTrigger is disabled\n // for Gmail, this homepage function never executes.\n \"homepageTrigger\": { \"runFunction\": \"buildHomePage\" }\n },\n \"calendar\": {\n // Show customized homepage content for Calendar only.\n \"homepageTrigger\": { \"runFunction\": \"buildCalendarHomepage\" }\n },\n \"drive\": {\n // Show customized homepage content for Drive only.\n \"homepageTrigger\": { \"runFunction\": \"buildDriveHomepage\" }\n }\n \"gmail\": {\n // Disable homepage add-on content in Gmail.\n \"homepageTrigger\": { \"enabled\": false }\n },\n ...\n }\n }\n\nNote that this is equivalent to the following manifest excerpt: \n\n {\n ...\n \"addOns\": {\n ...\n \"common\": { /* ... */ }, // Omitted a default homepageTrigger specification.\n \"calendar\": {\n // Show customized homepage content for Calendar only.\n \"homepageTrigger\": { \"runFunction\": \"myCalendarFunction\" }\n },\n \"drive\": {\n // Show customized homepage content for Drive only.\n \"homepageTrigger\": { \"runFunction\": \"myDriveFunction\" }\n }\n \"gmail\": { /* ... */ },\n ...\n }\n }\n\nNone of the `homepageTrigger` sections are required. However, the UI shown for\nan add-on in any given host product depends on the presence of the\ncorresponding manifest field, and whether there's an associated\n`homepageTrigger`. The following example shows which add-on trigger functions\nare executed (if any) to create a homepage UI for different manifest\nconfigurations:\n\n### Homepage event objects\n\nWhen called, the homepage trigger function (`runFunction`) described above is\npassed an [event object](/workspace/add-ons/concepts/event-objects)\ncontaining data from the invocation context.\n\nHomepage event objects don't include widget or contextual information; the\ninformation passed is limited to the following\n[common event object](/workspace/add-ons/concepts/event-objects#common_event_object)\nfields:\n\n- `commonEventObject.clientPlatform`\n- `commonEventObject.hostApp`\n- `commonEventObject.userLocale` and `commonEventObject.userTimezone` (but see [Accessing user locale and timezone](/workspace/add-ons/how-tos/access-user-locale) for restriction information).\n\nSee [Event object](/workspace/add-ons/concepts/event-objects) for more details.\n\nOther non-contextual cards\n--------------------------\n\nYour add-on UI can contain additional non-contextual cards that aren't\nhomepages. For example, your homepage might have a button that opens a\n\"Settings\" card where the user can adjust the add-on settings (such settings\nwould, in most cases, be independent of context and therefore non-contextual).\n\nNon-contextual cards are built like any other card; the only difference is\nwhat action or event generates and displays the card. See\n[Navigation methods](/workspace/add-ons/how-tos/navigation#navigation_methods)\nfor details on how to create transitions between cards."]]
