Changelog

​

Android runtime now supports Kotlin

​

Vision OCR

• Multiple image sources. Recognize a hosted HTTPS image, a data: URI, a raw base64 string, a photo the user picks, or a multi-page document scan, all through one capability.
• Native pickers. The @imagepicker token opens the system photo library and the @filepicker token opens an image-filtered file browser, with the selection flowing straight into recognition.
• Document scanning. The @documentscanner token opens the native document camera with edge detection and perspective correction, recognizing every captured page and returning the combined text in one result.
• Structured results. Each result delivers the full text plus a per-line breakdown through the window.onVisionEvent callback. Lines carry a confidence score on iOS where the engine exposes one. Output is normalized so each line is trimmed and blank runs collapse before delivery.
• Parallel recognition. Jobs run independently and are correlated by a caller-supplied id, so several images can be processed at once.
• Script hints. An optional language hint constrains recognition to a known script for non-Latin text, though both platforms auto-detect by default.

• despia-native

​

OneSignal push routing and metadata

• Path-based routing. Send a path key in the OneSignal data object (e.g. /account/orders/4567?tab=tracking). Despia applies the route via pushState and fires popstate on notification tap. Most SPA routers react to the popstate event and navigate automatically with no additional code required on the web side.
• Metadata delivery. Send a metadata key in the data object with any JSON value. The payload is delivered to window.onNotificationEvent as an object when sent via the REST API, or as a string requiring JSON.parse when set via the OneSignal dashboard Additional Data fields. Use it to restore app state on open.
• window.onNotificationEvent hook. For routers that do not react to a synthetic popstate, or when using metadata, define window.onNotificationEvent at the top of your entry bundle. The host app calls it on every notification tap after applying the URL change. If the handler is not defined when the event fires, the event is lost and will not be replayed.
• Legacy data.url behavior unchanged. Pushes that send only data.url continue to trigger a full WebView navigation. They now also fire window.onNotificationEvent with url in the payload, which is a no-op if the handler is not implemented.

​

PostHog analytics bridge

• Event capture. The posthog://capture scheme fires named events with optional URI-encoded JSON properties. Device context (OS, app version, screen size) is attached automatically by the native SDK, and your keys take precedence on any conflict.
• Identity and aliasing. The posthog://identify scheme links the device to your internal user ID and stores person properties on the PostHog person record. The posthog://alias scheme merges anonymous pre-signup history into the identified profile in a single call.
• Group analytics. The posthog://group scheme associates subsequent events with an organization, team, or workspace for B2B funnels. Group types are created automatically on first use, up to PostHog’s hard limit of five per project.
• Screen tracking. The posthog://screen scheme sends a $screen event with the provided name, suitable for route-change tracking.
• Super and person properties. The posthog://register and posthog://unregister schemes manage session-level super properties appended to every captured event. The posthog://set_person_properties scheme updates the person record without capturing an event.
• Feature flags via injected globals. The despia.postHogFlags global holds all evaluated flag values, keyed by flag name, and updates in place whenever PostHog pushes new values. Reads are synchronous, always current, and require no despia() call.
• Injected identity globals. despia.postHogDistinctId, despia.postHogSessionId, and despia.postHogOptedOut are kept live on the despia object and update in place after every relevant scheme fires.
• GDPR consent controls. The posthog://opt_out and posthog://opt_in schemes act as the SDK-level consent cutoff. Events fired while opted out are dropped before they reach PostHog servers, and the cutoff persists across sessions.
• Reset on logout. The posthog://reset scheme clears the distinct ID, person properties, super properties, group associations, and session in a single call.

• despia-native

​

PK Pass / Wallet

• Pass sheet trigger. Call despia('wallet://pkpass?url=...') with a publicly hosted HTTPS URL pointing to a .pkpass file. The runtime fetches the file and presents the native add-to-wallet sheet.
• Callback payloads. Define window.onWalletEvent before the despia() call to receive the outcome. Payloads report presented, dismissed, and failed states, with typed error strings for download failures, invalid passes, and device restrictions.

