Weegloo Docs - Membangun Aplikasi

Untuk mengunggah aplikasi web buatan Anda sendiri ke marketplace sebagai Market App, Anda harus terlebih dahulu membangun aplikasi tersebut dan menyiapkan artefak hasil build-nya. Proses ini mencakup membangun situs statis dengan HTML dan JavaScript, lalu memeriksa artefak build dari command line.

Market App adalah aplikasi yang Anda unggah ke marketplace dan dipasang ke Space lain. Bentuknya adalah aplikasi web statis yang sama seperti Web Hosting. Setelah Anda mengunggah kumpulan file tampilan yang sudah dibangun sebelumnya, tampilan tersebut langsung muncul ketika pengunjung masuk.

Ada satu hal yang berbeda dari aplikasi web biasa, dan karena itu muncul satu aturan yang harus dipatuhi saat membangun. Halaman ini membahas perbedaan dan aturan tersebut, serta verifikasi sebelum mengunggah.

Saat dipasang, resource disalin ke Space orang yang memasang

Ketika Market App dipasang, bukan hanya tampilan aplikasi, tetapi juga resource yang Anda pilih bersamaan saat menerbitkan (Content Type, Content, Media, dan sebagainya) ikut disalin ke Space orang yang memasangnya. Bayangkan Anda membuat dan mengunggah aplikasi katalog produk toko pakaian. Ketika seseorang memasang aplikasi itu, bersama tampilan aplikasi, Content Type produk dan Content produk ikut tersalin ke dalam Space orang tersebut.

Resource yang disalin menerima identifier baru di Space tempat ia dipasang. Delivery Access Token yang dipakai untuk membaca konten juga dibuat baru di Space tempat pemasangan. Karena itu aplikasi yang dipasang membaca salinannya sendiri yang disalin ke Space orang yang memasang, bukan Space pembuatnya. Setelah pemasangan selesai, aplikasi itu beroperasi hanya dengan resource dari Space tempat ia dipasang.

Mengapa informasi akses ditanamkan ke dalam build

Market App yang dipasang tidak memiliki server. Karena merupakan hosting statis yang sama seperti Web Hosting, tidak ada runtime server yang menghitung tampilan pada setiap permintaan, dan konten diambil dengan browser yang langsung memanggil API pengiriman WEEGLOO (CDA, Content Delivery API). Karena itu, di dalam artefak build (file tampilan) harus tertulis dari Space mana, apa yang dibaca, dan dengan nilai kredensial apa.

Masalahnya, seperti yang sudah dilihat sebelumnya, saat dipasang, resource disalin dengan identifier baru. Nilai yang tertulis di file build adalah identifier dan token dari Space pembuat, padahal yang harus dibaca di tempat pemasangan adalah salinan yang baru disalin. Jika dibiarkan dengan nilai lama, aplikasi akan menunjuk ke tempat yang salah.

Karena itu WEEGLOO menggantikan nilai-nilai ini untuk Anda saat pemasangan. Saat menerbitkan, WEEGLOO menemukan terlebih dahulu di mana identifier, token, dan identifier resource dari Space pembuat tertulis di dalam teks build, lalu saat pemasangan, mengganti tempat itu dengan nilai baru dari salinan Space tempat pemasangan. Berkat itu, aplikasi yang dipasang secara otomatis menunjuk ke Space tempat ia dipasang.

Penggantian ini hanya terjadi untuk resource yang Anda sertakan bersama aplikasi. Jadi resource yang dibaca oleh tampilan (Content Type, Delivery Access Token, dan sebagainya) harus disertakan seluruhnya saat menerbitkan. Jika ada yang terlewat, identifier tersebut tidak diganti dan tetap menjadi nilai yang salah di tempat pemasangan. Apa saja yang harus disertakan dibahas di bagian pemilihan resource pada Menerbitkan Aplikasi.

Penggantian otomatis ini memiliki satu prasyarat. Nilai harus berada di dalam teks build sebagai satu string utuh apa adanya. Sebab tahap penerbitan mencari string itu secara harfiah dan mencatat posisinya. Jika Anda memecah nilai, membuatnya saat runtime, atau membuatnya diterima dari luar, tahap penerbitan tidak akan menemukannya, dan akibatnya saat pemasangan penggantian juga tidak terjadi sehingga aplikasi yang dipasang tidak berfungsi.

