Dokumentasi Teknis

Panduan Instalasi PikoCS (Composer)
& Cara Menyisipkan WA Bubble ke Web Klien

PikoCS dibangun dengan CodeIgniter 4.7.5, target runtime PHP 8.3.28 dan MySQL 8.4.7. Ikuti 6 langkah di bawah — dari composer install sampai widget WhatsApp mengambang tampil di website klien Anda.

PHP 8.3.28 MySQL 8.4.7 CodeIgniter 4.7.5 Composer 2.x ±15 menit selesai

0 Persyaratan Server

PikoCS berjalan di VPS, cloud instance, shared hosting modern, atau Docker. Spesifikasi minimum:

Software

PHP 8.3 (direkomendasikan 8.3.28) dengan ekstensi: intl, mbstring, curl, json, xml, mysqlnd, zip
MySQL 8.4.7 (atau MariaDB 10.11+ kompatibel)
Composer 2.x untuk dependensi PHP
Web server Apache (mod_rewrite) / Nginx, atau php spark serve untuk dev

Hardware minimum

1 vCPU / 1 GB RAM (nyaman: 2 vCPU / 2 GB)
Disk 2 GB (log chat tumbuh ± 1 MB per 1.000 pesan)
Akses keluar HTTPS ke pikoai.gayamapp.cloud (gateway AI)
Sertifikat SSL (Let's Encrypt gratis) — wajib untuk widget di web klien

Cek versi cepat: php -v, mysql --version, composer -V. Debian/Ubuntu: sudo apt install php8.3-cli php8.3-mysql php8.3-intl php8.3-mbstring php8.3-curl php8.3-xml php8.3-zip mysql-server composer

1 Install dengan Composer

Unduh paket PikoCS (zip dari vendor atau repositori Git Anda), ekstrak, lalu install dependensi — CodeIgniter 4.7.5 akan ditarik otomatis sesuai composer.lock:

# masuk ke folder proyek PikoCS cd pikocs # install seluruh dependensi (CI 4.7.5 dsb.) composer install --no-dev --optimize-autoloader # bila proyek berasal dari git tanpa vendor/ composer update --no-dev # verifikasi versi framework yang terpasang composer show codeigniter4/framework | grep versions # → versions : * v4.7.5

Ingin mulai dari kerangka CI4 baru lalu menimpa dengan kode PikoCS? Bisa juga:

composer create-project codeigniter4/appstarter:^4.7.5 pikocs cd pikocs # salin app/, public/assets/, public/bubble.js dari paket PikoCS ke proyek ini

Struktur penting proyek:

pikocs/ ├── app/ │ ├── Config/ # Routes.php, Pikoai.php, Widget.php, Database.php, Cors.php │ ├── Controllers/ # Home, Harga, Panduan, Demo, Seo, Api/{Chat,Lead,Widget} │ ├── Database/Migrations/ # widget_keys, chat_sessions, chat_messages, leads │ ├── Libraries/PikoAIClient.php # pemanggil gateway PikoAI + mode demo │ ├── Models/ # WidgetKeyModel, ChatSessionModel, dst. │ └── Views/ # layouts/, partials/, home.php, harga.php, panduan.php, demo.php ├── public/ # DOCUMENT ROOT web server! │ ├── index.php │ ├── bubble.js # ★ WA bubble untuk disisipkan ke web klien │ └── assets/ # css/js/img hasil build ├── writable/ # cache, log, session (harus bisa ditulis) └── .env # konfigurasi lingkungan (dibuat di langkah 2)

2 Konfigurasi .env

# salin template env menjadi .env cp env .env

Lalu sesuaikan bagian-bagian berikut:

# PRODUKSI: matikan debug agar error tidak bocor ke pengunjung CI_ENVIRONMENT = production # URL publik aplikasi WAJIB pakai HTTPS (widget klien butuh ini) app.baseURL = 'https://cs.domainkamu.com/' app.detectBaseURL = false # true hanya utk dev di balik tunnel/preview # Database MySQL 8.4.7 (dibuat di langkah 3) database.default.hostname = 127.0.0.1 database.default.database = pikocs database.default.username = pikocs database.default.password = GANTI_DENGAN_PASSWORD_KUAT database.default.DBDriver = MySQLi database.default.port = 3306 # Gateway AI PikoAI (langkah 4) pikoai.endpoint = 'https://pikoai.gayamapp.cloud/api/v1/chat/completions' pikoai.apiKey = 'API_KEY_KAMU' pikoai.temperature = 0.7 pikoai.maxTokens = 2048 pikoai.demoFallback = true # balas mode demo saat gateway/key bermasalah # Widget widget.vendorWaNumber = '6281200001234' # tombol "Hubungi Vendor" (Dedicated)

Jangan commit .env ke Git! File ini berisi API key & password database. Pastikan juga writable/ dapat ditulis (chmod 775, owner user web server).

3 Database MySQL 8.4.7 + Migrasi

Buat database & user khusus PikoCS (MySQL 8.4 memakai plugin autentikasi caching_sha2_password secara default — didukung driver MySQLi PHP 8.3):

sudo mysql -u root -p -- di dalam prompt mysql: CREATE DATABASE pikocs CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci; CREATE USER 'pikocs'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'GANTI_DENGAN_PASSWORD_KUAT'; GRANT ALL PRIVILEGES ON pikocs.* TO 'pikocs'@'localhost'; FLUSH PRIVILEGES; EXIT;

Jalankan migrasi (membuat 4 tabel: widget_keys, chat_sessions, chat_messages, leads) lalu seed data demo:

php spark migrate # buat semua tabel php spark migrate:status # cek sudah applied semua php spark db:seed DemoSeeder # demo key + contoh klien "Toko Batik Aruna"

Buat widget key untuk klien pertama Anda:

php spark pikocs:key --client="Toko Klien Pertama" --plan=pro --origins="https://tokoklien.com" \ --context="Katalog: Kaos polos Rp55.000, Hoodie Rp150.000. Kirim dari Bandung via J&T. COD tersedia. WhatsApp toko 0812xxxx." \ --wa=6281234567890 # Output: # ✔ Widget key berhasil dibuat untuk: Toko Klien Pertama # WIDGET_KEY : pk-3f9a2c1e-88b04d7e5a2f1c94 # Pasang di web klien (sebelum </body>): # <script src="https://cs.domainkamu.com/bubble.js" data-key="pk-3f9a2c1e-88b04d7e5a2f1c94" defer></script>

Kolom store_context = "Buku Pintar Toko" yang disuntikkan ke system prompt AI. Semakin lengkap (produk, harga, kebijakan, gaya bahasa), semakin pintar jawaban AI-nya. Bisa diupdate kapan saja langsung di tabel widget_keys.

4 API Key Gateway PikoAI

Mesin AI PikoCS adalah gateway PikoAI (kompatibel format OpenAI). Isi pikoai.apiKey di .env dengan key Anda. Uji dulu langsung dengan cURL:

curl -X POST https://pikoai.gayamapp.cloud/api/v1/chat/completions \ -H "Authorization: Bearer API_KEY_KAMU" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "Halo, perkenalkan dirimu sebagai CS toko!" } ], "temperature": 0.7, "max_tokens": 2048 }'

Key terisi → mode live

Setiap chat klien diteruskan PikoCS ke gateway PikoAI lengkap dengan persona + Buku Pintar Toko + riwayat percakapan. Jawaban AI asli, header respons X-PikoCS-Mode: live.

Key kosong / gateway error → mode fallback

Agar widget klien tidak pernah "mati", PikoCS membalas dengan mesin demo cerdas lokal (pikoai.demoFallback = true). Matikan bila ingin error tegas: set false.

5 Menjalankan Aplikasi

Development — server bawaan CI4:

php spark serve --host 0.0.0.0 --port 8080 # buka http://localhost:8080 → landing page, /harga, /panduan, /demo

Produksi (Nginx) — document root HARUS ke folder public/:

server { listen 443 ssl http2; server_name cs.domainkamu.com; root /var/www/pikocs/public; # ← folder public! index index.php; ssl_certificate /etc/letsencrypt/live/cs.domainkamu.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/cs.domainkamu.com/privkey.pem; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include fastcgi_params; fastcgi_pass unix:/run/php/php8.3-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } # bubble.js & sitemap boleh di-cache agresif location = /bubble.js { add_header Cache-Control "public, max-age=300"; } }

Produksi (Apache) — arahkan DocumentRoot vhost ke public/; .htaccess rewrite sudah tersedia di dalamnya. Aktifkan mod_rewrite dan pastikan AllowOverride All.

Setelah jalan, verifikasi cepat:

curl https://cs.domainkamu.com/robots.txt # → memuat Sitemap: curl https://cs.domainkamu.com/sitemap.xml # → XML 4 URL curl -X POST https://cs.domainkamu.com/api/v1/chat \ -H "Authorization: Bearer pk-demo-pikocs-2026" \ -H "Content-Type: application/json" \ -d '{"message":"halo, paket apa saja yang tersedia?"}' # → {"ok":true,"reply":"PikoCS punya 3 paket kak ...","mode":"live|fallback",...}

Bagian Paling Penting ⭐

6. Menyisipkan WA Bubble ke Web Klien

WA bubble adalah tombol WhatsApp hijau mengambang di pojok kanan bawah website yang, saat diklik, membuka panel chat AI PikoCS (bukan bot menu kaku). Klien cukup menempel satu baris script — semua tampilan & logika di-inject otomatis oleh bubble.js, tanpa dependensi jQuery/Bootstrap dan tanpa bentrok dengan CSS website klien.

6.1 — Snippet wajib (tempel sebelum `</body>`)

<script src="https://www.pikocs.gayamapp.cloud/bubble.js" data-key="WIDGET_KEY_KLIEN" defer></script>

Ganti WIDGET_KEY_KLIEN dengan key hasil php spark pikocs:key (langkah 3). Untuk mencoba cepat tanpa key sendiri, pakai demo key: pk-demo-pikocs-2026 — bubble di halaman PikoCS ini pun memakainya (lihat pojok kanan bawah 👇).

6.2 — Kustomisasi lewat atribut `data-*` (semua opsional)

Atribut	Default	Fungsi
data-key	— (wajib)	Widget key klien; menentukan persona AI, Buku Pintar Toko & branding
data-title	nama toko dari server	Judul header panel chat
data-greeting	salam default	Pesan pembuka otomatis dari AI saat panel dibuka
data-color	#25D366	Warna tema bubble & header (hijau WhatsApp)
data-position	right	Posisi mengambang: `right` / `left`
data-wa-number	dari server (opsional)	Menampilkan tombol "Lanjut ke WhatsApp" (deep-link wa.me) — mis. untuk order yang butuh manusia di sisi toko
data-tooltip	kosong	Tooltip ajakan di samping bubble (muncul beberapa detik)
data-server	asal URL script	Override URL server PikoCS bila bubble.js di-host terpisah (CDN klien)

6.3 — Contoh di berbagai platform

HTML statis / landing page

<body> ...isi website... <script src="https://cs.domainkamu.com/bubble.js" data-key="pk-xxxx" defer></script> </body>

WordPress

// Appearance → Theme File Editor → footer.php // (atau plugin "Insert Headers and Footers") // Tempel SEBELUM : <script src="https://cs.domainkamu.com/bubble.js" data-key="pk-xxxx" defer></script>

React / Next.js

// app/layout.jsx (Next) atau index.html <Script src="https://cs.domainkamu.com/bubble.js" data-key="pk-xxxx" strategy="afterInteractive" />

Toko online (Shopify dll.)

// Shopify: Online Store → Themes → // Edit code → layout/theme.liquid // Tempel sebelum : <script src="https://cs.domainkamu.com/bubble.js" data-key="pk-xxxx" defer></script>

6.4 — Checklist setelah pemasangan

Bubble hijau muncul di pojok kanan bawah (mobile: panel jadi full-width bottom sheet).
Klik bubble → greeting AI tampil → kirim pesan uji → dibalas < 5 detik. Badge kecil di footer panel menunjukkan mode live (gateway PikoAI) atau demo.
Riwayat chat pengunjung tetap ada saat refresh (session token di localStorage browser mereka).
Cek di database Anda: baris baru muncul di chat_sessions & chat_messages.
Domain klien sudah didaftarkan di widget_keys.allowed_origins (atau set *).

7 Referensi API Chat AI

Widget memakai satu endpoint utama. Anda juga bisa memakainya langsung (mis. integrasi WhatsApp Cloud API webhook sendiri):

POST https://www.pikocs.gayamapp.cloud/api/v1/chat

Header

Authorization: Bearer WIDGET_KEY_KLIEN Content-Type: application/json Origin: https://tokoklien.com # dicek terhadap allowed_origins

Body request

{ "message": "kak, hoodie ukuran L ready? ongkir ke Medan berapa?", "session_token": "sess-...", // opsional; dikembalikan respons pertama "history": [ // opsional; dipakai bila DB server mati { "role": "user", "content": "halo" }, { "role": "assistant", "content": "halo kak! ada yang bisa dibantu?" } ] }

Respons 200

{ "ok": true, "reply": "Ready kak! Hoodie L tersisa 4 pcs. Ongkir ke Medan via J&T Rp21.000 (2-3 hari)...", "session_token": "sess-1a2b3c...", "mode": "live", // live = gateway PikoAI | fallback = mode demo "latency_ms": 2140, "server_time": "2026-10-31T14:03:22+07:00" }

Kode error

401 widget key tidak ada / nonaktif • 403 origin tidak diizinkan
422 message kosong / kepanjangan • 429 rate limit (20/menit) atau kuota paket habis
502 gateway AI gagal & demoFallback=false

Endpoint pendukung lain:

GET /api/v1/widget/config?key=pk-xxxx # branding publik widget (nama toko, greeting, warna, nomor WA) POST /api/v1/lead # form pendaftaran trial/konsultasi (JSON) GET /sitemap.xml • GET /robots.txt # SEO

8 Troubleshooting

Bubble tidak muncul di web klien

Cek: (1) script berada sebelum </body>, (2) URL bubble.js bisa dibuka langsung di browser, (3) tidak ada CSP yang memblokir script eksternal, (4) ad-blocker — whitelist domain. Lihat Console browser (F12) untuk error pemuatan.

Bubble muncul tapi chat error 401

Widget key salah/nonaktif. Cek tabel widget_keys (is_active=1). Demo key bawaan: pk-demo-pikocs-2026.

Chat error 403 di web klien

Origin domain klien tidak terdaftar. Update widget_keys.allowed_origins — pisahkan dengan koma, atau isi * untuk semua domain.

Jawaban selalu "mode demo/fallback"

pikoai.apiKey di .env kosong, atau server tidak bisa keluar ke https://pikoai.gayamapp.cloud (cek firewall/DNS), atau key ditolak gateway (401/403). Uji dengan cURL langkah 4 dan lihat writable/logs/log-*.php.

php spark migrate gagal konek

Cek kredensial .env, pastikan MySQL 8.4.7 berjalan (systemctl status mysql), user punya GRANT ke database pikocs, dan host 127.0.0.1:3306 benar (bukan socket / TCP mismatch).

Halaman 404 semua kecuali beranda

Rewrite web server belum jalan. Apache: aktifkan mod_rewrite + AllowOverride All. Nginx: pastikan try_files $uri $uri/ /index.php?$query_string ada dan document root ke public/.

CORS error di console browser klien

Filter CORS PikoCS mengizinkan semua origin untuk /api/v1/*. Bila Anda mengubah Config/Cors.php, pastikan allowedOrigins memuat * atau pola domain klien, lalu restart php-fpm.

AI lambat menjawab

Normalnya 2–6 detik (tergantung gateway). Naikkan pikoai.timeout bila jaringan server lambat, dan pastikan server punya outbound HTTPS latency rendah ke gateway.

Server Siap, AI Siap, Toko Anda Siap 24/7 🚀

Setelah instalasi selesai, aktifkan paket dan biarkan AI PikoCS bekerja sementara Anda fokus membesarkan bisnis.

Lihat Harga (mulai Rp49rb)