• despia-native

​

Expanded Clerk Auth: SSO, MFA, password reset, SMS, magic links, and more

• Enterprise SSO. Route the user to their organization’s SAML or OIDC identity provider based on email domain. Returns a normal sign-in or sign-up event depending on whether the user is new to the organization.
• MFA continuation. Continue a sign-in whose first-factor result came back needing a second factor. Supports TOTP and backup codes via single-call verify, plus a prepare step for SMS or email second factors.
• Password reset. Three-step reset flow: send a code, verify the code, set a new password. Works with both email and phone identifiers, the bridge picks the right delivery channel.
• SMS one-time code. Passwordless sign-in via a one-time code sent over SMS. Phone numbers are normalized to E.164, so human-formatted numbers like +1 (555) 123-4567 are accepted directly.
• Magic link tickets. Native equivalent of an email magic link. Your backend mints a one-time ticket through Clerk’s API and includes it in an email or push that deep-links into the app, the app forwards the ticket to the bridge to complete sign-in.

• Username and phone sign-in. Password sign-in now accepts any identifier: email, username, or phone. Pass jane, jane@example.com, or +15551234567 and the bridge resolves it.
• Sign-up without email. Password sign-up no longer requires an email address. At least one of email, username, or phone is enough, alongside the password. Username-only or phone-only accounts are valid.
• Email code sign-up. The email code flow now supports new-account creation, not just sign-in. Optional first name, last name, and username can be passed when sending the code.

• Auth Sheet and User Profile emit close events. The prebuilt sign-in sheet now fires a completion event when it closes, carrying userId and emailAddress if the user signed in, or a dismissed event if the sheet closed without sign-in. The User Profile sheet fires a closed event on dismiss. Apps no longer need to poll the session state after the sheet closes.
• Shared pending-flow state. Email code, phone code, password reset, and MFA continuation all hold one in-memory pending sign-in at a time. Starting a new flow cancels any other in flight, and calling a later step before its prerequisite returns a missing-state error.
• Unified completion semantics. Every flow that reaches a successful completion now follows the same pattern: the result payload carries userId (plus emailAddress if a primary email exists), the JWT refresher starts, attribution fires, and window.clerkJWT populates a tick later.

​

WebSockets

• Native connection ownership. The connection lives on the native side rather than in the WebView. It persists through JavaScript suspension, app backgrounding, and WebView reloads without any additional handling in your code.
• Durable inbound message storage. Incoming messages are written to disk before your handler sees them. If the handler fails or the app restarts, Despia replays the message on the next resume, reconnect, or reload.
• Durable outbound queue. Sends issued while the socket is offline are saved and flushed in order once the connection is restored.
• Auto-reconnect with backoff. Dropped connections retry automatically with wait times that grow per attempt and cap at 30 seconds. A keepalive ping goes out every 25 seconds to prevent routers and proxies from closing idle sockets.
• Subscribe frame registration. The websocket://subscribe command registers a frame Despia sends to the server on every connect and reconnect, enabling server-side cursor replay for any messages missed during a gap.
• Connection status. The websocket://status command returns the live state of a connection, including pending outbound sends and unacknowledged inbound messages.

• despia-native

​

Native file preview with fileviewer://

• Custom Android previewer. Android uses Despia’s own in-app file preview engine, not the system “Open with” chooser. This removes the dependency on whichever third-party file viewer the user happens to have installed and delivers render fidelity on par with QuickLook on iOS.
• True cross-platform parity. The same fileviewer:// call renders identically on iOS and Android. Your users see consistent output regardless of device, OS version, or what apps they have installed.
• Authenticated downloads. The native fetch forwards the WebView’s cookie jar and User-Agent automatically, so session-protected file URLs render without query-string tokens or custom headers.
• Broad type coverage. PDFs, images (PNG, JPG, HEIC), plain text, RTF, CSV, and Office documents (DOCX, XLSX, PPTX) are supported. The file extension is taken from the URL path, with a fallback to the response Content-Type.
• Optional theme parameter. Pass theme=light or theme=dark alongside src to match the native previewer to your app’s current appearance. Defaults to the system appearance when omitted.

