Создайте домашнюю страницу для приложения Google Chat

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

Карточка приложения с двумя виджетами.
Рисунок 1 : Пример домашней страницы, которая отображается в личных сообщениях приложения Chat.

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


Используйте Card Builder для проектирования и предварительного просмотра сообщений и пользовательских интерфейсов для приложений чата:

Откройте конструктор карт

Предпосылки

Node.js

Приложение Google Chat, которое получает и отвечает на события взаимодействия . Чтобы создать интерактивное приложение Chat с использованием HTTP-сервиса, выполните это краткое руководство .

Питон

Приложение Google Chat, которое получает и отвечает на события взаимодействия . Чтобы создать интерактивное приложение Chat с использованием HTTP-сервиса, выполните это краткое руководство .

Ява

Приложение Google Chat, которое получает и отвечает на события взаимодействия . Чтобы создать интерактивное приложение Chat с использованием HTTP-сервиса, выполните это краткое руководство .

Скрипт приложений

Приложение Google Chat, которое получает и отвечает на события взаимодействия . Чтобы создать интерактивное приложение Chat в Apps Script, выполните это краткое руководство .

Настройте домашнюю страницу приложения для вашего чата

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

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

  1. В консоли Google Cloud перейдите > Дополнительные продукты > Google Workspace > Библиотека продуктов > Google Chat API .

    Перейти к API чата Google

  2. Нажмите «Управление» , а затем перейдите на вкладку «Конфигурация» .

  3. В разделе «Интерактивные функции» перейдите в раздел «Функциональность» , чтобы настроить домашнюю страницу приложения:

    1. Установите флажок «Принимать сообщения 1:1» .
    2. Установите флажок «Поддержка приложения Home» .
  4. Если ваше приложение Chat использует HTTP-сервис, перейдите в настройки подключения и укажите конечную точку для поля App Home URL . Вы можете использовать тот же URL, который вы указали в поле HTTP endpoint URL .

  5. Нажмите «Сохранить» .

Создайте домашнюю карточку приложения

Когда пользователь открывает домашнюю страницу приложения, ваше приложение Chat должно обрабатывать событие взаимодействия APP_HOME , возвращая экземпляр RenderActions с навигацией pushCard и Card . Для создания интерактивного опыта карта может содержать интерактивные виджеты, такие как кнопки или текстовые поля, которые приложение Chat может обрабатывать и на которые можно отвечать дополнительными картами или диалогом.

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

Node.js

узел/app-home/index.js
app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Питон

python/app-home/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

Ява

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Process Google Chat events
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

Скрипт приложений

Реализуйте функцию onAppHome , которая вызывается после всех событий взаимодействия APP_HOME :

Этот пример отправляет сообщение карты, возвращая карту JSON . Вы также можете использовать службу карт Apps Script .

apps-script/app-home/app-home.gs
/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Отвечайте на взаимодействия с домашним приложением

Если ваша начальная домашняя карточка приложения содержит интерактивные виджеты, такие как кнопки или входы выбора, ваше приложение Chat должно обрабатывать соответствующие события взаимодействия, возвращая экземпляр RenderActions с навигацией updateCard . Чтобы узнать больше об обработке интерактивных виджетов, см. Обработка информации, введенной пользователями .

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

Node.js

узел/app-home/index.js
// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Питон

python/app-home/main.py
def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

Ява

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

Скрипт приложений

Этот пример отправляет сообщение карты, возвращая карту JSON . Вы также можете использовать службу карт Apps Script .

apps-script/app-home/app-home.gs
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}

Открытые диалоги

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

Диалоговое окно с различными виджетами.
Рисунок 3 : Диалоговое окно, предлагающее пользователю добавить контакт.

Чтобы открыть диалог из домашней страницы приложения, обработайте соответствующее событие взаимодействия, вернув renderActions с навигацией updateCard , содержащей объект Card . В следующем примере приложение Chat реагирует на нажатие кнопки из домашней страницы приложения, обрабатывая событие взаимодействия CARD_CLICKED и открывая диалог:

{ renderActions: { action: { navigations: [{ updateCard: { sections: [{
  header: "Add new contact",
  widgets: [{ "textInput": {
    label: "Name",
    type: "SINGLE_LINE",
    name: "contactName"
  }}, { textInput: {
    label: "Address",
    type: "MULTIPLE_LINE",
    name: "address"
  }}, { decoratedText: {
    text: "Add to favorites",
    switchControl: {
      controlType: "SWITCH",
      name: "saveFavorite"
    }
  }}, { decoratedText: {
    text: "Merge with existing contacts",
    switchControl: {
      controlType: "SWITCH",
      name: "mergeContact",
      selected: true
    }
  }}, { buttonList: { buttons: [{
    text: "Next",
    onClick: { action: { function: "openSequentialDialog" }}
  }]}}]
}]}}]}}}

Чтобы закрыть диалог, обработайте следующие события взаимодействия:

  • CLOSE_DIALOG : закрывает диалоговое окно и возвращается на начальную домашнюю карточку приложения «Чат».
  • CLOSE_DIALOG_AND_EXECUTE : закрывает диалоговое окно и обновляет домашнюю карточку приложения.

В следующем примере кода CLOSE_DIALOG используется для закрытия диалогового окна и возврата на домашнюю карточку приложения:

{ renderActions: { action: {
  navigations: [{ endNavigation: { action: "CLOSE_DIALOG" }}]
}}}

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