Membangun halaman beranda untuk aplikasi Google Chat

Halaman ini menjelaskan cara membuat halaman beranda untuk pesan langsung dengan aplikasi Google Chat Anda. Halaman beranda, yang disebut sebagai Beranda Aplikasi di Google Chat API, adalah antarmuka kartu yang dapat disesuaikan yang muncul di tab Beranda di ruang pesan langsung 1:1 antara pengguna dan aplikasi Chat.

Kartu beranda aplikasi dengan dua widget.
Gambar 1: Contoh halaman beranda yang muncul dalam pesan langsung dengan aplikasi Chat.

Tidak seperti aplikasi host Google Workspace lainnya, add-on yang memperluas Chat tidak menampilkan halaman beranda di panel akses cepat sisi kanan dan tidak menggunakan addOns.common.homepageTrigger dalam manifes. Sebagai gantinya, Chat menampilkan halaman beranda Anda sebagai kartu di tab Beranda dalam pesan langsung personal dengan aplikasi Chat dan dikonfigurasi di Konsol Google Cloud.

Anda dapat menggunakan Beranda Aplikasi untuk membagikan tips berinteraksi dengan aplikasi Chat, menampilkan dasbor pengguna yang dipersonalisasi, atau memungkinkan pengguna mengakses dan mengonfigurasi layanan atau alat eksternal dari Chat.


Gunakan Pembuat Kartu untuk mendesain dan melihat pratinjau pesan dan antarmuka pengguna untuk aplikasi Chat:

Buka Card Builder

Prasyarat

HTTP

Aplikasi Google Chat yang menerima dan merespons interaksi pengguna. Untuk membuatnya, selesaikan panduan memulai HTTP.

Apps Script

Aplikasi Google Chat yang menerima dan merespons interaksi pengguna. Untuk membuatnya, selesaikan panduan memulai Apps Script.

Mengonfigurasi Beranda Aplikasi untuk aplikasi Chat Anda

Untuk mendukung App Home, aktifkan Support App Home dan konfigurasi App home pemicu di konsol Google Cloud. Aplikasi Chat Anda menerima peristiwa pemicu Beranda Aplikasi setiap kali pengguna membuka tab Beranda dalam pesan langsung 1:1 dengan aplikasi Chat.

Untuk mengonfigurasi App Home di konsol Google Cloud:

  1. Di Konsol Google Cloud, buka Menu > APIs & Services > Enabled APIs & Services > Google Chat API > Configuration.

    Buka konfigurasi Chat API

  2. Di bagian Interactive features, pastikan Enable interactive features diaktifkan, lalu di bagian Functionality, centang kotak Support App Home.

  3. Di bagian Setelan koneksi > Pemicu, tentukan handler App Home di kolom App home berdasarkan arsitektur aplikasi Chat Anda:

    • HTTP: Masukkan URL endpoint HTTPS yang menangani permintaan Beranda Aplikasi (atau pilih Gunakan URL endpoint HTTP umum untuk semua pemicu agar URL endpoint HTTP umum Anda menerima semua peristiwa).
    • Google Apps Script: Masukkan nama fungsi callback Google Apps Script yang membuat dan menampilkan kartu halaman beranda Anda (defaultnya adalah onAppHome).
  4. Klik Simpan.

Menangani objek peristiwa App Home

Saat pengguna membuka tab Beranda dalam pesan langsung personal dengan aplikasi Chat Anda, Chat akan mengirimkan objek peristiwa ke endpoint atau fungsi callback Beranda Aplikasi Anda.

Tidak seperti peristiwa interaksi ruang atau pesan, objek peristiwa Beranda Aplikasi awal tidak menyertakan payload interaksi gabungan (seperti messagePayload). Objek ini berisi kolom berikut:

  • commonEventObject: Mencakup clientPlatform, hostApp ("CHAT"), userLocale, dan userTimezone.
  • chat.user: Pengguna Chat yang membuka tab Beranda.
  • chat.eventTime: Stempel waktu saat pengguna membuka tab Beranda.

Membangun kartu Beranda Aplikasi