Nilai yang ditanamkan ke dalam build (dan yang diganti saat pemasangan) ada tiga.

sys.id dari Space asli (spaceId): dari Space mana data dibaca.
Delivery Access Token dari Space asli*: nilai kredensial baca-saja yang dapat membaca konten terbit dari Space tersebut.
sys.id dari resource yang dirujuk aplikasi: misalnya sys.id dari Content Type yang menyimpan produk, yaitu identifier resource yang ditunjuk oleh kode klien.

Menyisipkan nilai sebagai literal

Intinya adalah ketiga nilai di atas harus muncul di dalam artefak build sebagai satu literal string utuh (intact literal substring). Ketika Anda membuka file teks hasil build (JS, HTML, JSON, dan sebagainya), nilai harus terlihat sebagai satu kesatuan apa adanya tanpa terpecah atau termodifikasi. Hanya dengan begitu tahap penerbitan dapat menemukan nilai itu dan mencatat posisinya, lalu tahap pemasangan dapat mengganti tempat itu dengan nilai baru.

Berikut adalah contoh konfigurasi yang ditaruh di kode klien. Nilainya hanya contoh untuk menunjukkan formatnya, dan harus Anda ganti dengan nilai kredensial yang sebenarnya.

// weegloo.config.js: nilai-nilai ini dimuat apa adanya ke dalam artefak build
export const WEEGLOO = {
  spaceId: "spc_xxxxxxxxxxxxxxxx",                 // sys.id dari Space asli
  deliveryAccessToken: "dat_xxxxxxxxxxxxxxxxxxxx",  // Delivery Access Token dari Space asli
  productContentTypeId: "ct_xxxxxxxxxxxx",          // sys.id dari Content Type yang dibaca aplikasi
};

Browser memanggil CDA secara langsung dengan nilai ini.

fetch(`https://cda.weegloo.com/v1/spaces/${WEEGLOO.spaceId}/contents`, {
  headers: { Authorization: `Bearer ${WEEGLOO.deliveryAccessToken}` },
});

Cara-cara berikut tidak boleh dipakai. Semuanya membuat nilai tidak tertinggal sebagai literal utuh di artefak build, sehingga tahap penerbitan tidak dapat menemukan nilai itu. Akibatnya saat pemasangan penggantian tidak terjadi, sehingga aplikasi yang dipasang tidak dapat membaca salinan Space-nya sendiri.

Membaca variabel lingkungan saat runtime. Aplikasi yang dipasang tidak memiliki server atau lingkungan runtime untuk menyuntikkan nilai, dan nilainya pun tidak tertinggal secara harfiah di teks build.
```
// Tidak boleh: variabel lingkungan ini tidak ada di tempat pemasangan
deliveryAccessToken: process.env.DELIVERY_ACCESS_TOKEN
```
Mengambil dengan fetch saat runtime. Jika nilai dibuat agar diterima dari suatu tempat, nilainya tidak tertinggal di teks build dan tidak ada tempat untuk mengambilnya.

Memecah dengan penggabungan string. Nilai tidak muncul sebagai satu kesatuan sehingga tahap penerbitan tidak dapat menemukannya.

// Tidak boleh: "dat_xxxxxxxxxxxxxxxxxxxx" tidak tertinggal sebagai satu substring di artefak build
deliveryAccessToken: "dat_" + "xxxxxxxxxxxxxxxxxxxx"

Membiarkannya sebagai placeholder atau kosong. Pengisian nilai dilakukan oleh WEEGLOO saat pemasangan. Namun penggantian itu mencari nilai sebenarnya yang ditanamkan di build lalu mengganti tempatnya, jadi jika dibiarkan kosong atau dengan tanda sementara, tidak ada nilai untuk dicari sehingga tidak menjadi sasaran penggantian. Pada saat artefak build dibuat, nilai sebenarnya harus sudah ada secara harfiah.

Nilai harus selalu ditaruh di file teks (JS, HTML, JSON, dan sebagainya). Jangan menaruhnya di file biner seperti gambar atau font. Pencarian dan penggantian nilai hanya terjadi pada file teks.

Bundler juga termasuk yang perlu diperiksa. Sebagian bundler memecah atau memodifikasi literal string dalam proses optimasi. Jangan merasa aman hanya dengan melihat kode sumber, buka artefak build yang sebenarnya dan periksa apakah nilai tetap utuh sebagai literal (lihat bagian berikutnya).

