Эта страница переведена с помощью Cloud Translation API.

Домашние страницы

«Домашние страницы» — это функция надстройки Google Workspace, позволяющая определять одну или несколько неконтекстуальных карточек . Неконтекстуальные карточки отображают пользовательский интерфейс, когда пользователь находится вне определенного контекста, например, при просмотре почтового ящика Gmail без открытых сообщений или черновиков.

Домашние страницы позволяют отображать неконтекстный контент, подобно приложениям Google в боковой панели быстрого доступа (Google Keep, Google Calendar и Google Tasks). Домашние страницы также могут служить отправной точкой при первом открытии вашего дополнения и полезны для обучения новых пользователей взаимодействию с ним.

Определите домашнюю страницу для вашего дополнения, указав ее в манифесте проекта и реализовав одну или несколько функций homepageTrigger (см. Настройка домашней страницы ). Если ваше дополнение расширяет функционал Google Chat, его домашняя страница отображается на вкладке « Главная » в личном сообщении с приложением Chat и настраивается в консоли Google Cloud, а не в манифесте (см. Настройка домашней страницы для Chat ).

Вы можете установить несколько домашних страниц, по одной для каждого приложения хостинга, которое расширяет ваше дополнение. Вы также можете определить единую общую домашнюю страницу по умолчанию, которая будет использоваться на хостингах, где вы не указали пользовательскую домашнюю страницу.

Домашняя страница вашего дополнения отображается в следующих случаях:

Когда дополнение впервые открывается на хосте (после авторизации) или когда пользователь открывает вкладку «Главная» в личном сообщении с вашим приложением «Чат» в чате.
Когда пользователь переключается из контекстного режима в неконтекстный, пока дополнение открыто. Например, при переходе от редактирования события в календаре к основному календарю.
Когда пользователь достаточно часто нажимает кнопку «Назад», чтобы убрать каждую вторую карту из внутренних стопок .
Когда взаимодействие с пользовательским интерфейсом в неконтекстной карточке приводит к вызову Navigation.popToRoot .

Рекомендуется разработать главную страницу. Если вы её не укажете, при каждом переходе пользователя на главную страницу будет отображаться стандартная карточка с названием вашего дополнения.

Настройки главной страницы

В надстройках Google Workspace поле addOns.common.homepageTrigger используется для настройки содержимого домашней страницы по умолчанию (неконтекстной) для приложений-хостов в манифесте надстройки:

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

runFunction : Имя функции Google Apps Script, которую вызывает платформа дополнений Google Workspace для отображения карточек дополнений на главной странице. Эта функция является функцией запуска главной страницы . Эта функция должна создавать и возвращать массив объектов Card , составляющих пользовательский интерфейс главной страницы. Если возвращается более одной карточки, приложение-хост отображает заголовки карточек в списке, из которого пользователь может выбрать нужную (см. Возврат нескольких карточек ).
enabled : Следует ли включать карточки на главной странице для данной области видимости. Это поле необязательно и по умолчанию имеет значение true . Установка значения false приводит к отключению карточек на главной странице для всех хостов (если иное не указано для данного хоста; см. конфигурацию для конкретного хоста).

Для того чтобы хост мог использовать общую домашнюю страницу, в манифесте дополнения должны присутствовать как addOns.common.homepageTrigger , так и ресурс верхнего уровня хоста. Например, если addOns.gmail отсутствует в манифесте, то дополнение будет отключено для Gmail и не будет отображать домашнюю страницу или другие функции на этом хосте.

В дополнение к общей конфигурации, в конфигурации каждого хост-приложения доступны идентичные по структуре переопределения для каждого хоста, например, в параметрах addOns.gmail.homepageTrigger , addOns.calendar.homepageTrigger и других триггерах, специфичных для хоста.

В следующем примере показан манифест, в котором определен общий триггер домашней страницы, но он переопределен пользовательскими функциями для Календаря и Диска и отключен для 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 не является обязательным. Отображаемый пользовательский интерфейс для дополнения в основном продукте зависит от наличия соответствующего поля в манифесте и от того, существует ли связанный с ним триггер homepageTrigger . В следующем примере показано, какие функции триггера дополнения выполняются для создания пользовательского интерфейса главной страницы для различных конфигураций манифеста:

Диаграмма, показывающая последовательность выполнения функции, запускающей главную страницу дополнения.

Настройте главную страницу для чата.

В отличие от других приложений для хостинга Google Workspace, дополнения, расширяющие функциональность Chat, не отображают домашнюю страницу в правой панели быстрого доступа и не используют addOns.common.homepageTrigger в манифесте. Вместо этого Chat отображает вашу домашнюю страницу в виде карточки на вкладке « Главная » в личном сообщении при взаимодействии с приложением Chat.

Чтобы включить и настроить триггер «Домашняя страница приложения» для вашего дополнения «Чат» в консоли Google Cloud:

В консоли Google Cloud перейдите в Меню > API и сервисы > Включенные API и сервисы > Google Chat API > Конфигурация .
Перейдите в раздел «Настройка API чата Google».
В разделе «Интерактивные функции» убедитесь, что параметр «Включить интерактивные функции» включен, а затем установите флажок «Поддерживать главный экран приложения» .
В разделе «Настройки подключения» > «Триггеры» укажите обработчик «Домашний адрес приложения» в поле «Домашний адрес приложения» в соответствии с архитектурой вашего дополнения:
- HTTP : Введите URL-адрес конечной точки HTTPS, которая обрабатывает запросы к App Home (или оставьте это поле пустым, чтобы ваш общий URL-адрес конечной точки HTTP получал все события).
- Google Apps Script : Введите имя функции обратного вызова Google Apps Script, которая создает и возвращает карточку вашей домашней страницы (по умолчанию — onAppHome ).
Нажмите « Сохранить ».

Когда пользователь открывает вкладку «Главная» в личном сообщении вашего приложения «Чат», приложение отправляет событие-триггер «Главная страница приложения» на вашу конечную точку или функцию. Для отображения главной страницы верните объект RenderActions с действием навигации pushCard (или используйте 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();
}

Более подробную информацию об обработке триггеров чата и возврате действий см. в разделе «Получение и обработка взаимодействий с пользователями» .

Объекты событий главной страницы

При вызове функции запуска домашней страницы ( runFunction ) или конечной точки App Home, описанной ранее, в качестве параметра передается объект события , содержащий данные из контекста вызова.

Объекты событий главной страницы не содержат информации о виджетах или контекстной информации. Передаваемая информация включает следующие общие поля объектов событий :

commonEventObject.clientPlatform
commonEventObject.hostApp
commonEventObject.userLocale и commonEventObject.userTimezone (см. раздел «Доступ к локали и часовому поясу пользователя » для получения информации об ограничениях).

В чате объект события «Главная страница приложения» также включает поле chat с информацией о пользователе и времени взаимодействия:

chat.user : Пользователь чата , открывший вкладку «Главная» .
chat.eventTime : Отметка времени, когда пользователь открыл вкладку «Главная» .

Дополнительные сведения см. в объекте Event .

Другие карты, не имеющие отношения к контексту.

В интерфейсе вашего дополнения могут содержаться дополнительные неконтекстные карточки, не являющиеся главными страницами. Например, на главной странице может быть кнопка, открывающая карточку «Настройки» для изменения параметров дополнения (такие настройки обычно не зависят от контекста).

Неконтекстные карточки создаются так же, как и любые другие карточки; единственное отличие заключается в том, какое действие или событие генерирует и отображает карточку. Подробнее о создании переходов между карточками см. в разделе «Методы навигации» .

Домашние страницы Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.