Dokumentasi

 

Tutorial Membuat Undangan Digital 1 For Multi-Event

 

Product Requirements Document (PRD)

Sistem Undangan Digital Multi-Event Berbasis Google Apps Script & External Hosting

1. Ringkasan Produk (Executive Summary)

Sistem ini adalah platform undangan digital web-based yang dirancang khusus untuk fleksibilitas tinggi. Sistem ini menggunakan arsitektur Hybrid di mana antarmuka pengguna (Frontend) di-host secara mandiri pada layanan hosting eksternal (cPanel, Vercel, dll.), sementara pemrosesan data dan basis data (Backend) menggunakan satu URL Google Apps Script (GAS) terpusat yang terhubung ke Google Sheets.

Keunggulan utama sistem ini adalah kemampuannya menangani banyak acara (Multi-Event) secara bersamaan hanya dengan satu Backend. Sistem secara cerdas akan membuat tab sheet baru di database untuk setiap nama agenda/acara yang berbeda.

2. Target Pengguna

1. Administrator / Event Organizer: Mengelola penyebaran undangan, mengatur nama event, dan memantau daftar kehadiran di Google Sheets.

2. Tamu Undangan: Menerima undangan dinamis, melihat detail acara, dan mengisi buku tamu.

3. Arsitektur Sistem

• Frontend: HTML5, TailwindCSS, Vanilla JavaScript. (Dapat di-host di mana saja).

• Backend / API: Google Apps Script (code.gs). Bertindak sebagai REST API untuk memproses metode GET (mengambil data) dan POST (menyimpan data).

• Database: Google Sheets terpusat (Satu spreadsheet file dengan banyak sheet tabs).

4. Fitur Utama

1. Satu Backend untuk Semua (Centralized API): Satu URL deployment GAS melayani puluhan atau ratusan web undangan.

2. Auto-Generate Database Sheet: Jika Frontend mengirimkan identifier EVENT_NAME baru yang belum ada di spreadsheet, Backend otomatis membuatkan sheet/tab baru lengkap dengan format header tabelnya.

3. Bilingual Support: Pengguna dapat beralih antara Bahasa Indonesia dan Bahasa Inggris secara instan tanpa perlu reload halaman (Client-side rendering).

4. Dynamic Guest Name: Nama tamu dipersonalisasi melalui parameter URL (contoh: ?to=Nama+Tamu). Terdapat deteksi pintar untuk memberikan nama default jika parameter kosong.

5. Interactive Guestbook: Formulir RSVP dan buku tamu yang langsung memperbarui data ke Google Sheets dan memuat ulang daftar ucapan secara real-time di halaman undangan.

6. Multimedia & Animasi: Dilengkapi dengan musik latar (auto-play dengan proteksi interaksi browser), countdown timer, dan animasi scroll reveal (Intersection Observer).

5. Panduan Penggunaan (Workflow Operasional)

Berikut adalah alur kerja operasional penggunaan sistem ini dari sisi Administrator:

Fase 1: Setup Backend Terpusat (Hanya Dilakukan Sekali)

Langkah ini hanya perlu dilakukan saat pertama kali membangun ekosistem.

1. Deploy code.gs di Google Apps Script.

2. Jalankan fungsi initialSetup() untuk membuat file Google Sheets "Master".

3. Deploy sebagai Web App (akses: "Anyone").

4. Simpan Web App URL. URL ini menjadi "Mesin Induk" selamanya.

Fase 2: Konfigurasi Frontend untuk Acara Baru (Diulang untuk tiap event)

Setiap kali ada pesanan/kebutuhan undangan baru (misal: Wisuda TK, Wisuda SD, Pernikahan A&B):

1. Gandakan (copy) file index.html template.

2. Buka file tersebut, cari variabel konfigurasi berikut di bagian skrip JavaScript:
   const GAS_API_URL = "URL_WEB_APP_GAS_MESIN_INDUK";
   const EVENT_NAME  = "Wisuda_SDITFI2_2026"; // Ganti ini sesuai nama acara
   
   

3. Ubah EVENT_NAME menjadi nama unik tanpa spasi (disarankan pakai garis bawah _).

4. Ubah detail acara (Tanggal, Waktu, Lokasi, Teks) di dalam HTML.

5. Upload HTML tersebut ke Hosting Klien/Subdomain.

Fase 3: Pengumpulan Data

1. Tamu membuka undangan web.

2. Saat tamu mengisi buku tamu, Frontend akan mengirim (POST) payload JSON berisi: nama, kehadiran, ucapan, dan sheet (yaitu nilai dari EVENT_NAME).

