Halaman ini diterjemahkan oleh Cloud Translation API.

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.

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

Anda dapat menggunakan layar utama 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 dan 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 layar utama aplikasi untuk aplikasi Chat Anda

Untuk mendukung beranda 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:

Di konsol Google Cloud, buka Menu > Produk lainnya > Google Workspace > Library Produk > Google Chat API.

Buka Google Chat API
Klik Kelola, lalu klik tab Konfigurasi.
Di bagian Interactive features, buka bagian Functionality untuk mengonfigurasi layar utama aplikasi:
1. Centang kotak Menerima pesan 1:1.
2. Pilih kotak centang Support App Home.
Jika aplikasi Chat Anda menggunakan layanan HTTP, buka Setelan koneksi dan tentukan endpoint untuk kolom URL Beranda Aplikasi. Anda dapat menggunakan URL yang sama dengan yang Anda tentukan di kolom URL endpoint HTTP.
Klik Simpan.

Membuat kartu layar utama aplikasi

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.

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

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

Implementasikan fungsi onAppHome yang dipanggil setelah semua peristiwa interaksi APP_HOME:

Contoh ini mengirimkan 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 app home

Jika kartu layar utama 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 mengirimkan 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.

Dialog yang menampilkan berbagai widget. — **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 objek Card. Dalam contoh berikut, aplikasi Chat merespons klik tombol dari kartu layar utama 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 layar utama aplikasi awal aplikasi Chat.
CLOSE_DIALOG_AND_EXECUTE: Menutup dialog dan memuat ulang kartu 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 membuat dialog berurutan. Untuk mempelajari cara mem-build dialog berurutan, lihat Membuka dan merespons dialog.

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

Membangun halaman beranda untuk aplikasi Google Chat

Prasyarat

Node.js

Python

Java

Apps Script

Mengonfigurasi layar utama aplikasi untuk aplikasi Chat Anda

Membuat kartu layar utama aplikasi

Node.js

Python

Java

Apps Script

Merespons interaksi app home

Node.js

Python

Java

Apps Script

Membuka dialog

Topik terkait