Colota - Android GPS Location tracker
feat: add interactive deep link generator to setup docs page
Max Dietrich140323e2c7ef
diff --git a/apps/docs/docs/guides/deep-link-setup.md b/apps/docs/docs/guides/deep-link-setup.mdindex 006b741e..d86b5200 100644--- a/apps/docs/docs/guides/deep-link-setup.md+++ b/apps/docs/docs/guides/deep-link-setup.md@@ -2,10 +2,26 @@sidebar_position: 7---+import DeepLinkGenerator from '@site/src/components/DeepLinkGenerator'+# Deep Link SetupConfigure Colota instantly using a `colota://setup` URL. Generate a link or QR code with your server settings and share it with users - no manual typing required.+## Link Generator++Fill in the settings you want to configure. Only the fields you set will be included - everything else keeps its current value on the device. All processing happens in your browser - no data is sent to any server.++<DeepLinkGenerator />++## How It Works++1. User taps the link or scans a QR code+2. Colota opens and shows a confirmation screen listing all settings that will be applied+3. Sensitive values (passwords, tokens) are masked in the preview+4. User taps **Apply Configuration** to save or **Cancel** to discard+5. Settings are persisted and the app navigates to the Dashboard+## URL Format```@@ -14,49 +30,7 @@ colota://setup?config=BASE64_ENCODED_JSONThe `config` parameter is a base64-encoded JSON object. Only include the settings you want to change - everything else keeps its current value.-## Supported Parameters--```json-{- "endpoint": "https://my-server.com/api/locations",- "interval": 10,- "distance": 5,- "syncInterval": 300,- "retryInterval": 30,- "accuracyThreshold": 50,- "filterInaccurateLocations": true,- "isOfflineMode": false,- "syncCondition": "any",- "syncSsid": "",- "apiTemplate": "owntracks",- "httpMethod": "POST",- "fieldMap": {- "lat": "lat",- "lon": "lon",- "acc": "acc",- "alt": "alt",- "vel": "vel",- "batt": "batt",- "bs": "bs",- "tst": "tst",- "bear": "cog"- },- "customFields": [- { "key": "_type", "value": "location" },- { "key": "tid", "value": "AA" }- ],- "auth": {- "type": "bearer",- "bearerToken": "my-secret-token-123"- },- "customHeaders": {- "X-Api-Key": "abc123",- "CF-Access-Client-Id": "my-cf-id"- }-}-```--### Parameter Reference+## Parameter Reference| Parameter | Type | Description || --- | --- | --- |@@ -64,7 +38,6 @@ The `config` parameter is a base64-encoded JSON object. Only include the setting| `interval` | number | GPS polling interval in seconds (must be > 0) || `distance` | number | Minimum movement in meters before recording a new location || `syncInterval` | number | Batch sync interval in seconds (0 = instant) |-| `retryInterval` | number | Seconds between retry attempts || `accuracyThreshold` | number | Discard locations less accurate than this (meters) || `filterInaccurateLocations` | boolean | Enable accuracy filtering || `isOfflineMode` | boolean | Store locally only, never sync |@@ -80,7 +53,7 @@ The `config` parameter is a base64-encoded JSON object. Only include the setting| `auth.bearerToken` | string | Token for Bearer Auth || `customHeaders` | object | Custom HTTP headers (e.g. Cloudflare Access) |-## Generating a Setup Link+## Generating Links Programmatically### Using Node.js@@ -108,25 +81,6 @@ print(f'colota://setup?config={encoded}')"```-### QR Code--Generate a QR code from the `colota://setup?config=...` URL using any QR generator. When scanned, Android opens Colota and navigates directly to the confirmation screen.--## How It Works--1. User taps the link or scans a QR code-2. Colota opens and shows a confirmation screen listing all settings that will be applied-3. Sensitive values (passwords, tokens) are masked in the preview-4. User taps **Apply Configuration** to save or **Cancel** to discard-5. Settings are persisted and the app navigates to the Dashboard--## Testing with ADB--```bash-adb shell am start -a android.intent.action.VIEW \- -d "colota://setup?config=BASE64_HERE" com.Colota-```-## Security Notes- The configuration URL is not encrypted. Avoid putting sensitive tokens in QR codes displayed in public.diff --git a/apps/docs/src/components/DeepLinkGenerator.module.css b/apps/docs/src/components/DeepLinkGenerator.module.cssnew file mode 100644index 00000000..b0cc4bc5--- /dev/null+++ b/apps/docs/src/components/DeepLinkGenerator.module.css@@ -0,0 +1,222 @@+.generator {+ border: 1px solid var(--colota-border);+ border-radius: var(--colota-card-radius);+ background: var(--colota-card-bg);+ padding: var(--colota-card-padding);+ margin: 1.5rem 0;+}++.section {+ margin-bottom: 1.25rem;+}++.section:last-child {+ margin-bottom: 0;+}++.sectionTitle {+ font-size: 0.8rem;+ font-weight: 600;+ text-transform: uppercase;+ letter-spacing: 0.05em;+ color: var(--ifm-font-color-secondary);+ margin-bottom: 0.5rem;+}++.row {+ display: flex;+ gap: 0.75rem;+ margin-bottom: 0.5rem;+}++.row > * {+ flex: 1;+}++.field {+ display: flex;+ flex-direction: column;+ gap: 0.25rem;+ margin-bottom: 0.5rem;+}++.label {+ font-size: 0.8rem;+ font-weight: 500;+ color: var(--ifm-font-color-secondary);+}++.input,+.select {+ padding: 0.5rem 0.75rem;+ border: 1px solid var(--colota-border);+ border-radius: 8px;+ background: var(--ifm-background-color);+ color: var(--ifm-font-color-base);+ font-size: 0.875rem;+ font-family: inherit;+ width: 100%;+ box-sizing: border-box;+}++.input:focus,+.select:focus {+ outline: none;+ border-color: var(--ifm-color-primary);+ box-shadow: 0 0 0 2px rgba(13, 148, 136, 0.15);+}++.input::placeholder {+ color: var(--ifm-font-color-secondary);+ opacity: 0.6;+}++.checkbox {+ display: flex;+ align-items: center;+ gap: 0.5rem;+ margin-bottom: 0.5rem;+ font-size: 0.875rem;+ cursor: pointer;+}++.checkbox input {+ accent-color: var(--ifm-color-primary);+}++.keyValueList {+ display: flex;+ flex-direction: column;+ gap: 0.5rem;+}++.keyValueRow {+ display: flex;+ gap: 0.5rem;+ align-items: center;+}++.keyValueRow .input {+ margin-bottom: 0;+}++.removeBtn {+ background: none;+ border: none;+ color: var(--ifm-font-color-secondary);+ cursor: pointer;+ font-size: 1.1rem;+ padding: 0.25rem;+ line-height: 1;+ opacity: 0.6;+}++.removeBtn:hover {+ opacity: 1;+ color: #e53e3e;+}++.addBtn {+ background: none;+ border: 1px dashed var(--colota-border);+ border-radius: 6px;+ padding: 0.35rem 0.75rem;+ color: var(--ifm-color-primary);+ font-size: 0.8rem;+ font-weight: 500;+ cursor: pointer;+ margin-top: 0.25rem;+}++.addBtn:hover {+ background: rgba(13, 148, 136, 0.05);+ border-color: var(--ifm-color-primary);+}++.divider {+ border: none;+ border-top: 1px solid var(--colota-border);+ margin: 1rem 0;+}++.output {+ background: var(--colota-card-elevated-bg);+ border: 1px solid var(--colota-border);+ border-radius: 8px;+ padding: 0.75rem;+ word-break: break-all;+ font-family: var(--ifm-font-family-monospace);+ font-size: 0.8rem;+ color: var(--ifm-font-color-base);+ max-height: 120px;+ overflow-y: auto;+ user-select: all;+}++.actions {+ display: flex;+ gap: 0.5rem;+ margin-top: 0.75rem;+ flex-wrap: wrap;+}++.copyBtn,+.downloadBtn {+ display: inline-flex;+ align-items: center;+ gap: 0.35rem;+ padding: 0.5rem 1rem;+ border: none;+ border-radius: 8px;+ font-size: 0.85rem;+ font-weight: 500;+ cursor: pointer;+ font-family: inherit;+ transition: opacity 0.15s;+}++.copyBtn {+ background: var(--ifm-color-primary);+ color: #fff;+}++.copyBtn:hover {+ opacity: 0.9;+}++.downloadBtn {+ background: transparent;+ border: 1px solid var(--colota-border);+ color: var(--ifm-font-color-base);+}++.downloadBtn:hover {+ border-color: var(--ifm-color-primary);+}++.qrContainer {+ display: flex;+ justify-content: center;+ padding: 1rem;+ background: #fff;+ border-radius: 8px;+ margin-top: 0.75rem;+}++.qrContainer canvas {+ max-width: 200px;+ max-height: 200px;+}++.empty {+ color: var(--ifm-font-color-secondary);+ font-size: 0.85rem;+ font-style: italic;+}++@media (max-width: 600px) {+ .row {+ flex-direction: column;+ gap: 0;+ }+}diff --git a/apps/docs/src/components/DeepLinkGenerator.tsx b/apps/docs/src/components/DeepLinkGenerator.tsxnew file mode 100644index 00000000..f9ac132a--- /dev/null+++ b/apps/docs/src/components/DeepLinkGenerator.tsx@@ -0,0 +1,490 @@+import { useState, useMemo, useCallback, useRef, useEffect } from "react"+import styles from "./DeepLinkGenerator.module.css"++interface KeyValue {+ key: string+ value: string+}++const API_TEMPLATES = ["custom", "dawarich", "geopulse", "owntracks", "phonetrack", "reitti", "traccar"] as const+const AUTH_TYPES = ["none", "basic", "bearer"] as const+const SYNC_CONDITIONS = ["any", "wifi_any", "wifi_ssid", "vpn"] as const++export default function DeepLinkGenerator() {+ // Connection+ const [endpoint, setEndpoint] = useState("")+ const [apiTemplate, setApiTemplate] = useState("")+ const [httpMethod, setHttpMethod] = useState("")++ // Tracking+ const [interval, setInterval_] = useState("")+ const [distance, setDistance] = useState("")+ const [accuracyThreshold, setAccuracyThreshold] = useState("")+ const [filterInaccurateLocations, setFilterInaccurateLocations] = useState("")++ // Sync+ const [syncInterval, setSyncInterval] = useState("")+ const [isOfflineMode, setIsOfflineMode] = useState("")+ const [syncCondition, setSyncCondition] = useState("")+ const [syncSsid, setSyncSsid] = useState("")++ // Auth+ const [authType, setAuthType] = useState("")+ const [authUsername, setAuthUsername] = useState("")+ const [authPassword, setAuthPassword] = useState("")+ const [authBearerToken, setAuthBearerToken] = useState("")++ // Field map+ const [fieldMapEntries, setFieldMapEntries] = useState<KeyValue[]>([])++ // Custom fields+ const [customFields, setCustomFields] = useState<KeyValue[]>([])++ // Custom headers+ const [customHeaders, setCustomHeaders] = useState<KeyValue[]>([])++ // QR+ const qrRef = useRef<HTMLDivElement>(null)+ const [qrLib, setQrLib] = useState<any>(null)++ useEffect(() => {+ import("qrcode").then((mod) => setQrLib(mod.default || mod)).catch(() => {})+ }, [])++ const config = useMemo(() => {+ const obj: Record<string, unknown> = {}++ if (endpoint) obj.endpoint = endpoint+ if (apiTemplate) obj.apiTemplate = apiTemplate+ if (httpMethod) obj.httpMethod = httpMethod++ if (interval) obj.interval = Number(interval)+ if (distance) obj.distance = Number(distance)+ if (accuracyThreshold) obj.accuracyThreshold = Number(accuracyThreshold)+ if (filterInaccurateLocations) obj.filterInaccurateLocations = filterInaccurateLocations === "true"++ if (syncInterval) obj.syncInterval = Number(syncInterval)+ if (isOfflineMode) obj.isOfflineMode = isOfflineMode === "true"+ if (syncCondition) obj.syncCondition = syncCondition+ if (syncSsid) obj.syncSsid = syncSsid++ if (authType && authType !== "none") {+ const auth: Record<string, string> = { type: authType }+ if (authType === "basic") {+ if (authUsername) auth.username = authUsername+ if (authPassword) auth.password = authPassword+ } else if (authType === "bearer") {+ if (authBearerToken) auth.bearerToken = authBearerToken+ }+ obj.auth = auth+ } else if (authType === "none") {+ obj.auth = { type: "none" }+ }++ const fm: Record<string, string> = {}+ for (const e of fieldMapEntries) {+ if (e.key && e.value) fm[e.key] = e.value+ }+ if (Object.keys(fm).length > 0) obj.fieldMap = fm++ const cf = customFields.filter((e) => e.key && e.value)+ if (cf.length > 0) obj.customFields = cf++ const ch: Record<string, string> = {}+ for (const e of customHeaders) {+ if (e.key && e.value) ch[e.key] = e.value+ }+ if (Object.keys(ch).length > 0) obj.customHeaders = ch++ return obj+ }, [+ endpoint,+ apiTemplate,+ httpMethod,+ interval,+ distance,+ accuracyThreshold,+ filterInaccurateLocations,+ syncInterval,+ isOfflineMode,+ syncCondition,+ syncSsid,+ authType,+ authUsername,+ authPassword,+ authBearerToken,+ fieldMapEntries,+ customFields,+ customHeaders+ ])++ const isEmpty = Object.keys(config).length === 0++ const deepLink = useMemo(() => {+ if (isEmpty) return ""+ const encoded = btoa(JSON.stringify(config))+ return `colota://setup?config=${encoded}`+ }, [config, isEmpty])++ // QR code rendering+ useEffect(() => {+ if (!qrRef.current || !qrLib || !deepLink) {+ if (qrRef.current) qrRef.current.innerHTML = ""+ return+ }++ const canvas = document.createElement("canvas")+ qrLib.toCanvas(canvas, deepLink, { width: 200, margin: 2 }, (err: Error | null) => {+ if (!err && qrRef.current) {+ qrRef.current.innerHTML = ""+ qrRef.current.appendChild(canvas)+ }+ })+ }, [deepLink, qrLib])++ const [copyFeedback, setCopyFeedback] = useState(false)+ const [downloadFeedback, setDownloadFeedback] = useState(false)++ const copyLink = useCallback(() => {+ navigator.clipboard.writeText(deepLink)+ setCopyFeedback(true)+ setTimeout(() => setCopyFeedback(false), 2000)+ }, [deepLink])++ const downloadJson = useCallback(() => {+ const blob = new Blob([JSON.stringify(config, null, 2)], { type: "application/json" })+ const url = URL.createObjectURL(blob)+ const a = document.createElement("a")+ a.href = url+ a.download = "colota-config.json"+ a.click()+ URL.revokeObjectURL(url)+ setDownloadFeedback(true)+ setTimeout(() => setDownloadFeedback(false), 2000)+ }, [config])++ const updateKV = (+ list: KeyValue[],+ setList: (v: KeyValue[]) => void,+ index: number,+ field: "key" | "value",+ val: string+ ) => {+ const next = [...list]+ next[index] = { ...next[index], [field]: val }+ setList(next)+ }++ const removeKV = (list: KeyValue[], setList: (v: KeyValue[]) => void, index: number) => {+ setList(list.filter((_, i) => i !== index))+ }++ return (+ <div className={styles.generator}>+ {/* Connection */}+ <div className={styles.section}>+ <div className={styles.sectionTitle}>Connection</div>+ <div className={styles.field}>+ <label className={styles.label}>Endpoint URL</label>+ <input+ className={styles.input}+ type="url"+ placeholder="https://my-server.com/api/locations"+ value={endpoint}+ onChange={(e) => setEndpoint(e.target.value)}+ />+ </div>+ <div className={styles.row}>+ <div className={styles.field}>+ <label className={styles.label}>API Template</label>+ <select className={styles.select} value={apiTemplate} onChange={(e) => setApiTemplate(e.target.value)}>+ <option value="">-- not set --</option>+ {API_TEMPLATES.map((t) => (+ <option key={t} value={t}>+ {t}+ </option>+ ))}+ </select>+ </div>+ <div className={styles.field}>+ <label className={styles.label}>HTTP Method</label>+ <select className={styles.select} value={httpMethod} onChange={(e) => setHttpMethod(e.target.value)}>+ <option value="">-- not set --</option>+ <option value="POST">POST</option>+ <option value="GET">GET</option>+ </select>+ </div>+ </div>+ </div>++ {/* Tracking */}+ <div className={styles.section}>+ <div className={styles.sectionTitle}>Tracking</div>+ <div className={styles.row}>+ <div className={styles.field}>+ <label className={styles.label}>Interval (seconds)</label>+ <input+ className={styles.input}+ type="number"+ min="1"+ placeholder="e.g. 10"+ value={interval}+ onChange={(e) => setInterval_(e.target.value)}+ />+ </div>+ <div className={styles.field}>+ <label className={styles.label}>Distance (meters)</label>+ <input+ className={styles.input}+ type="number"+ min="0"+ placeholder="e.g. 5"+ value={distance}+ onChange={(e) => setDistance(e.target.value)}+ />+ </div>+ </div>+ <div className={styles.row}>+ <div className={styles.field}>+ <label className={styles.label}>Accuracy threshold (meters)</label>+ <input+ className={styles.input}+ type="number"+ min="0"+ placeholder="e.g. 50"+ value={accuracyThreshold}+ onChange={(e) => setAccuracyThreshold(e.target.value)}+ />+ </div>+ <div className={styles.field}>+ <label className={styles.label}>Filter inaccurate locations</label>+ <select+ className={styles.select}+ value={filterInaccurateLocations}+ onChange={(e) => setFilterInaccurateLocations(e.target.value)}+ >+ <option value="">-- not set --</option>+ <option value="true">Enabled</option>+ <option value="false">Disabled</option>+ </select>+ </div>+ </div>+ </div>++ {/* Sync */}+ <div className={styles.section}>+ <div className={styles.sectionTitle}>Sync</div>+ <div className={styles.row}>+ <div className={styles.field}>+ <label className={styles.label}>Sync interval (seconds)</label>+ <input+ className={styles.input}+ type="number"+ min="0"+ placeholder="0 = instant"+ value={syncInterval}+ onChange={(e) => setSyncInterval(e.target.value)}+ />+ </div>+ </div>+ <div className={styles.row}>+ <div className={styles.field}>+ <label className={styles.label}>Sync condition</label>+ <select className={styles.select} value={syncCondition} onChange={(e) => setSyncCondition(e.target.value)}>+ <option value="">-- not set --</option>+ {SYNC_CONDITIONS.map((c) => (+ <option key={c} value={c}>+ {c}+ </option>+ ))}+ </select>+ </div>+ {syncCondition === "wifi_ssid" && (+ <div className={styles.field}>+ <label className={styles.label}>Wi-Fi SSID</label>+ <input+ className={styles.input}+ placeholder="MyNetwork"+ value={syncSsid}+ onChange={(e) => setSyncSsid(e.target.value)}+ />+ </div>+ )}+ </div>+ <div className={styles.field}>+ <label className={styles.label}>Offline mode</label>+ <select className={styles.select} value={isOfflineMode} onChange={(e) => setIsOfflineMode(e.target.value)}>+ <option value="">-- not set --</option>+ <option value="true">Enabled</option>+ <option value="false">Disabled</option>+ </select>+ </div>+ </div>++ {/* Auth */}+ <div className={styles.section}>+ <div className={styles.sectionTitle}>Authentication</div>+ <div className={styles.field}>+ <label className={styles.label}>Auth type</label>+ <select className={styles.select} value={authType} onChange={(e) => setAuthType(e.target.value)}>+ <option value="">-- not set --</option>+ {AUTH_TYPES.map((t) => (+ <option key={t} value={t}>+ {t}+ </option>+ ))}+ </select>+ </div>+ {authType === "basic" && (+ <div className={styles.row}>+ <div className={styles.field}>+ <label className={styles.label}>Username</label>+ <input className={styles.input} value={authUsername} onChange={(e) => setAuthUsername(e.target.value)} />+ </div>+ <div className={styles.field}>+ <label className={styles.label}>Password</label>+ <input+ className={styles.input}+ type="password"+ value={authPassword}+ onChange={(e) => setAuthPassword(e.target.value)}+ />+ </div>+ </div>+ )}+ {authType === "bearer" && (+ <div className={styles.field}>+ <label className={styles.label}>Bearer token</label>+ <input+ className={styles.input}+ type="password"+ placeholder="my-secret-token"+ value={authBearerToken}+ onChange={(e) => setAuthBearerToken(e.target.value)}+ />+ </div>+ )}+ </div>++ {/* Custom Headers */}+ <div className={styles.section}>+ <div className={styles.sectionTitle}>Custom Headers</div>+ <div className={styles.keyValueList}>+ {customHeaders.map((entry, i) => (+ <div key={i} className={styles.keyValueRow}>+ <input+ className={styles.input}+ placeholder="Header name"+ value={entry.key}+ onChange={(e) => updateKV(customHeaders, setCustomHeaders, i, "key", e.target.value)}+ />+ <input+ className={styles.input}+ placeholder="Value"+ value={entry.value}+ onChange={(e) => updateKV(customHeaders, setCustomHeaders, i, "value", e.target.value)}+ />+ <button className={styles.removeBtn} onClick={() => removeKV(customHeaders, setCustomHeaders, i)}>+ x+ </button>+ </div>+ ))}+ </div>+ <button className={styles.addBtn} onClick={() => setCustomHeaders([...customHeaders, { key: "", value: "" }])}>+ + Add header+ </button>+ </div>++ {/* Custom Fields */}+ <div className={styles.section}>+ <div className={styles.sectionTitle}>Custom Fields</div>+ <div className={styles.keyValueList}>+ {customFields.map((entry, i) => (+ <div key={i} className={styles.keyValueRow}>+ <input+ className={styles.input}+ placeholder="Key"+ value={entry.key}+ onChange={(e) => updateKV(customFields, setCustomFields, i, "key", e.target.value)}+ />+ <input+ className={styles.input}+ placeholder="Value"+ value={entry.value}+ onChange={(e) => updateKV(customFields, setCustomFields, i, "value", e.target.value)}+ />+ <button className={styles.removeBtn} onClick={() => removeKV(customFields, setCustomFields, i)}>+ x+ </button>+ </div>+ ))}+ </div>+ <button className={styles.addBtn} onClick={() => setCustomFields([...customFields, { key: "", value: "" }])}>+ + Add field+ </button>+ </div>++ {/* Field Map */}+ <div className={styles.section}>+ <div className={styles.sectionTitle}>Field Map</div>+ <div className={styles.keyValueList}>+ {fieldMapEntries.map((entry, i) => (+ <div key={i} className={styles.keyValueRow}>+ <input+ className={styles.input}+ placeholder="Source field (e.g. lat)"+ value={entry.key}+ onChange={(e) => updateKV(fieldMapEntries, setFieldMapEntries, i, "key", e.target.value)}+ />+ <input+ className={styles.input}+ placeholder="Mapped name"+ value={entry.value}+ onChange={(e) => updateKV(fieldMapEntries, setFieldMapEntries, i, "value", e.target.value)}+ />+ <button className={styles.removeBtn} onClick={() => removeKV(fieldMapEntries, setFieldMapEntries, i)}>+ x+ </button>+ </div>+ ))}+ </div>+ <button+ className={styles.addBtn}+ onClick={() => setFieldMapEntries([...fieldMapEntries, { key: "", value: "" }])}+ >+ + Add mapping+ </button>+ </div>++ {/* Output */}+ <hr className={styles.divider} />++ {isEmpty ? (+ <p className={styles.empty}>Fill in at least one field above to generate a setup link.</p>+ ) : (+ <>+ <div className={styles.sectionTitle}>Generated Link</div>+ <div className={styles.output}>{deepLink}</div>++ <div className={styles.actions}>+ <button className={styles.copyBtn} onClick={copyLink}>+ {copyFeedback ? "Copied!" : "Copy link"}+ </button>+ <button className={styles.downloadBtn} onClick={downloadJson}>+ {downloadFeedback ? "Downloaded!" : "Download JSON"}+ </button>+ </div>++ {qrLib && (+ <>+ <div className={styles.sectionTitle} style={{ marginTop: "1rem" }}>+ QR Code+ </div>+ <div className={styles.qrContainer} ref={qrRef} />+ </>+ )}+ </>+ )}+ </div>+ )+}