3. Backend menerima request. Karena nilai sheet = Wisuda_SDITFI2_2026, Backend mengecek ke spreadsheet: "Apakah tab Wisuda_SDITFI2_2026 ada?"

4. Jika tidak ada, tab dibuat otomatis, lalu data tamu dimasukkan.

5. Administrator cukup membuka 1 file Google Sheets untuk memantau ratusan acara, cukup dengan berpindah-pindah tab (sheet) di bagian bawah.

6. Panduan Instalasi & Deployment (Teknis)

Berikut adalah petunjuk teknis langkah demi langkah untuk menginstal sistem ini.

6.1. Setup Mesin Induk (Backend GAS)

1. Buka browser dan akses script.google.com.

2. Login menggunakan akun Google (Gmail), lalu klik tombol "New Project".

3. Di dalam editor, hapus semua kode bawaan pada file Code.gs.

4. Copy seluruh kode Backend API Multi-Event dan paste ke dalam Code.gs.

5. Tekan Ctrl+S (atau Command+S di Mac) untuk menyimpan, lalu ubah nama proyek (misal: "API Undangan Multi-Event GEMS").

6.2. Inisialisasi Database

1. Pada editor Apps Script, perhatikan dropdown fungsi di bagian atas (sebelah tombol "Run").

2. Pilih fungsi initialSetup.

3. Klik tombol "Run" (Jalankan).

4. Otorisasi Keamanan: - Klik Review permissions pada pop-up yang muncul.

• Pilih akun Google Anda.

• Klik Advanced (Lanjutan) di bagian bawah peringatan keamanan.

• Klik Go to [Nama Proyek Anda] (unsafe).

• Klik Allow (Izinkan).

5. Script akan berjalan dan otomatis membuat satu file Spreadsheet Master di Google Drive Anda.

6.3. Publikasi API (Deployment)

1. Di pojok kanan atas, klik tombol biru "Deploy" lalu pilih "New deployment".

2. Klik ikon roda gigi ⚙️ di sebelah "Select type", centang "Web app".

3. Konfigurasi dengan pengaturan berikut:

• Description: (Opsional) Ketik "Mesin Induk v1"

• Execute as: Pilih "Me" (Email Anda)

• Who has access: Pilih "Anyone" (Siapa saja)

4. Klik tombol "Deploy".

5. Salin Web app URL yang muncul. URL ini adalah kunci API yang akan digunakan pada seluruh frontend.

6.4. Setup Frontend (Hosting Eksternal)

1. Siapkan file index.html (Frontend Multi-Event).

2. Buka file tersebut menggunakan Code Editor (VS Code, Notepad++, dll).

3. Cari bagian konfigurasi di dalam tag <script> (umumnya di bawah).

4. Ganti nilai GAS_API_URL dengan Web app URL yang Anda salin dari langkah 6.3.

5. Ganti nilai EVENT_NAME dengan nama acara yang sedang dibuat (misal: Wisuda_Angkatan_5).

6. Unggah (upload) file HTML tersebut ke layanan hosting pilihan Anda (cPanel, Vercel, Netlify, Github Pages, dll).

6.5. Kustomisasi Tambahan

• Cara Mengubah Nama Tamu: Tambahkan parameter ?to=Nama+Tamu di akhir URL website Anda saat membagikan tautan. (Gunakan tanda + atau %20 untuk spasi).
  Contoh: https://undangan-klien.com/?to=Bapak+Budi

• Cara Memasukkan Musik Latar:

1. Upload file lagu .mp3 ke Dropbox.

2. Salin copy link file tersebut. (Contoh: https://www.dropbox.com/s/xxxx/lagu.mp3?dl=0)

3. Ubah bagian dl=0 di akhir link menjadi raw=1.

4. Ganti link pada tag <source src="..."> di dalam elemen <audio> pada HTML Anda.

7. Pengembangan Lanjutan (Future Roadmap)

• Keamanan Ekstra: Menambahkan proteksi CORS sederhana pada Backend agar hanya menerima request dari domain hosting yang diizinkan.

• Paging/Load More: Membatasi pengambilan data (GET) ucapan terbaru menjadi maksimal 50 data untuk performa yang lebih cepat jika ucapan mencapai ribuan.

• Dashboard Admin: Membuat aplikasi panel kontrol berbasis web untuk admin membuat link ?to= secara massal dan mengelola data tamu tanpa harus membuka Google Sheets langsung.

Dokumen PRD ini disiapkan untuk standarisasi proyek pengembangan undangan digital ekosistem GEMS / IckhwanSiddiq.