Saat pengguna membuka tab Beranda, tangani peristiwa pemicu Beranda Aplikasi dengan menampilkan objek RenderActions dengan tindakan navigasi pushCard dan Card. Untuk membuat pengalaman interaktif, kartu dapat berisi widget interaktif seperti tombol atau input teks.

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                },
                {
                  "buttonList": {
                    "buttons": [
                      {
                        "text": "Refresh",
                        "onClick": {
                          "action": {
                            "function": "https://example.com/updateAppHome"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

/**
 * Builds and returns the App Home card when a user opens the Home tab.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response pushing the homepage card.
 */
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.'))
              .addWidget(
                  CardService.newButtonSet().addButton(
                      CardService.newTextButton()
                          .setText('Refresh')
                          .setOnClickAction(
                              CardService.newAction().setFunctionName(
                                  'updateAppHome')))))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

Merespons interaksi App Home

Jika kartu Beranda Aplikasi Anda berisi widget interaktif, seperti tombol atau input formulir, mengklik tombol akan mengirimkan objek peristiwa yang berisi chat.buttonClickedPayload (bersama dengan commonEventObject.parameters dan commonEventObject.formInputs) ke fungsi atau endpoint tindakan yang dikonfigurasi tombol.

Untuk memperbarui kartu Beranda Aplikasi sebagai respons terhadap interaksi pengguna, tampilkan objek RenderActions dengan tindakan navigasi updateCard. Untuk mempelajari lebih lanjut cara membaca input formulir dari widget interaktif, lihat Membaca input data formulir oleh pengguna di kartu.

HTTP

{
  "action": {
    "navigations": [
      {
        "updateCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Last updated: 2026-10-02T23:00:00Z"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

/**
 * Updates the App Home card when a user clicks the Refresh button.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response updating the homepage card.
 */
function updateAppHome(event) {
  const updatedCard = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Last updated: ' + new Date().toTimeString())))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();
}

Membuka dialog dari Beranda Aplikasi

Aplikasi Chat Anda juga dapat merespons interaksi di App Home dengan membuka dialog.

Dialog yang menampilkan berbagai widget yang berbeda.
Gambar 2: Dialog yang meminta pengguna untuk menambahkan kontak.

Untuk mempelajari cara membuka, memperbarui, dan menutup dialog menggunakan RenderActions (pushCard, updateCard, dan endNavigation: "CLOSE_DIALOG"), lihat Membuka dialog interaktif.

Aplikasi Chat yang bukan add-on: Membuat halaman beranda untuk aplikasi Chat

Jika Anda mengelola aplikasi Chat yang bukan add-on Google Workspace, Chat akan mengirimkan peristiwa interaksi APP_HOME saat pengguna membuka tab Beranda, dan mengirimkan peristiwa interaksi CARD_CLICKED atau SUBMIT_FORM saat pengguna berinteraksi dengan widget di kartu Beranda Aplikasi.

Untuk mengupgrade aplikasi Chat yang bukan add-on ke framework add-on Google Workspace, lihat Mengonversi aplikasi Google Chat menjadi add-on Google Workspace.

Membangun kartu Beranda Aplikasi di aplikasi Chat yang bukan add-on

Di aplikasi Chat yang bukan add-on, tangani peristiwa interaksi APP_HOME dengan menampilkan respons yang berisi kolom renderActions tingkat teratas dengan navigasi pushCard:

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
@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"))))))))));
}

Apps Script

Contoh ini mengirim pesan kartu dengan menampilkan JSON kartu. Anda juga dapat menggunakan layanan kartu 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"
      }}
    }]}}
  ]}]};
}

Menanggapi interaksi Beranda Aplikasi di aplikasi Chat yang bukan add-on

Di aplikasi Chat yang bukan add-on, tangani peristiwa interaksi CARD_CLICKED atau SUBMIT_FORM dari kartu Beranda Aplikasi dengan menampilkan respons yang berisi kolom renderActions tingkat teratas dengan navigasi updateCard:

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

Contoh ini mengirim pesan kartu dengan menampilkan JSON kartu. Anda juga dapat menggunakan layanan kartu Apps Script.

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