Changelog

​

Updated NPM package documentation

​

Critical alerts

• Android. Critical alerts work out of the box with no additional configuration required.
• iOS. Critical alerts require the Critical Alerts entitlement from Apple. Once granted, enable them in the Despia dashboard under App - Integrations - OneSignal - Critical Alerts, then rebuild a new version in Despia to activate the capability.

​

PowerSync schema configuration

• Schema definition in connect. Pass a schema object directly to db.connect() alongside fetchToken and url. Each key is a table name, each value declares the columns and optional indexes for that table.
• Column type mapping. Columns are typed as 'text', 'integer', or 'real', mapping directly to SQLite affinity types.
• Optional indexes. Each table accepts an optional indexes map of index name to an array of column names, allowing the sync engine to optimise queries at the schema level.
• Updated TypeScript types. ConnectOptions now includes schema: PowerSyncSchema as a required field. The PowerSyncSchema type is exported directly from @despia/powersync.

await db.connect({
    fetchToken: async () => {
        const res = await fetch('/api/powersync-token')
        const { token } = await res.json()
        return token
    },
    url: 'https://YOUR_POWERSYNC_INSTANCE',
    schema: {
        users: {
            columns: {
                id: 'integer',
                email: 'text',
            },
        },
        todos: {
            columns: {
                id: 'integer',
                title: 'text',
                done: 'integer',
            },
            indexes: {
                byDone: ['done'],
            },
        },
    },
})

• @despia/powersync@1.1.0

​

Apple Health realtime observer

• Observer registration. Call healthkit://observe with a comma-separated list of identifiers, a delivery frequency, and a server URL. Despia registers a native HKObserverQuery for each type and enables background delivery via iOS background task APIs.
• Webhook delivery. On every HealthKit update, Despia fetches the latest day of data for the changed type and POSTs it to your server as JSON with event, userId, timestamp, and data fields.
• Configurable frequency. Set frequency to immediate, hourly, daily, or weekly to control how aggressively the OS wakes the app to deliver updates.
• Observer persistence. Active observers are saved to device storage and restored automatically when the app restarts - no re-registration required.
• Observer state. despia.observingHealthKit reflects the current array of active identifier strings. It updates after every observe or unobserve call.
• Selective stop. Call healthkit://unobserve?types=all to stop all observers, or pass specific identifiers to stop individual types.
• User identification. Append your own user ID as a query parameter on the server URL (e.g. ?user=abc123) to route webhook events directly to the right user record on your server without device ID mapping.

• despia-native

​

Movement-based location tracking

• Distance-triggered updates. Set movement to a distance in centimetres to receive a GPS point every time the device crosses that threshold. Use movement=100 for 1-metre precision, suited to running, cycling, and navigation use cases.
• Combined buffer and movement. buffer and movement run simultaneously. movement drives updates as the user moves, and buffer acts as a heartbeat fallback when the device is stationary or movement updates are sparse.
• Same location object shape. Movement-triggered points are delivered to window.onLocationChange, stored in the local session, and POSTed to the server endpoint using the same object shape as time-based points. No handling changes are required.

despia("location://?buffer=60&movement=100")

​

HealthKit workout quantity identifiers

• Workout quantity identifiers. Apps can now reference quantity-type identifiers tied to specific workout activities, such as active energy burned, distance, step count, and other measurable outputs produced during a workout session.
• Quantity type resolution. The SDK resolves each workout identifier to its underlying HKQuantityType automatically, so apps receive correctly typed samples without manual type mapping.

​

Apple Sign In

• iOS native - native Face ID sheet. On iOS, the Apple JS SDK with usePopup: true opens the native Face ID / Apple ID sheet directly inside WKWebView. No oauth:// bridge is needed on iOS. The id_token is returned to your JavaScript callback with no page redirect, which avoids the blank white screen that causes App Store rejection when using a redirect-based flow.
• Android native - oauth:// bridge. On Android, the oauth:// bridge opens Chrome Custom Tabs for the Apple OAuth flow. public/native-callback.html receives the id_token and code in the URL hash and fires the deeplink to close the tab. The oauth/ prefix in the deeplink is required.
• Web - Apple JS SDK popup. On web, the Apple JS SDK popup returns the id_token directly to your JavaScript callback. No redirect flow is used.
• Two response mode options for Android. The fragment mode redirects the browser directly to native-callback.html with #id_token in the hash - no backend POST handler needed. The form_post mode sends code, id_token, state, and user (name and email JSON, first login only) to your backend, which validates and redirects to native-callback.html with a session token.
• Plain HTML callback file. public/native-callback.html is recommended over a React component for the callback page. React Router can strip the #id_token hash fragment on route change, causing tokens to disappear. The plain HTML file bypasses React Router entirely and reads the hash directly from the browser. Chrome Custom Tabs hides the URL bar, so the .html extension is never visible to users.
• React, Vue, Vanilla JS, and HTML auth page examples. All auth page examples include the searchParams dependency array fix to handle the already-mounted page problem, where the deeplink updates the URL without remounting the component and the token handler never re-runs.

• despia-native

​

AppsFlyer integration