Terbitkan token dengan hak akses paling rendah

Delivery Access Token yang ditanamkan di build terekspos apa adanya ke browser. Siapa pun yang memasang dapat melihat nilai ini di file build aplikasi (token yang dibuat baru di Space tersebut setelah pemasangan juga sama-sama terekspos). Oleh karena itu, token ini harus diterbitkan dengan SpaceRole berhak akses paling rendah yang hanya dapat membaca Content Type yang benar-benar perlu dibaca aplikasi. Jangan terbitkan dengan peran Administrator. Jika token berhak admin terekspos ke browser, seluruh Space asli menjadi berisiko.

Cara membuat SpaceRole berhak akses paling rendah dan menerbitkan Delivery Access Token dengan peran tersebut dibahas di Token.

Verifikasi sebelum menerbitkan

Sebelum mengunggah, periksa apakah nilai sudah masuk dengan benar bukan di dalam kepala, tetapi pada artefak build yang sebenarnya. Di folder hasil build, jalankan grep untuk masing-masing spaceId asli, token, dan sys.id resource, lalu lihat apakah keluar sebagai literal utuh.

grep -r "DATxxxxxxxxxxxxxxxx" dist/

Cukup jika nilai yang dicari muncul sebagai satu kesatuan (tanpa terpecah atau termodifikasi) di dalam artefak build. Periksa untuk ketiga nilai yang ditanamkan (spaceId, Delivery Access Token, dan sys.id resource yang dirujuk). Jika salah satu saja tidak tertangkap oleh grep, tahap penerbitan juga tidak akan menemukan nilai itu, sehingga tidak diganti saat pemasangan (berarti bundler memodifikasi nilai itu atau ia hilang karena pembacaan saat runtime). Dalam kasus itu, perbaiki agar nilai tetap utuh sebagai literal dengan merujuk pada "Menyisipkan nilai sebagai literal" di atas.

Batasan build statis

Artefak build Market App mengikuti batasan statis yang sama seperti Web Hosting.

Tidak ada runtime server. Harus dibangun dengan static export (tanpa SSR).
Saat diekstrak, jumlah file harus 100 atau kurang.
Harus ada index.html di paling atas (root) kumpulan file.
Pemanggilan API WEEGLOO (CDA dan sebagainya) dilakukan langsung dari browser.

Batasan statis dan aturan kumpulan file selengkapnya dibahas di Penerapan Situs Web.

Tampilan yang dibangun dikemas ke dalam App Bundle

Artefak build yang sudah diverifikasi dikemas ke dalam App Bundle (paket aplikasi yang dikelompokkan per versi) saat menerbitkan. Resource yang dipilih bersamaan di layar penerbitan juga dikemas ke paket yang sama, lalu disalin ke Space tempat pemasangan saat dipasang. Prosedur menerbitkan dan menaikkan versi dibahas di Menerbitkan Aplikasi.

Jika aplikasi menerima anggotanya sendiri

Sampai di sini adalah kasus membaca konten publik yang dapat dibaca siapa saja melalui CDA. Jika aplikasi menerima pendaftaran dan login anggotanya sendiri, Anda memakai ServiceLogin dan SDK klien resmi. Dalam kasus ini browser memanggil ACDA (App Content Delivery API), bukan CDA, dengan token anggota. Pengaturan dan cara integrasinya dibahas di Login Anggota Layanan.

Metode autentikasi Market App yang dipasang dibahas oleh App Auth, dan pengguna yang memiliki hak akses ke aplikasi yang dipasang dibahas oleh App Member.

Yang harus dilakukan berikutnya

Menerbitkan Aplikasi: membahas prosedur studio konten untuk mengunggah aplikasi yang Anda buat (App Bundle) ke marketplace.
Penerapan Situs Web: membahas dasar-dasar Web Hosting seperti build statis, batas 100 file, dan index.html di root.
Token: membahas cara menerbitkan Delivery Access Token yang akan disisipkan ke build dengan SpaceRole berhak akses paling rendah.
Referensi API: membahas spesifikasi teknis seperti format permintaan CDA (API pengiriman) yang dipanggil saat tampilan aplikasi memuat konten, dan ACDA jika aplikasi menerima anggotanya sendiri.