Beranda

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

Halaman beranda memungkinkan Anda menampilkan konten non-kontekstual, seperti aplikasi Google di panel samping akses cepat (Keep, Kalender, dan 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.

Anda dapat menentukan halaman beranda untuk add-on dengan menentukannya di manifes project dan menerapkan satu atau beberapa fungsi homepageTrigger (lihat Konfigurasi halaman beranda).

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

Halaman beranda add-on Anda ditampilkan jika salah satu kondisi berikut terpenuhi:

• Saat add-on pertama kali dibuka di host (setelah otorisasi).
• 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 menghapus setiap kartu lain dari stack internal.
• Saat interaksi UI dalam kartu non-kontekstual menghasilkan panggilan Navigation.popToRoot().

Mendesain halaman beranda tidak wajib, tetapi sangat direkomendasikan. Jika Anda tidak menentukan halaman beranda, kartu umum yang berisi nama add-on Anda akan digunakan setiap kali pengguna akan 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 semua aplikasi host di manifest add-on:

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

• runFunction: Nama fungsi Apps Script yang dipanggil framework add-on Google Workspace untuk merender kartu add-on beranda. Fungsi ini adalah fungsi pemicu 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 dari (lihat Menampilkan beberapa kartu).

• enabled: Apakah kartu halaman beranda harus diaktifkan untuk cakupan ini. Kolom ini bersifat opsional, dan secara default ditetapkan ke true. Menetapkan parameter ini ke false akan menonaktifkan kartu halaman beranda untuk semua host (kecuali jika diganti untuk host tersebut; lihat di bawah).

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

Selain konfigurasi umum, ada juga penggantian per host yang memiliki struktur identik dan tersedia di setiap konfigurasi aplikasi host, di addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger, dan sebagainya.

Contoh berikut menunjukkan manifes tempat pemicu halaman beranda umum ditentukan, tetapi diganti dengan fungsi kustom untuk Kalender dan Drive, serta dinonaktifkan sepenuhnya 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 }
        },
        ...
      }
    }

Perhatikan bahwa cuplikan manifes berikut setara dengan contoh sebelumnya, meskipun konfigurasi homepageTrigger default dan Gmail dihilangkan:

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

Tidak ada bagian homepageTrigger yang wajib diisi. Namun, UI yang ditampilkan untuk add-on di produk host tertentu bergantung pada keberadaan kolom manifes yang sesuai, dan apakah ada homepageTrigger terkait. Contoh berikut menunjukkan fungsi pemicu add-on mana yang dijalankan (jika ada) untuk membuat UI beranda bagi berbagai konfigurasi manifes:

Objek peristiwa halaman beranda

Saat dipanggil, fungsi pemicu halaman beranda (runFunction) yang dijelaskan di atas akan menerima objek peristiwa yang berisi data dari konteks pemanggilan.

Objek peristiwa halaman beranda tidak menyertakan informasi widget atau kontekstual; informasi yang diteruskan terbatas pada kolom objek peristiwa umum berikut:

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

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" tempat pengguna dapat menyesuaikan setelan add-on (setelan tersebut, dalam sebagian besar kasus, tidak bergantung pada konteks dan oleh karena itu tidak kontekstual).

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.