• Install attribution. The native AppsFlyer SDK is initialised automatically at launch on both iOS and Android. Attribution data is captured at install time, cached on-device, and injected into your web layer on every page load via despia.appsFlyerAttribution, despia.appsFlyerReferrer, and despia.appsFlyerUID. No setup code required.
• Normalised referrer string. despia.appsFlyerReferrer provides a clean source string on every load - values like tiktok_ad, facebook_organic, google_ad, and organic - ready to use for onboarding personalisation and funnel branching without any parsing.
• Deep linking. When a user opens the app via a campaign or creator OneLink URL, Despia resolves the deep link natively and navigates the WebView to the correct path automatically. deep_link_value maps directly to a route in your web app. No navigation code required from the web layer for fresh launches.
• Re-engagement callback. For users who already have the app installed and tap a campaign link while the app is open, Despia calls window.onAppsFlyerDeepLink(data) with the full click event payload so your app can respond without a full page reload.
• Creator and affiliate links. Deep link params support deep_link_sub1 through deep_link_sub5 for creator codes and affiliate IDs. Each creator can receive a unique OneLink URL. Attribution, commission tracking, and welcome personalisation are available from the same payload.
• Event bridge. In-app events are forwarded from your web layer to the native AppsFlyer SDK via despia("appsflyer://log_event?..."). Standard af_ prefixed events map automatically to Meta and TikTok conversion events in their dashboards. Custom events appear in the AppsFlyer dashboard for funnel and retention analysis.
• User identification. set_user_id, set_email, and set_phone are all supported. Emails and phone numbers are hashed with SHA256 automatically before transmission.
• GDPR consent. set_consent accepts is_gdpr and has_consent params and passes them directly to the AppsFlyer SDK consent API.
• On-demand data retrieval. Both get_uid and get_attribution support an await pattern - await despia("appsflyer://get_uid", ["appsFlyerUID"]) - for cases where you need the value immediately in the same execution flow.
• Ad revenue tracking. Coming soon - despia("appsflyer://log_ad_revenue?...") will allow impression-level revenue reporting back to AppsFlyer from Meta, TikTok, and AdMob to enable LTV and ROAS reporting per acquisition channel.

• despia-native

​

Local CDN - query all cached files

• localcdn://query. Calling await despia('localcdn://query', ['cdnItems']) returns the full cdnItems array containing every file currently in the local cache, across all folders.
• Same response schema. Each item in the returned array follows the existing response schema - index, index_full, local_cdn, local_path, cdn, size, status, and created_at - identical to localcdn://read output.

​

AppsFlyer integration

• Install attribution. The native AppsFlyer SDK is initialised automatically at launch on both iOS and Android. Attribution data is captured at install time, cached on-device, and injected into your web layer on every page load via despia.appsFlyerAttribution, despia.appsFlyerReferrer, and despia.appsFlyerUID. No setup code required.
• Normalised referrer string. despia.appsFlyerReferrer provides a clean source string on every load - values like tiktok_ad, facebook_organic, google_ad, and organic - ready to use for onboarding personalisation and funnel branching without any parsing.
• Deep linking. When a user opens the app via a campaign or creator OneLink URL, Despia resolves the deep link natively and navigates the WebView to the correct path automatically. deep_link_value maps directly to a route in your web app. No navigation code required from the web layer for fresh launches.
• Re-engagement callback. For users who already have the app installed and tap a campaign link while the app is open, Despia calls window.onAppsFlyerDeepLink(data) with the full click event payload so your app can respond without a full page reload.
• Creator and affiliate links. Deep link params support deep_link_sub1 through deep_link_sub5 for creator codes and affiliate IDs. Each creator can receive a unique OneLink URL. Attribution, commission tracking, and welcome personalisation are available from the same payload.
• Event bridge. In-app events are forwarded from your web layer to the native AppsFlyer SDK via despia("appsflyer://log_event?..."). Standard af_ prefixed events map automatically to Meta and TikTok conversion events in their dashboards. Custom events appear in the AppsFlyer dashboard for funnel and retention analysis.
• User identification. set_user_id, set_email, and set_phone are all supported. Emails and phone numbers are hashed with SHA256 automatically before transmission.
• GDPR consent. set_consent accepts is_gdpr and has_consent params and passes them directly to the AppsFlyer SDK consent API.
• On-demand data retrieval. Both get_uid and get_attribution support an await pattern - await despia("appsflyer://get_uid", ["appsFlyerUID"]) - for cases where you need the value immediately in the same execution flow.
• Ad revenue tracking. Coming soon - despia("appsflyer://log_ad_revenue?...") will allow impression-level revenue reporting back to AppsFlyer from Meta, TikTok, and AdMob to enable LTV and ROAS reporting per acquisition channel.

• despia-native

​

Local CDN - query all cached files

• localcdn://query. Calling await despia('localcdn://query', ['cdnItems']) returns the full cdnItems array containing every file currently in the local cache, across all folders.
• Same response schema. Each item in the returned array follows the existing response schema - index, index_full, local_cdn, local_path, cdn, size, status, and created_at - identical to localcdn://read output.

​

Local server

• On-device HTTP server. Assets are served from http://localhost, not file:// or a custom scheme. BrowserRouter, Vue Router, and any routing library that expects a real HTTP origin work without modification.
• First-launch hydration. On first open, Despia fetches your web build from your existing hosting (Netlify, Vercel, AWS, or anything else) and caches it on the device. No migration required.
• OTA updates. On startup, Despia fetches despia/local.json and compares the deployed_at timestamp with the cached value. If it has changed, the new build downloads in the background and applies on next launch. No app store review needed for HTML, CSS, JavaScript, image, or font changes.
• @despia/local build plugin. Available for Vite, Webpack, Rollup, Nuxt, SvelteKit, Astro, Remix, esbuild, and any build system via a postbuild CLI hook. The plugin scans your output directory after each build and generates despia/local.json automatically.
• despia-version-guard. A companion package for gating web UI features behind a minimum native runtime version. Supports React, Vue, Angular, Svelte, and Vanilla JS.

• @despia/local — build plugin
• despia-native — native SDK and JavaScript bridge