​

Stripe Payment

• Native PaymentSheet. Call despia('stripe://payment?publishable_key=...&payment_intent_client_secret=...') to open Stripe’s native payment sheet on top of the WebView. The sheet handles card entry, 3DS, Apple Pay, Google Pay, Link, and any other method enabled on the Payment Intent.
• Optional saved cards on payment. Pass customer_id (cus_...) and ephemeral_key_secret (ek_...) on stripe://payment to attach the Stripe customer so the sheet lists their saved cards and saves the new one for reuse. The pair is all-or-nothing: pass both for saved cards, pass neither for guest checkout (the default and original behavior). Passing exactly one returns a missing param failed event with no sheet. Existing integrations without these params continue to work unchanged.
• Native CustomerSheet for saved cards. Call despia('stripe://manage?publishable_key=...&customer_id=...&ephemeral_key_secret=...&setup_intent_client_secret=...') to let the customer manage their saved payment methods. The ephemeral key must be created server-side with the Stripe API version the mobile SDK expects and is short-lived. The optional SetupIntent client secret enables the “add a new card” flow.
• Theme. theme=light, theme=dark, or theme=automatic controls the sheet’s color scheme on both actions. Case-insensitive, unknown values fall back to automatic which follows the device’s system setting.
• Accent color. accent_color=<hex> sets the primary Pay button color and the sheet’s primary accent. Accepts 6-digit hex, 3-digit shorthand, 8-digit hex with alpha, with or without a leading #, and the percent-encoded %23 form. The native runtime tolerates raw # characters in any parameter position. Invalid values are silently ignored.
• Corner radius. corner_radius=<pt> sets the general corner radius applied to input fields and buttons together, including the secondary back button. Non-negative numbers only. Invalid, negative, or non-finite values are silently ignored.
• Action corner radius. action_corner_radius=<pt> overrides the primary Pay button corner radius independently of the general radius. When omitted, the Pay button inherits from corner_radius. When set without corner_radius, only the Pay button is rounded and the rest of the sheet stays at Stripe’s default.
• Single shared callback. window.stripeEvent receives results from both actions. Branch on event.method to route between paymentSheet and customerSheet, then branch on event.status within each. PaymentSheet statuses are completed, canceled, or failed. CustomerSheet statuses are selected, canceled, or failed, with no completed since managing cards is not a payment.
• Stable error contract. A missing or empty required param returns the literal error string missing param on either action, which is safe to match on. All other failures return Stripe’s localized SDK message, which should be logged or displayed but never branched on since it is locale-dependent.
• iOS and Android parity. The same commands work identically on both platforms with no fork in your web code. The native parser treats # as an ordinary character rather than a fragment delimiter, so hex colors and any position of the # resolve the same way everywhere.

​

Clerk Auth for Despia

