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

Главные страницы – это функция дополнений Google Workspace, которая позволяет определять одну или несколько неконтекстных карточек. Карточки без контекста отображают пользовательский интерфейс, когда пользователь находится вне определенного контекста, например просматривает свой почтовый ящик Gmail без открытого письма или черновика.

На главной странице можно показывать контент, не связанный с контекстом, как в приложениях Google на боковой панели быстрого доступа (Google Keep, Google Календарь и Google Задачи). Главные страницы также могут быть полезны для обучения новых пользователей работе с дополнением.

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

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

Главная страница дополнения показывается в следующих случаях:

  • Когда дополнение впервые открывается в хосте (после авторизации) или когда пользователь открывает вкладку Главная в прямом чате 1:1 с вашим приложением Chat в 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. В примере ниже показано, какие функции триггеров дополнений выполняются для создания интерфейса главной страницы при разных конфигурациях манифеста.

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

Как настроить главную страницу для Chat

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

Чтобы включить и настроить триггер для главной страницы приложения в дополнении Chat в консоли Google Cloud, выполните следующие действия:

  1. В консоли Google Cloud нажмите Меню > API и сервисы > Включенные API и сервисы > Google Chat API > Конфигурация.

    Перейти к настройке Google Chat API

  2. В разделе Интерактивные функции убедитесь, что параметр Включить интерактивные функции включен, а затем установите флажок Поддержка приложения "Дом".

  3. В разделе Настройки подключения > Триггеры укажите обработчик главной страницы приложения в поле Главная страница приложения в зависимости от архитектуры дополнения:

    • HTTP Введите URL конечной точки HTTPS, которая обрабатывает запросы на главную страницу приложения (или оставьте поле пустым, чтобы все события получал общий URL конечной точки HTTP).
    • Google Apps Script – введите название функции обратного вызова Google Apps Script, которая создает и возвращает карточку главной страницы (по умолчанию onAppHome).

  4. Нажмите Сохранить.

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

Подробнее о том, как обрабатывать триггеры Chat, возвращать действия и создавать карточку главного экрана приложения, рассказывается в статьях Отправка и обновление карточки главного экрана приложения и Получение и обработка взаимодействий с пользователем.

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

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

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

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

  • chat.user – пользователь Chat, открывший вкладку Главная.
  • chat.eventTime – временная метка момента, когда пользователь открыл вкладку Главная.

Подробнее об объекте события…

Другие карточки без контекста

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

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