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

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

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

Вы можете использовать главную страницу приложения, чтобы делиться советами по взаимодействию с приложением 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 > Библиотека продуктов > API Google Chat .

    Перейти к API Google Chat

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

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

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

  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"
      }}
    }]}}
  ]}]};
}

Реагировать на взаимодействия на главной странице приложения

Если ваша исходная главная карточка приложения содержит интерактивные виджеты, такие как кнопки или поля выбора, ваше приложение чата должно обрабатывать соответствующие события взаимодействия, возвращая экземпляр 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" }}]
}}}

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

,

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

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

Вы можете использовать главную страницу приложения, чтобы делиться советами по взаимодействию с приложением 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 > Библиотека продуктов > API Google Chat .

    Перейти к API Google Chat

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

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

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

  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"
      }}
    }]}}
  ]}]};
}

Реагировать на взаимодействия на главной странице приложения

Если ваша исходная главная карточка приложения содержит интерактивные виджеты, такие как кнопки или поля выбора, ваше приложение чата должно обрабатывать соответствующие события взаимодействия, возвращая экземпляр 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" }}]
}}}

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