Kayooh - Ultimate Self-Hosted GPS Cycling Tracker

Filosofi & Nilai Jual

Kayooh adalah aplikasi pelacak gowes mandiri (Self-Hosted) kelas Enterprise yang memberikan kedaulatan penuh atas data pribadi Anda. Dengan arsitektur hybrid terbaru yang memisahkan beban *database* lokal dan satelit *Object Storage*, Kayooh menjamin kinerja secepat kilat meski menyimpan puluhan ribu rekor gowes Anda seumur hidup.

Fitur Unggulan

✅ Kelebihan Utama & Fitur Super

🎙️ Radio Peleton (Walkie Talkie): Komunikasi suara antar peserta murni via browser dengan Native Web API. Terdapat Auto-Sweeper yang otomatis membersihkan cache audio di server agar memori selalu lega.
🗣️ Smart Voice Coach: Asisten suara pintar berbahasa Indonesia yang akan membacakan statistik jarak dan kecepatan setiap kelipatan 5 KM secara otomatis untuk menjaga fokus mata ke aspal.
Cloudflare R2 Integration: Database SQLite Anda dijamin bebas bengkak! Seluruh titik kordinat masif kini dititipkan dengan aman ke satelit Cloudflare R2 secara instan. Server PHP Anda jadi super ringan.
Universal Route Parser: Peta pintar yang mampu menerjemahkan segala jenis data secara otomatis: Sandi Strava jadul (Encoded Polyline), JSON Lokal, hingga JSON dari Cloudflare R2.
IndexedDB Black Box: Penyimpanan darurat (Black Box) kini ditenagai oleh mesin IndexedDB. Tahan banting dari resiko browser crash atau tertutup tak sengaja, data gowes Anda tak akan hilang.
Peleton Radar Sync: Mesin pengawas terpusat (radar_sync.php) yang menyatukan sinyal seluruh peserta di satu peta secara real-time. Dilengkapi fitur Auto-Clean dan Ghost Sweeper (menghapus peserta yang hilang sinyal).
Strava Mass-Sync: Mesin penyedot data (Strava Sync) dengan fitur Pagination aman yang mampu menarik ratusan sejarah gowes lawas Anda tanpa membuat server timeout atau duplikat data.
Live Tracking Telegram: Siaran posisi real-time dan notifikasi Start/Finish langsung ke grup Telegram keluarga secara hibrida untuk memastikan keselamatan Anda di jalan.
Telemetri Suhu Udara: Sensor cuaca pintar yang mengambil sampel suhu lingkungan otomatis via Open-Meteo API setiap 15 menit, lalu merata-ratakannya di akhir gowes.
Video Flexing Sinematik: Putar ulang rute gowes dalam animasi video interaktif dengan dukungan layar penuh (Fullscreen) dan visual yang adaptif terhadap Dark/Light Mode. Sangat cocok untuk direkam dan dibagikan ke media sosial.
Personal Heatmap (Live Theme): Visualisasikan seluruh "daerah kekuasaan" aspal Anda dalam satu peta bercahaya yang di-render super cepat menggunakan algoritma Asynchronous Loading dan Overlapping Opacity.
Offline GPX Extractor & Importer: Kemerdekaan mutlak dari pihak ketiga! Ekstrak file .gpx secara offline, atau impor data GPX Peleton teman ke dalam database Anda sendiri (lengkap dengan lencana 👥 Peleton).
Anti Brute-Force & Safe Logout: Gerbang login dilengkapi Database IP Blocker (memblokir IP setelah 5x gagal). Sistem Logout juga menyapu bersih cache sesi secara elegan di memori peramban.
Multi-Metrik Otomatis: Kalkulasi presisi tinggi untuk Jarak (Haversine formula), Kecepatan Maksimum, Waktu Bergerak (Moving Time), Elevasi, hingga fitur Auto-Pause cerdas saat Anda berhenti di lampu merah.

⚠️ Karakteristik & Catatan Penggunaan