• Configure and the two globals. clerk://configure wires up the bridge. The native side writes window.clerkJWT (auto-refreshed every 50 seconds, under Clerk’s 60-second TTL) and fires every result through window.onClerkEvent. Same-key configure is a no-op, different keys switch tenant and clear the secure session store.
• Prebuilt Auth Sheet. clerk://authview opens Clerk’s native sign-in sheet covering email/password, OAuth, magic links, MFA, password reset, and passkeys in one prebuilt UI.
• Email and password. clerk://manual?method=password drives manual sign-in and sign-up flows with your own forms while keeping the native session and JWT refresh.
• OAuth providers. method=oauth runs system-browser OAuth via ASWebAuthenticationSession on iOS and Chrome Custom Tabs on Android. Over 25 providers supported (Google, GitHub, Microsoft, Discord, LinkedIn, Facebook, Slack, Notion, Vercel, and more), with unknown values passed through as Clerk custom providers.
• Native Sign in with Apple. method=apple uses Apple’s native ASAuthorizationController sheet on iOS and Apple OAuth via Chrome Custom Tabs on Android. Required by App Review for any iOS app offering third-party social login.
• Email one-time code. method=email_code drives the two-step OTP flow with action=start and action=verify.
• SMS one-time code. method=phone_code (alias sms) ships the same two-step OTP flow over SMS. Phone numbers are normalized to E.164, both code flows share pending state so only one runs at a time.
• Passkeys. method=passkey signs in with an existing credential or registers a new one to the signed-in account. Saved to iCloud Keychain on iOS or Google Password Manager on Android.
• User Profile sheet. clerk://userprofile opens Clerk’s prebuilt account-management sheet for editing profile, managing emails, phones, external accounts, passkeys, sessions, MFA, and account deletion.
• Offline session snapshot. clerk://state reads the full user and session object from the in-memory cache hydrated from secure storage. No network round-trip, works with the device fully offline.
• Zero-config server-side auth. clerk://ssr writes the session into the WebView cookie store scoped to your app host plus localhost and 127.0.0.1. Next.js clerkMiddleware(), TanStack, and any framework reading standard Clerk cookies sees an authenticated user on the very first request, no Clerk web SDK on the page required. A TTL ladder (50s refresher, 55s cookie, 60s JWT) guarantees the cookie pair is always in a state Clerk middleware accepts without a handshake redirect. An optional header= param also injects the JWT on main-frame navigations.
• Attribution sync. clerk://attribution auto-mirrors the Clerk userId into OneSignal and AppsFlyer on every sign-in or sign-up and clears it on sign-out. Enabled by default, overridable via the existing setonesignalplayerid:// and appsflyer://set_user_id routes.
• Sign out and multi-tenant switching. clerk://signout revokes the session, stops the JWT refresher, clears attribution IDs, and writes the signed-out cookie state. Calling configure again with a different publishable key switches tenant and resets everything atomically.

• Introduction
• Auth Methods
• Sessions
• Backend
• Account
• API Reference

​

Speech recognition

• URL-scheme bridge. A flat four-event control flow via speechrecognition://start, stop, and abort, with results delivered to a single window.onSpeechRecognitionEvent callback. Suited to push-to-talk UIs and explicit control flows.
• Web Speech API polyfill. A drop-in window.SpeechRecognition and webkitSpeechRecognition implementation that matches the standard browser surface. Existing Web Speech code and libraries like react-speech-recognition run unmodified inside your app.
• Cross-platform parity. Identical event shapes, error vocabulary, and parameter names on iOS and Android. The same JavaScript runs on both platforms with no branching. Android network failures are folded into the audio-capture error code so a single handler covers both runtimes.
• Continuous and interim modes. Long-form dictation with live partial transcripts, plus single-utterance push-to-talk, configurable per session via the continuous and interim query parameters.
• BCP-47 language selection. Pass any BCP-47 tag like en-US, de-DE, or ja-JP, or omit the language parameter to use the device system locale.
• Custom vocabulary biasing. Pass known_words as a comma-separated query parameter, or set recognition.knownWords on the polyfill, to nudge the recognizer toward product names, jargon, or proper nouns. Backed by SFSpeechAudioBufferRecognitionRequest.contextualStrings on iOS 10 and later and EXTRA_BIASING_STRINGS on Android 13 and later, with a graceful no-op on older Android.

​

NFC tag reading and writing

• Read mode. despia('nfc://read') activates the system NFC sheet, scans one tag, and fires window.onNFCEvent({ type: 'read', id, data }) with the tag’s lowercase hex identifier and NDEF payload.
• Write mode. despia('nfc://write?value=...') writes an arbitrary payload to the next tapped tag and fires window.onNFCEvent({ type: 'write' }) on success.
• Cancellation and error handling. The runtime distinguishes user-dismissed sessions (type: 'dismissed') from platform failures (type: 'error'), so silent resets and retry prompts stay separate.
• vCard payloads. Write a contact card by prefixing the value with VCARD_ and joining properties with underscores. The receiving phone recognises the vCard and offers to save the contact natively.

