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 antarmase kartu yang dapat disesuaikan yang muncul di tab Beranda ruang pesan langsung antara pengguna dan aplikasi Chat.

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

Anda dapat menggunakan beranda aplikasi untuk membagikan tips berinteraksi dengan aplikasi Chat atau mengizinkan pengguna mengakses dan menggunakan layanan atau alat eksternal dari Chat.

Gunakan Card Builder untuk mendesain dan melihat pratinjau antarmuka pengguna dan pesan untuk aplikasi Chat:

Buka Card Builder

Prasyarat

Node.js

Aplikasi Google Chat yang menerima dan merespons peristiwa interaksi. Untuk membuat aplikasi Chat interaktif menggunakan layanan HTTP, selesaikan panduan memulai ini.

Python

Aplikasi Google Chat yang menerima dan merespons peristiwa interaksi. Untuk membuat aplikasi Chat interaktif menggunakan layanan HTTP, selesaikan panduan memulai ini.

Java

Aplikasi Google Chat yang menerima dan merespons peristiwa interaksi. Untuk membuat aplikasi Chat interaktif menggunakan layanan HTTP, selesaikan panduan memulai ini.

Apps Script

Aplikasi Google Chat yang menerima dan merespons peristiwa interaksi. Untuk membuat aplikasi Chat interaktif di Apps Script, selesaikan panduan memulai ini.

Mengonfigurasi beranda aplikasi untuk aplikasi Chat Anda

Untuk mendukung beranda aplikasi, Anda harus mengonfigurasi aplikasi Chat agar menerima APP_HOME peristiwa interaksi, Aplikasi Chat Anda menerima peristiwa ini setiap kali pengguna mengklik tab Beranda dari pesan langsung dengan aplikasi Chat.

Untuk memperbarui setelan konfigurasi di konsol Google Cloud, lakukan hal berikut:

  1. Di konsol Google Cloud, klik Menu > APIs & Services > Enabled APIs & Services > Google Chat API > Configuration. Buka konfigurasi Chat API
  2. Di bagian Interactive features, buka bagian Functionality, lalu pilih Support App Home.
  3. Jika aplikasi Chat Anda menggunakan layanan HTTP, buka Connection settings dan tentukan endpoint untuk kolom App Home URL. Anda dapat menggunakan URL yang sama dengan yang Anda tentukan di kolom HTTP endpoint URL.
  4. Klik Save.

Membuat kartu beranda aplikasi

Saat pengguna membuka beranda aplikasi, aplikasi Chat Anda harus menangani peristiwa interaksi APP_HOME dengan menampilkan instance RenderActions dengan navigasi pushCard dan Card. Untuk membuat pengalaman interaktif, kartu dapat berisi widget interaktif seperti tombol atau input teks yang dapat diproses dan direspons oleh aplikasi Chat dengan kartu tambahan, atau dialog.

Dalam contoh berikut, aplikasi Chat menampilkan kartu beranda aplikasi awal yang menampilkan waktu pembuatan kartu dan tombol. Saat pengguna mengklik tombol, aplikasi Chat akan menampilkan kartu yang diperbarui yang menampilkan waktu pembuatan kartu yang diperbarui.

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

Terapkan fungsi onAppHome yang dipanggil setelah semua peristiwa interaksi APP_HOME:

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

Merespons interaksi beranda aplikasi

Jika kartu beranda aplikasi awal Anda berisi widget interaktif, seperti tombol atau input pilihan, aplikasi Chat Anda harus menangani peristiwa interaksi terkait dengan menampilkan instance RenderActions dengan updateCard navigasi. Untuk mempelajari lebih lanjut cara menangani widget interaktif, lihat Memproses informasi yang dimasukkan oleh pengguna.

Dalam contoh sebelumnya, kartu beranda aplikasi awal menyertakan tombol. Setiap kali pengguna mengklik tombol, peristiwa interaksi CARD_CLICKED akan memicu fungsi updateAppHome untuk memuat ulang kartu beranda aplikasi, seperti yang ditunjukkan dalam kode berikut:

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()
  }]}}};
}

Membuka dialog

Aplikasi Chat Anda juga dapat merespons interaksi di beranda aplikasi dengan membuka dialog.

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

Untuk membuka dialog dari beranda aplikasi, proses peristiwa interaksi terkait dengan menampilkan renderActions dengan updateCard navigasi yang berisi objek Card. Dalam contoh berikut, aplikasi Chat merespons klik tombol dari kartu beranda aplikasi dengan memproses peristiwa interaksi CARD_CLICKED dan membuka dialog:

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

Untuk menutup dialog, proses peristiwa interaksi berikut:

  • CLOSE_DIALOG: Menutup dialog dan kembali ke kartu beranda aplikasi awal aplikasi Chat.
  • CLOSE_DIALOG_AND_EXECUTE: Menutup dialog dan memuat ulang kartu beranda aplikasi.

Contoh kode berikut menggunakan CLOSE_DIALOG untuk menutup dialog dan kembali ke kartu beranda aplikasi:

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

Untuk mengumpulkan informasi dari pengguna, Anda juga dapat membuat dialog berurutan. Untuk mempelajari cara membuat dialog berurutan, lihat Membuka dan merespons dialog.