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

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

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

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

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

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

Предварительные условия

Node.js

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

Питон

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

Ява

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

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

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

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

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

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

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

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

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

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

    1. Установите флажок Получать сообщения 1:1 .
    2. Установите флажок «Домашняя страница приложения поддержки» .

  4. Если ваше приложение чата использует службу HTTP, перейдите в настройки подключения и укажите конечную точку в поле «Домашний URL-адрес приложения» . Вы можете использовать тот же URL-адрес, который вы указали в поле URL-адрес конечной точки HTTP .

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

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

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

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

Node.js

узел/приложение-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 :

В этом примере отправляется карточное сообщение, возвращая card JSON . Вы также можете использовать службу карточек 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

узел/приложение-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;
}

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

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

приложения-скрипт/app-home/app-home.gs
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}

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

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

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

Чтобы открыть диалоговое окно из домашней страницы приложения, обработайте связанное событие взаимодействия, вернув renderActions с навигацией updateCard , содержащей объект Card . В следующем примере приложение чата реагирует на нажатие кнопки на главной карточке приложения, обрабатывая событие взаимодействия 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 : закрывает диалоговое окно и возвращает к исходной домашней карточке приложения Chat.
  • CLOSE_DIALOG_AND_EXECUTE : закрывает диалоговое окно и обновляет домашнюю карточку приложения.

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

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

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