• despia-native

​

window.virtual.href - 15 years later, a new plugin bridge

• No character limit. Pass multi-megabyte payloads directly on iOS and Android. Full base64 images, long prompts, JSON dumps, and config blobs all go through intact.
• No dropped calls. Fire as many plugin calls in a row as you want, in any order. Every call runs on both platforms.
• Free-form strings. Spaces, special characters, and newlines pass through as-is with no manual encoding required.
• Same syntax as before. window.virtual.href = "myscheme://..." uses the same scheme and parameter shape as the redirect path it replaces. The string is delivered straight to native code via a message channel instead of going through the URL redirect machinery.

​

Action Sheet

• Native iOS and Android sheets. Pass a title and a JSON-encoded items array as URL params. The native side handles presentation and iPad anchoring to the centre of the WebView automatically.
• Per-platform icons. Each item accepts iconIos (any SF Symbol name) and iconAndroid (any Material drawable resource name). Missing or unknown icon names render the row without an icon, no crash.
• Destructive styling. Setting destructive: true on an item renders it in red, matching the platform cue users expect for irreversible actions like delete, remove, and leave.
• Theme override. Pass theme: 'light', 'dark', or 'system' to control sheet appearance independently of the operating system. Defaults to system.
• Single global callback. The native side calls window.onSheetEvent(value) once per sheet with the tapped item’s value, or null if the user tapped Cancel, tapped outside, or tapped back.

• despia-native

​

Focus events

• focusin callback. Fires every time the app returns to the foreground, including the first launch resume. Use it to revalidate session state, refresh auth tokens, or reload content when the user comes back.
• focusout callback. Fires once per background transition. Use it to stop timers, pause video playback, or persist unsaved state before the app is suspended.

• despia-native

​

Apple Health workouts with per-session statistics

• Dedicated workouts endpoint. Call healthkit://workouts?days=N to retrieve every workout in the last N days as a flat array, with date, activityType, duration, calories, distance, value, and unit on each record. Authorization for HKWorkoutTypeIdentifier is requested automatically on the first call.
• Per-workout statistics. Pass an included= parameter with a comma-separated list of HKQuantityTypeIdentifier values, each suffixed with Average, Max, Min, or Sum, to compute aggregates scoped to the workout’s startDate to endDate window rather than the whole day. Results land on a samples[] array on each workout, with each entry exposing key, value, and unit.
• Suffix-driven aggregation. Average maps to discrete average, Max to discrete max, Min to discrete min, and Sum to cumulative sum. An identifier with no suffix defaults to discrete average. Authorization for every base quantity type referenced is requested in a single prompt, with the suffix stripped before the auth call. Invalid identifiers are silently skipped without affecting valid ones in the same call.
• PascalCase activity types. The new scheme returns Apple’s HKWorkoutActivityType enum names directly, for example Running, Cycling, and FunctionalStrengthTraining. The legacy readhealthkit://HKWorkoutTypeIdentifier path continues to return lowercase values like running, so existing UIs reading from healthkitResponse are unaffected.
• Fully backwards compatible. Every existing readhealthkit:// and healthkit://read?types=... call keeps working unchanged. Use healthkit://workouts for any workouts-only read or any read that needs per-workout statistics, and the legacy path when batching workouts with other unrelated identifiers in a single call.

• despia-native

​

Gyroscope sensor

