Google Chat アプリのホームページを作成する

このページでは、 Google Chat アプリ。ホームページ( Google Chat API: [ホーム] タブに表示されるカスタマイズ可能なカード インターフェース / ダイレクト メッセージ スペース ユーザーと Chat 用アプリの間での通信です。

2 つのウィジェットを含むアプリのホームカード。
図 1: Chat アプリのダイレクト メッセージに表示されるホームページの例。

アプリホームを使用すると、Chat アプリの操作方法や、ユーザーが Chat から外部サービスやツールにアクセスして使用できるようにする方法に関するヒントを共有できます。


カードビルダーを使用して、Chat 用アプリのメッセージとユーザー インターフェースを設計し、プレビューします。

カードビルダーを開く

前提条件

Node.js

インタラクティブ機能が有効になっている Google Chat アプリ。新しい HTTP サービスを使用したインタラクティブな Chat アプリについては、こちらのクイックスタートを完了します。

Python

インタラクティブ機能を有効にする Google Chat アプリ。新しい HTTP サービスを使用したインタラクティブな Chat アプリについては、こちらのクイックスタートを完了します。

Java

インタラクティブ機能を有効にする Google Chat アプリ。HTTP サービスを使用してインタラクティブな Chat アプリを作成するには、こちらのクイックスタートを完了してください。

Apps Script

インタラクティブ機能を有効にする Google Chat アプリ。Apps Script でインタラクティブな Chat アプリを作成するには、こちらのクイックスタートを完了してください。

Chat アプリのアプリホームを構成する

アプリホームをサポートするには、APP_HOME インタラクション イベントを受信するように Chat アプリを構成する必要があります。Chat アプリは、ユーザーが Chat アプリのダイレクト メッセージから [ホーム] タブをクリックするたびに、このイベントを受信します。

Google Cloud コンソールで構成設定を更新する手順は次のとおりです。

  1. Google Cloud コンソールで、メニュー > [その他のプロダクト] > [Google Workspace] > [プロダクト ライブラリ] > [Google Chat API] に移動します。

    Google Chat API に移動

  2. [管理] をクリックしてから、[構成] タブをクリックします。

  3. [インタラクティブ機能] の [機能] セクションに移動して、アプリのホームを構成します。

    1. [1 対 1 のメッセージを受信する] チェックボックスをオンにします。
    2. [アプリのホームをサポートする] チェックボックスをオンにします。
  4. Chat アプリで HTTP サービスを使用する場合は、 接続設定] に移動し、接続先のエンドポイントを指定します。 [App Home URL] フィールド。URL で [HTTP エンドポイント URL] フィールド。

  5. [保存] をクリックします。

アプリのホームカードを作成する

ユーザーがアプリのホームを開いたときに、Chat アプリは APP_HOME インタラクション イベントを返します。つまり、 RenderActions pushCard ナビゲーションと Card。新しい カードにはボタンなどのインタラクティブなウィジェットを テキスト入力、またはテキスト入力として処理でき、 追加のカードやダイアログで応答できます。

次の例では、Chat 用アプリに 最初のアプリのホームカード。カードの作成時刻と、 ボタン。ユーザーがボタンをクリックすると、更新されたカードが返され、更新されたカードの作成時間が表示されます。

Node.js

node/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

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

java/app-home/src/main/java/com/google/chat/app/home/App.java
/**
 * Process Google Chat events
 *
 * @param event Event from chat.
 * @return GenericJson
 * @throws Exception
 */
@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() {
  GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
  textParagraph.setText("Here is the app home 🏠 It's " + new Date());

  GoogleAppsCardV1Widget textParagraphWidget = new GoogleAppsCardV1Widget();
  textParagraphWidget.setTextParagraph(textParagraph);

  GoogleAppsCardV1Action action = new GoogleAppsCardV1Action();
  action.setFunction("updateAppHome");

  GoogleAppsCardV1OnClick onClick = new GoogleAppsCardV1OnClick();
  onClick.setAction(action);

  GoogleAppsCardV1Button button = new GoogleAppsCardV1Button();
  button.setText("Update app home");
  button.setOnClick(onClick);

  GoogleAppsCardV1ButtonList buttonList = new GoogleAppsCardV1ButtonList();
  buttonList.setButtons(List.of(button));

  GoogleAppsCardV1Widget buttonListWidget = new GoogleAppsCardV1Widget();
  buttonListWidget.setButtonList(buttonList);

  GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
  section.setWidgets(List.of(textParagraphWidget, buttonListWidget));

  GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
  card.setSections(List.of(section));

  return card;
}

Apps Script

すべての APP_HOME インタラクション イベントの後に呼び出される onAppHome 関数を実装します。

この例では、カード メッセージを送信するために、 カード JSONApps 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 アプリは、入力または選択入力を 関連するインタラクション イベントを RenderActionsupdateCard」ナビゲーションを使用。インタラクティブ広告の処理と 詳細は ユーザーが入力した情報を処理する

上の例では、最初のアプリのホームカードにボタンが含まれていました。いつ ユーザーがボタンをクリックしたとき(CARD_CLICKED インタラクション イベント) 次に示すように、関数 updateAppHome をトリガーしてアプリのホームカードを更新します。 次のコードを使用します。

Node.js

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

Python

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

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

Apps Script

この例では、カード メッセージを送信するために、 カード JSON。 また、 Apps Script カードサービス

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

ダイアログを開く

Chat アプリは、ダイアログを開いて、アプリのホームでの操作に応答することもできます。

<ph type="x-smartling-placeholder">
</ph> さまざまなウィジェットを備えたダイアログ。
図 3: 連絡先の追加を求めるダイアログ

アプリのホームからダイアログを開くには、次の方法で関連する操作イベントを処理します。 Card を含む updateCard ナビゲーションで renderActions を返す 渡されます。次の例では、チャットアプリが 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" }}]
}}}

ユーザーから情報を収集するために、連続したダイアログを作成することもできます。連続的なダイアログを作成する方法については、ダイアログを開いて応答するをご覧ください。