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 dari ruang pesan langsung antara pengguna dan aplikasi Chat.

Gambar 1: Contoh halaman beranda yang muncul di 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 pesan serta antarmuka pengguna untuk aplikasi Chat:

Buka Pembuat Kartu

---

Prasyarat

Node.js

Aplikasi Google Chat yang diaktifkan untuk fitur interaktif. Untuk membuat aplikasi Chat interaktif menggunakan layanan HTTP, selesaikan panduan memulai ini.

Python

Aplikasi Google Chat yang diaktifkan untuk fitur interaktif. Untuk membuat aplikasi Chat interaktif menggunakan layanan HTTP, selesaikan panduan memulai ini.

Java

Aplikasi Google Chat yang diaktifkan untuk fitur interaktif. Untuk membuat aplikasi Chat interaktif menggunakan layanan HTTP, selesaikan panduan memulai ini.

Apps Script

Aplikasi Google Chat yang diaktifkan untuk fitur interaktif. Untuk membuat aplikasi Chat interaktif di Apps Script, selesaikan panduan memulai ini.

Mengonfigurasi beranda aplikasi untuk aplikasi Chat Anda

Untuk mendukung layar utama aplikasi, Anda harus mengonfigurasi aplikasi Chat untuk menerima Peristiwa interaksi APP_HOME, 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, buka Menu > Produk lainnya > Google Workspace > Library Produk > Google Chat API.

   Buka Google Chat API

2. Klik Kelola, lalu klik tab Konfigurasi.

3. Di bagian Interactive features, buka bagian Functionality untuk mengonfigurasi layar utama aplikasi:

   1. Centang kotak Receive 1:1 messages.
   2. Centang kotak Support App Home.

4. Jika aplikasi Chat Anda menggunakan layanan HTTP, buka Connection settings dan tentukan endpoint untuk URL Beranda Aplikasi. Anda dapat menggunakan URL yang sama dengan yang ditentukan di kolom URL endpoint HTTP.

5. Klik Simpan.

Membuat kartu beranda aplikasi

Untuk contoh lainnya, lihat contoh aplikasi Google Chat.

Saat pengguna membuka layar utama 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.

Pada contoh berikut, aplikasi Chat menampilkan kartu beranda aplikasi awal yang menampilkan waktu kartu dibuat dan tombol. Saat pengguna mengklik tombol tersebut, aplikasi Chat menampilkan kartu yang diperbarui yang menunjukkan waktu pembuatan kartu yang diperbarui.

Node.js

node/app-home/index.js

Lihat di GitHub

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

Lihat di GitHub

@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

Lihat di GitHub

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

Implementasikan fungsi onAppHome yang dipanggil setelah semua APP_HOME peristiwa interaksi:

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

apps-script/app-home/app-home.gs

Lihat di GitHub

/**
 * 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 layar utama 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 navigasi updateCard. Untuk mempelajari lebih lanjut cara menangani widget interaktif, lihat Memproses informasi yang dimasukkan oleh pengguna.

Pada 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

Lihat di GitHub

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

Python

python/app-home/main.py

Lihat di GitHub

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

Lihat di GitHub

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

Lihat di GitHub

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

Membuka dialog

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

Gambar 3: Dialog yang meminta pengguna untuk menambahkan kontak.

Untuk membuka dialog dari layar utama aplikasi, proses peristiwa interaksi terkait dengan menampilkan renderActions dengan navigasi updateCard yang berisi 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 layar utama 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 membangun dialog berurutan. Kepada mempelajari cara membangun dialog berurutan, lihat Membuka dan merespons dialog.

Topik terkait

• Lihat contoh aplikasi Chat yang menggunakan layar utama aplikasi.
• Membuka dan merespons dialog.