• Single-channel gyro and compass. window.onGyroscopeChange receives x, y, z angular velocity in radians per second plus heading, headingAccuracy, and timestamp on every emitted reading. Heading is -1 until the magnetometer produces its first fix.
• Magnitude threshold. gyroscope://start?threshold= filters readings natively against √(x² + y² + z²). Pass 0 to receive every sample for tilt or parallax UI, higher values for shake-style gestures so the JavaScript layer only sees deliberate motion.
• Tracking state flag. despia.gyroscopeActive reflects whether the sensor is running and survives soft close and reopen. Boot code can branch on the flag to resume the live readout or show the start button without guessing.
• Resume after soft close. When the user backgrounds and reopens the app, the runtime restores the session using the last threshold and continues invoking window.onGyroscopeChange as soon as the handler is reattached.
• Calibration prompts. Readings carry a calibration_required status when iOS reports the magnetometer needs recalibrating. Heading continues to stream during this state so the page can surface a figure-8 hint and dismiss it when headingAccuracy returns to a good range.
• Error handling. Devices without a gyroscope or magnetometer emit a status: "error" payload with error: "unavailable", and despia.gyroscopeActive stays false so fallback UI can take over.
• No permission prompt. Heading is delivered without requesting location access. True-north and Qibla conversions can be done in JavaScript using the page’s own coordinates and a local declination value.

• despia-native

​

Screen Radius

• Automatic injection. No scheme call is required. The runtime reads the top-left corner radius on every supported device and writes it to the page before stylesheets and scripts run.
• JavaScript value. despia.screenRadius returns the radius as a number in CSS pixels, for example 47.33 on iPhone 14 Pro. Use it for any sizing logic that needs the raw measurement.
• CSS variable. --screen-radius is scoped to the document root with a px unit, ready to drop into border-radius rules or calc() expressions for concentric inner corners.
• Graceful fallback. The value resolves to 0 on devices without rounded screens, on older OS versions, and in non-Despia environments. Pair every var(--screen-radius) with a 0px default so calc() expressions stay valid in desktop previews and clamp to square corners.
• Cross-platform parity. iOS and Android expose identical values in CSS pixels, so feature code does not need to branch by platform.

• despia-native on npm

​

RevenueCat Customer Center

• Customer Center scheme. Call the new revenuecat://center scheme with an external_id parameter to present the native sheet. Layout, copy, and available actions are configured from the RevenueCat dashboard, so no client-side UI work is required.
• Event callback. Every interaction inside the sheet streams back through window.onRevenueCatCenter(event). Switch on event.event to handle restoreStarted, restoreCompleted, restoreFailed, manageSubscriptionsOpened, refundRequested, refundCompleted, feedbackSurveyCompleted, managementOptionSelected, and dismissed.
• iOS in-app refunds. iOS users can now initiate refund requests directly from the sheet. The runtime emits refundRequested and refundCompleted events with productId and a status field of success, userCancelled, or error.
• Android refund fallback. Google Play does not allow in-app refund requests, so configure a customUrl management option in the RevenueCat dashboard and route Android users to a mailto: link or your support page from the managementOptionSelected event. iOS continues to use the native flow.
• Fully safe restore pattern. On restoreCompleted, refundCompleted, and dismissed, re-query the native store with the existing getpurchasehistory:// scheme and re-run your entitlement check. The event payload’s activeEntitlements array is informational, the native store query is authoritative.

• despia-native on npm

​

Extended HealthKit sleep identifier support

• Full stage breakdown. Reads now return REM, core, deep, awake, and unspecified asleep values when the source device provides them, in addition to in-bed and asleep totals.
• Third-party device coverage. Any HealthKit-authorised device that writes sleep samples to the Health app is now readable through the same despia() sleep call, including Oura, Whoop, Withings, Eight Sleep, Fitbit, and Garmin where the user has enabled Health app sync.
• Per-sample source metadata. Each returned sample includes the originating source name and bundle identifier so the app can distinguish between devices when the user has more than one sleep tracker connected.
• Backwards compatibility. Existing integrations that only consume in-bed and asleep totals continue to work without changes. New stage fields are additive.

if (isDespiaIOS) {
    const data  = await despia('readhealthkit://HKCategoryTypeIdentifierSleepAnalysis?days=7', ['healthkitResponse'])
    const sleep = data.healthkitResponse.HKCategoryTypeIdentifierSleepAnalysis
}

​

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.

​

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