Konfigurasi Cloudflare R2 (Wajib): Agar performa Kayooh bekerja 100%, Anda diwajibkan melakukan setup bucket gratis di Cloudflare R2 dan memasukkan kredensial API-nya di menu Pengaturan Kayooh.
Konsumsi Baterai Ekstra: Aplikasi ini menggunakan Wake Lock API agar layar HP terus menyala (mencegah sensor GPS tertidur oleh OS HP). Pastikan baterai Anda penuh atau bawa Powerbank untuk touring jarak jauh.
Ketergantungan Internet: Meski memori Black Box (IndexedDB) bisa merekam secara offline saat di area blank-spot, fitur tingkat lanjut seperti Radar Peleton, Live Telegram, dan penyimpanan R2 mewajibkan koneksi internet aktif, terutama di garis finish.
Sertifikat SSL (HTTPS) Mutlak: Fitur keamanan sensor Geolocation pada browser modern (Chrome/Safari) mewajibkan akses melalui HTTPS. Aplikasi tidak akan bisa membaca GPS jika diakses hanya dengan HTTP.
Akurasi GPS Bergantung pada Perangkat: Kayooh meminta izin enableHighAccuracy ke perangkat Anda. Jika cuaca sangat buruk atau HP berada jauh di dalam tas/kantong tebal, rute garis (polyline) mungkin akan sedikit melompat.

Transparansi & API Eksternal

Kayooh sangat menghargai privasi Anda. Aplikasi ini hanya mengandalkan beberapa layanan publik dan API kelas kakap untuk memaksimalkan fitur tanpa mengorbankan kedaulatan data Anda:

Cloudflare R2 Storage: Bertindak sebagai "Satelit/Gudang Kontainer" tempat jutaan titik kordinat GPS Anda bersandar dengan aman, cepat, dan tanpa membebani server hosting pribadi.
Telegram Bot API: Digunakan untuk membangun "Grup Komando", menyiarkan Live Location (Radar), dan mengirim rangkuman metrik gowes otomatis ke ruang obrolan pribadi Anda.
Open-Meteo API: Digunakan murni untuk menghitung total elevasi bukit dan mengambil sampel suhu udara lingkungan setiap 15 menit berjalan.
OSRM (Open Source Routing Machine) API: Berperan sebagai "tukang setrika" yang menempelkan titik-titik koordinat GPS Anda agar rapi mengikuti alur aspal di peta.
OpenStreetMap (OSM): Dimuat melalui library Leaflet.js sebagai kanvas visual pemetaan dasar.
CartoDB Maps API: Digunakan sebagai basemap beresolusi tinggi pada Studio Video Flexing dan Personal Heatmap untuk mengakomodasi transisi tema Dark/Light Mode secara dinamis.
Strava API: Digunakan hanya jika Anda memilih untuk melakukan "Sync Strava" secara sukarela untuk menyedot data historis.
HTML5 Fullscreen & WakeLock API: Memungkinkan Studio Video Kayooh menelan seluruh layar HP demi hasil rekaman layar yang bersih, serta menjaga layar dan sensor GPS tetap hidup menyala saat merekam gowes di aspal.

Panduan Instalasi Server (First-Time Setup)

Kayooh dirancang agar sangat ringan dan mudah di-deploy di VPS maupun Shared Hosting biasa. Berikut adalah langkah untuk menghidupkan Kayooh di server Anda:

Persyaratan Sistem: Pastikan server Anda menjalankan PHP (direkomendasikan versi 7.4 atau 8.0+) dan ekstensi SQLite3 telah diaktifkan.
Unggah File: Upload atau clone seluruh source code Kayooh ke direktori web server Anda (misal: public_html/ atau /var/www/html/).
Hak Akses (Permissions): Pastikan folder instalasi Kayooh memiliki izin tulis (writable). Sistem PHP membutuhkan izin ini (misal: chmod 755 atau chown www-data) untuk menciptakan database kayooh.sqlite serta menulis log kordinat di folder /radar_logs dan /temp.
Jalankan Installer: Buka browser Anda dan akses alamat instalasi: https://domain-anda.com/install.php
Buat Akun Kapten: Masukkan email dan kata sandi yang kuat untuk mengamankan dashboard utama Anda. Setelah berhasil, sistem akan otomatis mengunci akses instalasi demi keamanan.
Selesai! Kayooh siap digunakan. Lanjutkan ke tahap pengaturan Bot Telegram dan sinkronisasi Strava di bawah ini. (Opsional)

Panduan Live Tracking (Telegram & Peleton)

Fitur andalan Kayooh adalah kemampuannya menyiarkan lokasi Anda secara langsung ke keluarga di rumah tanpa mereka perlu menginstal aplikasi pelacak tambahan. Cukup gunakan "Grup Komando" Telegram!

Langkah 1: Membuat Bot Telegram

