Beranda

Halaman beranda adalah fitur add-on Google Workspace yang memberikan kemampuan untuk menentukan satu atau beberapa kartu non-kontekstual. Kartu non-kontekstual menampilkan antarmuka pengguna saat pengguna berada di luar konteks tertentu, seperti saat melihat kotak masuk Gmail tanpa membuka pesan atau draf.

Halaman beranda memungkinkan Anda menampilkan konten non-kontekstual, mirip dengan aplikasi Google di panel samping akses cepat (Google Keep, Google Kalender, dan Google Tasks). Halaman beranda juga dapat memberikan titik awal saat pengguna pertama kali membuka add-on Anda dan berguna untuk mengajari pengguna baru cara berinteraksi dengan add-on Anda.

Tentukan halaman beranda untuk add-on Anda dengan menentukannya di manifest project dan menerapkan satu atau beberapa fungsi homepageTrigger (lihat Konfigurasi halaman beranda). Jika add-on Anda memperluas Google Chat, halaman berandanya akan muncul di tab Beranda dalam pesan langsung 1:1 dengan aplikasi Chat dan dikonfigurasi di konsol Google Cloud, bukan di manifes (lihat Mengonfigurasi halaman beranda untuk Chat).

Anda dapat memiliki beberapa halaman beranda, satu untuk setiap aplikasi host yang diperluas oleh add-on Anda. Anda juga dapat menentukan satu halaman beranda default umum yang digunakan di host tempat Anda belum menentukan halaman beranda kustom.

Halaman beranda add-on Anda ditampilkan dalam kasus berikut:

• Saat add-on pertama kali dibuka di host (setelah otorisasi), atau saat pengguna membuka tab Beranda dalam pesan langsung 1:1 dengan aplikasi Chat Anda di Chat.
• Saat pengguna beralih dari konteks kontekstual ke konteks non-kontekstual saat add-on terbuka. Misalnya, dari mengedit acara Kalender ke Kalender utama.
• Saat pengguna mengklik tombol kembali beberapa kali untuk memunculkan setiap kartu lain dari tumpukan internal.
• Saat interaksi UI di kartu non-kontekstual menghasilkan panggilan Navigation.popToRoot.

Sebaiknya desain halaman beranda. Jika Anda tidak menentukannya, kartu generik yang berisi nama add-on Anda akan digunakan setiap kali pengguna membuka halaman beranda.

Konfigurasi halaman beranda

Add-on Google Workspace menggunakan kolom addOns.common.homepageTrigger untuk mengonfigurasi konten add-on halaman beranda default (non-kontekstual) untuk aplikasi host dalam manifes add-on:

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

• runFunction: Nama fungsi Google Apps Script yang dipanggil framework add-on Google Workspace untuk merender kartu add-on beranda. Fungsi ini adalah fungsi pemicu halaman beranda. Fungsi ini harus membuat dan menampilkan array objek Card yang membentuk UI halaman beranda. Jika lebih dari satu kartu ditampilkan, aplikasi host akan menampilkan header kartu dalam daftar yang dapat dipilih pengguna (lihat Menampilkan beberapa kartu).

• enabled: Apakah kartu halaman beranda harus diaktifkan untuk cakupan ini. Kolom ini bersifat opsional, dan defaultnya adalah true. Menetapkan parameter ini ke false akan menyebabkan kartu beranda dinonaktifkan untuk semua host (kecuali jika diganti untuk host tersebut; lihat konfigurasi khusus host).

Agar host dapat menggunakan halaman beranda umum, addOns.common.homepageTrigger dan resource tingkat teratas host harus ada di manifes add-on. Misalnya, jika addOns.gmail tidak ada dalam manifes, add-on akan dinonaktifkan untuk Gmail dan tidak akan menampilkan halaman beranda atau fungsi lainnya di host tersebut.

Selain konfigurasi umum, penggantian per host yang terstruktur secara identik tersedia di setiap konfigurasi aplikasi host, di addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger, dan pemicu khusus host lainnya.

Contoh berikut menunjukkan manifes tempat pemicu halaman beranda umum ditentukan, tetapi diganti dengan fungsi kustom untuk Kalender dan Drive, serta dinonaktifkan untuk Gmail. Dalam konfigurasi ini, fungsi buildHomePage umum tidak pernah dieksekusi karena diganti atau host dinonaktifkan.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

Kutipan manifes berikut setara dengan contoh sebelumnya, meskipun homepageTrigger default dan konfigurasi Gmail dihilangkan:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

Tidak ada bagian homepageTrigger yang wajib diisi. UI yang ditampilkan untuk add-on di produk host bergantung pada keberadaan kolom manifes yang sesuai dan apakah ada homepageTrigger terkait. Contoh berikut menunjukkan fungsi pemicu add-on mana yang dijalankan untuk membuat UI halaman beranda untuk konfigurasi manifes yang berbeda:

Mengonfigurasi halaman beranda untuk 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 akan menampilkan halaman beranda Anda sebagai kartu di tab Beranda pada pesan langsung personal dengan aplikasi Chat.

Untuk mengaktifkan dan mengonfigurasi pemicu App Home untuk add-on Chat di konsol Google Cloud:

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

   Buka Konfigurasi Google Chat API

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

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

   • HTTP: Masukkan URL endpoint HTTPS yang menangani permintaan Beranda Aplikasi (atau biarkan kosong 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.

Saat pengguna membuka tab Beranda dari pesan langsung dengan aplikasi Chat Anda, Chat akan mengirimkan peristiwa pemicu Beranda Aplikasi ke endpoint atau fungsi Anda. Untuk merender halaman beranda, kembalikan objek RenderActions dengan tindakan navigasi pushCard (atau gunakan updateCard saat memperbarui halaman beranda sebagai respons terhadap klik tombol di kartu halaman beranda):

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

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.')))
      .build();

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

Untuk mengetahui detail selengkapnya tentang cara menangani pemicu Chat dan tindakan yang ditampilkan, lihat Menerima dan merespons interaksi pengguna.

Objek peristiwa halaman beranda

Saat dipanggil, fungsi pemicu halaman beranda (runFunction) atau endpoint Beranda Aplikasi yang dijelaskan sebelumnya akan meneruskan objek peristiwa yang berisi data dari konteks pemanggilan.

Objek peristiwa halaman beranda tidak menyertakan widget atau informasi kontekstual. Informasi yang diteruskan mencakup kolom objek peristiwa umum berikut:

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale dan commonEventObject.userTimezone (lihat Mengakses lokalitas dan zona waktu pengguna untuk mengetahui informasi pembatasan).

Di Chat, objek peristiwa Beranda Aplikasi juga menyertakan kolom chat dengan informasi tentang pengguna dan waktu interaksi:

• chat.user: Pengguna Chat yang membuka tab Beranda.
• chat.eventTime: Stempel waktu saat pengguna membuka tab Beranda.

Lihat Objek peristiwa untuk mengetahui detail selengkapnya.

Kartu non-kontekstual lainnya

UI add-on Anda dapat berisi kartu non-kontekstual tambahan yang bukan halaman beranda. Misalnya, halaman beranda Anda mungkin memiliki tombol yang membuka kartu "Setelan" untuk menyesuaikan setelan add-on (setelan tersebut biasanya tidak bergantung pada konteks).

Kartu non-kontekstual dibuat seperti kartu lainnya; satu-satunya perbedaan adalah tindakan atau peristiwa yang menghasilkan dan menampilkan kartu. Lihat Metode navigasi untuk mengetahui detail cara membuat transisi antar-kartu.