Buka aplikasi Telegram dan cari akun @BotFather.
Ketik perintah /newbot dan ikuti instruksi untuk memberikan nama dan username (harus diakhiri kata "bot").
Setelah selesai, @BotFather akan memberikan Bot Token API. Simpan token ini baik-baik.

Langkah 2: Membuat "Grup Komando"

Buat grup Telegram baru (misal: "Pantau Bapak Gowes") atau gunakan grup keluarga Anda yang sudah ada.
Masukkan istri, anak, rekan Peleton, dan Bot yang baru Anda buat tadi ke dalam grup tersebut.
(Opsional tapi disarankan) Jadikan bot Anda sebagai Admin grup agar lebih leluasa mengirim peta dan pesan.

Langkah 3: Mengunci Target (Chat ID)

Anda perlu mengetahui "ID" dari grup tersebut. Cara paling mudah: undang bot tambahan bernama @RawDataBot ke dalam grup Anda.
Bot itu akan merespons dengan struktur data. Cari bagian "chat": { "id": -100XXXXXXXXX }.
Catat angka tersebut! Format ID Grup Telegram biasanya selalu diawali dengan tanda minus.
(Keluarkan @RawDataBot dari grup setelah ID didapatkan agar grup kembali rapi).

Langkah 4: Menghubungkan ke Kayooh

Buka Dashboard Kayooh Anda, lalu klik ikon ⚙️ (Pengaturan) di pojok kanan atas layar.
Masukkan Bot Token API dan Chat ID Grup ke dalam form yang tersedia.
Klik SIMPAN PENGATURAN.

Langkah 5: Siap Gowes! 🚀

Sekarang, Anda tidak perlu repot lagi! Buka Dashboard Kayooh, lalu pilih mode gowes Anda:

Single Ride: Klik 🚀 SOLO. Peta Live Location dan notifikasi otomatis akan langsung muncul di Grup Telegram keluarga Anda!
Mode Peleton: Klik 👥 PELETON. Anda bisa membagikan Link Radar Web ke teman-teman gowes. Titik Anda dan titik teman-teman Anda akan muncul bersamaan di satu peta khusus.
Saat Anda menekan tombol Selesai, Bot Telegram akan otomatis mengirimkan rangkuman kecepatan, jarak, elevasi, suhu, beserta gambar keren pamer ke grup tersebut!

Panduan Mode Peleton (Co-Gowes) & Auto-Flexing

Mode Peleton adalah fitur "Sultan" di Kayooh. Kapten (Host) dapat menyatukan titik lokasi teman-teman (Guest) dalam satu layar Radar. Kerennya lagi, perangkat Guest akan menghitung statistiknya sendiri secara mandiri!

Langkah 1: Inisiasi oleh Kapten (Host)

Buka Dashboard Kayooh, klik tombol 👥 PELETON.
Sistem akan otomatis men-generate 6 digit Room ID unik (atau Anda bisa mengetikkan nama Room sendiri).
Klik tombol 🔗 COPY LINK di dalam layar perekaman, lalu bagikan tautan tersebut ke grup obrolan (WA/Telegram) teman-teman gowes Anda.
Klik tombol hijau ▶️ MULAI GOWES PELETON untuk mulai merekam aktivitas.

Langkah 2: Bergabung ke Radar (Guest)

Peserta (Guest) cukup mengklik tautan Radar yang dibagikan Kapten (tidak perlu mendaftar akun atau instal aplikasi).
Masukkan nama panggilan (maksimal 15 huruf), lalu klik 🚀 MULAI TRACKING.
Browser Guest akan secara ajaib menghitung jarak tempuh pribadi di latar belakang sekaligus memancarkan kordinat ke server Kapten.
⚠️ Penting: Pastikan layar HP dibiarkan menyala agar sensor GPS maksimal!

Langkah 3: Akhiri, Simpan Peserta, & Flexing Ekosistem!

Setelah sampai di garis finish, Kapten menekan tombol 🏁 SELESAI GOWES PELETON.
Sistem akan memunculkan prompt otomatis. Konfirmasi nama-nama peserta untuk disimpan permanen ke riwayat Kapten. Kayooh akan langsung memecah kordinat (Chunking) dan mengirimkannya ke satelit R2!
Bonus Untuk Guest: Sesaat setelah Kapten menekan tombol selesai, di layar Guest akan otomatis memunculkan tombol "📥 AMANKAN GPX SAYA". Guest dapat mengunduh file GPX rute mandirinya yang sudah tertanam Sandi Rahasia Peleton. Saat GPX ini diunggah ke server Kayooh miliknya sendiri, riwayat Peleton akan otomatis sinkron!

Langkah 4: Komunikasi Radio Peleton 🎙️

Di layar perekaman Peleton, perhatikan panel radio di pojok kanan bawah.
Tekan dan tahan tombol merah "🎤 TAHAN UNTUK BICARA", ucapkan pesan Anda, lalu lepaskan.
Sistem akan mengirimkan voice note ke seluruh anggota Peleton. Perangkat mereka akan membunyikan notifikasi "Ping!" dan pesan bisa diputar manual agar tidak mengagetkan saat gowes.

Panduan Lengkap API Strava

Agar Kayooh bisa menarik data lama Anda dari Strava, Anda perlu mendaftarkan aplikasi di portal pengembang Strava:

Langkah 1: Membuat Aplikasi API

Login ke akun Strava Anda di PC/Laptop.
Buka halaman My API Application: strava.com/settings/api.
Isi formulir pembuatan aplikasi sebagai berikut:
- Application Name: Contoh: "Kayooh"
- Category: Pilih "Visualizer" atau "Other"
- Website: Isi dengan URL domain Kayooh Anda (misal: https://jomokerto.web.id)
- Application Description: Contoh: "Self-hosted cycling tracker for personal use"
- Authorization Callback Domain: PENTING! Isi dengan nama domain saja tanpa https dan tanpa folder (misal: jomokerto.web.id)
Klik Create. Jika diminta mengunggah ikon, unggah gambar apa saja berukuran persegi.

Langkah 2: Mendapatkan Kredensial

Setelah aplikasi dibuat, Anda akan melihat halaman ringkasan aplikasi.
Catat Client ID dan Client Secret yang muncul. Jangan berikan kode ini kepada siapapun!

Langkah 3: Menghubungkan ke Kayooh

Buka Dashboard Kayooh Anda, lalu klik tombol 🧡 SYNC di deretan menu atas.
Masukkan Client ID dan Client Secret tadi ke form, lalu klik SIMPAN PENGATURAN.
Klik tombol 🔑 Dapatkan Token Sakti. Berikan izin akses pada halaman Strava yang muncul.
Setelah kembali ke Kayooh, klik SINKRONISASI SEKARANG untuk mulai mengimpor data sejarah gowes Anda.

Panduan Setup Cloudflare R2 (Penyimpanan Media)

Untuk menyimpan foto share peta dan sinkronisasi rute tanpa membebani hardisk VPS/Hosting Anda, Kayooh mendukung integrasi penuh dengan Cloudflare R2 (Gratis 10GB/bulan).

Langkah 1: Membuat Bucket R2

Login ke dashboard Cloudflare.
Pilih menu R2 di sidebar kiri, lalu klik Create bucket.
Beri nama bucket Anda (misal: kayooh-media), lalu klik Create bucket.
(Opsional) Di menu Settings bucket, aktifkan Public Access (Custom Domains) agar gambar bisa diakses publik.

Langkah 2: Mengatur CORS Policy (SANGAT PENTING!) ⚠️

Masuk ke dalam bucket yang baru dibuat, pilih tab Settings.
Scroll ke bawah ke bagian CORS Policy, lalu klik Add CORS policy (atau Edit).
Hapus teks yang ada, lalu paste kode JSON sakti ini:

[
  {
    "AllowedOrigins": [
      "http://localhost*",
      "https://domain-kayooh-anda.com"
    ],
    "AllowedMethods": [
      "GET",
      "PUT",
      "POST",
      "DELETE",
      "HEAD"
    ],
    "AllowedHeaders": [
      "*"
    ]
  }
]

*Catatan: Ganti https://domain-kayooh-anda.com dengan domain web Kayooh Anda (tanpa garis miring di belakang).

Langkah 3: Mendapatkan Kredensial API

Kembali ke menu utama R2, klik Manage R2 API Tokens di sebelah kanan atas.
Klik Create API token. Beri nama (misal: "Kayooh Token").
Pada bagian Permissions, pilih Object Read & Write. Klik Create.
Catat Access Key ID, Secret Access Key, dan URL Endpoint S3 API.
Masukkan ketiga data tersebut ke menu Pengaturan Kayooh di Dashboard Anda. Selesai!