despia-native 1.0.20 → 1.0.22

package/README.md

@@ -1,1326 +1,979 @@
-# Despia SDK
+# Despia Native
 
-JavaScript SDK for [Despia](https://despia.com) - Add real native device features to your React web app, Vue app, Angular app, or any web framework. Transform your web app into a native iOS & Android app without writing Swift or Kotlin. This npm package provides command queuing and variable watching for seamless integration with Despia's GPU-accelerated native runtime, enabling access to 25+ device APIs through simple JavaScript calls.
+JavaScript SDK for [Despia](https://despia.com). Build with any web framework, access 50+ native device capabilities through a single JavaScript function, and publish to iOS and Android from a browser. No Swift, no Kotlin, no terminal.
+
+[npm](https://www.npmjs.com/package/despia-native)
+[license](LICENSE)
+
+**[Documentation](https://setup.despia.com)** | **[AI Agent Index](https://setup.despia.com/llms.txt)** | **[iOS Deployment](https://setup.despia.com/deployment/apple-ios/automatic)** | **[Android Deployment](https://setup.despia.com/deployment/google-android/automatic)**
+
+Despia is the next generation of web-native development. Unlike earlier hybrid frameworks that routed files through JavaScript, forced Base64 encoding, imposed storage quotas, and ran on insecure `file://` origins, Despia runs your app on a real secure origin (`http://localhost` via Local Server, or your remote URL). Standard web APIs work without restrictions. File operations bypass JavaScript entirely and go directly to the native file system. A 500MB video file uses roughly 100 bytes of JS heap rather than 1.6GB.
+
+The runtime runs on WKWebView (iOS) and the Chromium-based WebView (Android) with hardware-accelerated compositing, JIT-compiled JavaScript, automatic DOM optimization, smart caching, and GPU-accelerated WebGL and Canvas 2D. CSS animations run on the compositor thread independently of JavaScript. The runtime has been actively maintained by the same core team since 2011, when it shipped as Advanced WebView. It has powered over 7,500 apps and became Despia in 2023. Native capabilities are implemented in Swift and Java and called from JavaScript through a single typed function. See the [changelog](https://setup.despia.com/changelog) for the full history.
 
 ---
 
-## Quick Start
+## MCP Server
+
+Add the Despia MCP to give your AI assistant full knowledge of the `despia-native` API.
+
+[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=Despia&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vc2V0dXAuZGVzcGlhLmNvbS9tY3AifQ==)
+[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22Despia%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fsetup.despia.com%2Fmcp%22%7D)
+
+```
+https://setup.despia.com/mcp
+```
+
+Look for "Add MCP", "MCP Settings", or "Personal Connectors" in your builder. Requires Node.js v18+ for local tools.
+
+---
+
+## Table of Contents
+
+- [MCP Server](#mcp-server)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Environment Detection](#environment-detection)
+- [AI Agent Rules](#ai-agent-rules)
+- [API Reference](#api-reference)
+- [Deployment Models](#deployment-models)
+- [Features](#features)
+  - [Haptic Feedback](#haptic-feedback)
+  - [Identity Vault](#identity-vault)
+  - [GPS Location](#gps-location)
+  - [RevenueCat In-App Purchases](#revenuecat-in-app-purchases)
+  - [AppsFlyer Attribution](#appsflyer-attribution)
+  - [Push Notifications](#push-notifications)
+  - [OAuth Authentication](#oauth-authentication)
+  - [Clipboard](#clipboard)
+  - [Contacts](#contacts)
+  - [App Information and Device Data](#app-information-and-device-data)
+  - [UI Controls and Styling](#ui-controls-and-styling)
+  - [File and Media Operations](#file-and-media-operations)
+  - [Apple Health (HealthKit)](#apple-health-healthkit)
+  - [AdMob Inline Ads](#admob-inline-ads)
+  - [Web Payment Request API](#web-payment-request-api)
+  - [Web Storage APIs](#web-storage-apis)
+  - [Local CDN](#local-cdn)
+  - [Local Server](#local-server)
+- [Capability Reference](#capability-reference)
+- [Safe Area](#safe-area)
+- [Extending the Runtime](#extending-the-runtime)
+- [Web Apps vs React Native](#web-apps-vs-react-native)
+- [Publishing to the App Store and Google Play](#publishing-to-the-app-store-and-google-play)
+- [Open Source](#open-source)
+- [Support](#support)
+- [License](#license)
+
+---
+
+## Installation
 
-**Install the SDK:**
 ```bash
 npm install despia-native
+# pnpm add despia-native
+# yarn add despia-native
 ```
 
-**Use it immediately:**
-```javascript
+```js
 import despia from 'despia-native';
-
-// Simple commands
-despia('lighthaptic://');
-
-// Commands with responses
-const appInfo = await despia('getappversion://', ['versionNumber']);
 ```
 
-**Note:** Always use the real SDK package. Mock implementations will not work on actual devices.
+> CDN alternative: `https://cdn.jsdelivr.net/npm/despia-native/+esm` (ESM) or `https://cdn.jsdelivr.net/npm/despia-native/index.min.js` (UMD, global)
 
 ---
 
-**Note: This is for web apps (React, Vue, Angular, etc.) to add native features - NOT for React Native apps.**
+## Quick Start
 
-## Web Apps vs React Native
+```js
+import despia from 'despia-native'; // npm / pnpm / yarn only
 
-**This SDK is for:**
-- React web apps (create-react-app, Next.js, Vite, etc.)
-- Vue web apps
-- Angular web apps  
-- Svelte web apps
-- Any web framework or vanilla JavaScript
-
-**This SDK is NOT for:**
-- React Native apps
-- Expo apps
-- Native mobile development
-
-**If you're building a React Native app, this SDK won't work for you.**
-
-**Import:** `import despia from 'despia-native';` (default export, not destructured)
-
-**IMPORTANT: This SDK package is REQUIRED for TypeScript, React, Vue, and other modern frameworks!** While `window.despia = ""` works in vanilla JavaScript, this package provides type safety, command queuing, and variable watching for professional development environments.
-
-## About Despia
-
-Despia bridges the gap between web and native mobile development. Build your React web app, Vue app, Angular app, or any web framework using the technologies you already know, then deploy it as a truly native application to the App Store and Google Play - complete with hardware acceleration, offline support, and deep OS integration.
-
-Our visual editor allows you to configure native widgets, shortcuts, and dynamic app behaviors without touching Xcode or Android Studio. Ship to both app stores with one-click deployment, automatic CI/CD pipelines, and over-the-air updates. Export clean, human-readable Swift and Kotlin source code anytime - you own everything, no vendor lock-in.
-
-**Go from web app to app store in a weekend - with full native capabilities.**
-
-### Key Features:
-- **Web Framework Support** - Works with React web apps, Vue web apps, Angular web apps, Svelte web apps, vanilla JS, or any web framework
-- **NOT for React Native** - This is for web apps to add native features, not React Native apps
-- **Visual Configuration** - Set up native features through an intuitive interface
-- **Zero Native Coding** - Access device APIs without writing Swift or Kotlin
-- **Source Code Export** - Get complete Xcode and Android Studio projects you can modify
-- **True Ownership** - Full access to generated code, no restrictions
-- **One-Click Publishing** - Direct deployment to App Store & Google Play
-- **Automated Pipeline** - Built-in CI/CD with code signing and provisioning
-- **OTA Updates** - Push updates instantly without app store review
-- **Performance** - 60fps GPU-accelerated rendering
-- **Device API Access** - NFC, HealthKit, Siri, RevenueCat, and 20+ more
-- **Single Codebase** - Maintain one web project for iOS, Android, and web
-
-### Native Device Features:
-- **App Links & Deep Linking** - Universal links and app-to-app communication
-- **Widgets & App Clips** - Home screen widgets and instant app experiences  
-- **In-App Purchases** - RevenueCat integration for subscriptions and payments
-- **Push Notifications** - Local and remote notifications with rich media
-- **Camera & Media** - Camera access, photo library, and file management
-- **Biometric Authentication** - Face ID, Touch ID, and fingerprint
-- **Location Services** - Foreground and background GPS tracking
-- **Contacts** - Address book access with proper permissions
-- **Haptic Feedback** - Tactile responses for user interactions
-- **App Analytics** - Version tracking, bundle IDs, device identifiers
-- **Screenshots** - Programmatic screen capture
-- **Status Bar** - Dynamic styling and visibility control
-- **Privacy Controls** - IDFA tracking and permission management
-- **Share Sheets** - Native sharing UI
-- **UI Controls** - Loading indicators, navigation bars, dynamic layouts
-- **Plus 8+ additional native capabilities**
-
-## Installation (REQUIRED - NO EXCEPTIONS)
+despia('successhaptic://');                           // haptic feedback
+const device = await despia('get-uuid://', ['uuid']); // native device ID
+console.log(device.uuid);
+```
 
-```bash
-# npm
-npm install despia-native
+No initialization. No setup. Open your app in the Despia runtime and it works.
 
-# pnpm
-pnpm install despia-native
+**How it works under the hood**
 
-# yarn
-yarn add despia-native
+Calling `despia()` sets `window.despia` to the scheme string. On iOS this is intercepted in `WebViewController.swift` via `decidePolicyFor navigationAction`. On Android it is intercepted in `MainActivity.java` via `shouldOverrideUrlLoading`. Results are written back to the WebView as named window variables, which the SDK resolves as a promise.
+
+```js
+// despia('get-uuid://', ['uuid'])
+// 1. window.despia = 'get-uuid://'        set by SDK
+// 2. window.location.href = 'get-uuid://' intercepted by native layer
+// 3. window.uuid = '<device-uuid>'        written back to WebView
+const device = await despia('get-uuid://', ['uuid']);
+console.log(device.uuid);
 ```
 
-**This is NOT optional. Your app will NOT work without this package.**
+The SDK handles command queuing, promise-based variable watching with a 30-second timeout, and error handling.
 
-**Package Manager Support:**
-- ✅ **npm** - Fully supported
-- ✅ **pnpm** - Fully supported (v1.0.19+)
-- ✅ **yarn** - Fully supported
+---
 
-**Do not attempt to:**
-- Write your own version
-- Copy/paste a mock implementation  
-- Use window.despia directly in frameworks
-- Create a "simplified" version
+## Environment Detection
 
-**The real SDK is required for ANY Despia functionality to work.**
+The SDK only activates inside the Despia native runtime. Gate native calls using these checks:
 
-## Important Notes
+```js
+const isDespia = navigator.userAgent.toLowerCase().includes('despia');
 
-### Simple Function API
-The SDK exports a single function - no initialization or setup required:
+const isDespiaIOS = isDespia &&
+  (navigator.userAgent.toLowerCase().includes('iphone') ||
+   navigator.userAgent.toLowerCase().includes('ipad'));
 
-```javascript
-import despia from 'despia-native';
+const isDespiaAndroid = isDespia &&
+  navigator.userAgent.toLowerCase().includes('android');
 
-// Just call it directly
-despia('lighthaptic://');
-despia('takescreenshot://');
+if (isDespia) {
+  despia('lighthaptic://');
+} else {
+  // Fallback for browser or development environment
+}
 ```
 
-### Common Mistakes to Avoid
-```javascript
-// Don't create mock implementations
-const despia = (command) => console.log(command); // Won't work on devices
+---
 
-// Don't use non-existent methods
-despia.ready();    // This method doesn't exist
-despia.init();     // This method doesn't exist
-despia.setup();    // This method doesn't exist
-```
+## AI Agent Rules
 
-## Getting Started
+If you are an AI coding agent generating Despia app code, follow these rules:
 
-### Step 1: Import Despia SDK
+- Import as a default: `import despia from 'despia-native'`
+- Do not write to `window.despia` directly; it is used internally by the SDK
+- Gate all native calls using the environment checks above
+- For offline (Local Server) apps, bundle the SDK via a package manager so it is available when the app is served from `http://localhost`
+- For Local CDN downloads, do not `await` `localcdn://write` with a watch key; use `window.contentServerChange(item)` or poll with `localcdn://read`
+- For the HTTP upload API, do not hardcode localhost ports; use `const host = window.location.host`
 
-**IMPORTANT: Always import as `despia` (default export), NOT as `{Commands}` or destructured imports!**
+---
 
-```javascript
-// CORRECT - ES6/ES2015 modules (default import)
-import despia from 'despia-native';
+## API Reference
 
-// CORRECT - CommonJS
-const despia = require('despia-native');
+### `despia(command, watch?)`
 
-// CORRECT - Browser (if using UMD build)
-// <script src="despia-native.js"></script>
-// despia is available globally
 
-// WRONG - Don't do this!
-// import { Commands } from 'despia-native';
-// import { despia } from 'despia-native';
-```
+| Parameter | Type       | Description                                                    |
+| --------- | ---------- | -------------------------------------------------------------- |
+| `command` | `string`   | A Despia protocol URL, e.g. `'lighthaptic://'`                 |
+| `watch`   | `string[]` | Optional. Array of variable names to wait for in the response. |
 
-**The SDK exports a single function called `despia` as the default export.**
 
-### Step 2: Use Native Features (No Setup Required)
+Returns a `Promise` that resolves when all watched variables are set by the native runtime.
 
-```javascript
-// That's it! No initialization needed. Just call despia() directly:
+**Timeout behavior**
 
-// Simple commands (no response needed)
-despia('lighthaptic://');           // Light haptic feedback
-despia('takescreenshot://');        // Take screenshot
-despia('spinneron://');             // Show loading spinner
+The SDK watches for a single variable for up to 30 seconds. This window applies to the variable watch only, not to the underlying native operation. Long-running operations — file downloads, purchases, biometric prompts — complete in native and deliver their result via a global callback function (e.g. `window.onRevenueCatPurchase`, `window.contentServerChange`) rather than a watched variable, so they are never constrained by this window. If a watched variable is never set, the Promise resolves with `undefined` and logs a timeout to the console.
 
-// Commands that return data (use await)
-const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
-console.log(appInfo); // { versionNumber: '1.0.0', bundleNumber: '123' }
+**Fresh-data behavior**
 
-const contacts = await despia('readcontacts://', ['contacts']);
-console.log(contacts); // { contacts: [...] }
-```
+Watched variables are cleared before each call to prevent resolving on stale values.
 
-### Step 3: Handle Responses
+- Single variable: `null` is treated as a valid resolved value. Other empty placeholders (`undefined`, `"n/a"`, `{}`, `[]`) are ignored.
+- Multiple variables: all variables must be non-null before the Promise resolves.
 
-```javascript
-// For commands that set variables, watch for them
-const result = await despia('get-uuid://', ['uuid']);
-console.log('Device UUID:', result.uuid);
+**Direct property access**
 
-// For commands with no response, just call them
-despia('lighthaptic://');
-despia('takescreenshot://');
+```js
+despia.variableName // Equivalent to window.variableName
 ```
 
-### Quick Examples
+### Protocol format
 
-```javascript
-// Haptic feedback
-despia('lighthaptic://');    // Light vibration
-despia('heavyhaptic://');    // Heavy vibration
-despia('successhaptic://');  // Success vibration
+```
+feature://action?param1=value1&param2=value2
+```
 
-// App information
-const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
-const deviceId = await despia('get-uuid://', ['uuid']);
+---
 
-// UI controls
-despia('spinneron://');      // Show loading
-despia('spinneroff://');     // Hide loading
-despia('hidebars://on');     // Hide status bar
+## Deployment Models
 
-// Screenshots and sharing
-despia('takescreenshot://');
-despia('shareapp://message?=Hello&url=https://myapp.com');
-```
+**Remote hydration (default):** The binary ships without embedded web assets. On each launch, Despia fetches the current build from your configured hosting URL. Web content updates do not require App Store or Google Play resubmission.
 
-### Common Import Issues
+**Local Server:** For offline-first apps. Your web build is cached on-device and served from `http://localhost`. After initial hydration the app launches without a network request. See [Local Server](#local-server).
 
-**If you get errors like "Commands is not a function" or "despia is not defined":**
+**OTA version gating:** Gate features by minimum runtime version using `despia-version-guard`.
 
-```javascript
-// WRONG - This will cause errors
-import { Commands } from 'despia-native';
-import { despia } from 'despia-native';
+```bash
+npm install despia-version-guard
+```
 
-// CORRECT - Always use default import
-import despia from 'despia-native';
+```jsx
+import { VersionGuard } from 'despia-version-guard';
 
-// Now you can use it
-despia('lighthaptic://');
+const MyApp = () => (
+  <div>
+    <StableFeature />
+    <VersionGuard min_version="21.0.3">
+      <NewFeature />
+    </VersionGuard>
+  </div>
+);
 ```
 
-**The package exports a single function as the default export, not named exports.**
+---
 
-## When to Use This SDK Package
+## Features
 
-### Vanilla JavaScript (works without this package)
+### Haptic Feedback
 
-```javascript
-// This WORKS in vanilla JavaScript:
-window.despia = 'lighthaptic://';
-window.despia = 'getappversion://';
+```js
+despia('lighthaptic://');   // Subtle vibration
+despia('heavyhaptic://');   // Strong vibration
+despia('successhaptic://'); // Positive confirmation
+despia('warninghaptic://'); // Attention alert
+despia('errorhaptic://');   // Negative feedback
 ```
 
-**Vanilla JS is fine for simple cases, but lacks:**
-- **TypeScript Support** - No type definitions or autocomplete
-- **Command Queuing** - Commands may be lost or executed out of order
-- **Variable Watching** - Can't wait for responses from native commands
-- **Error Handling** - No timeout or error management
-- **Type Safety** - No validation or IntelliSense
+---
 
-### Modern Frameworks Need This Package
+### Identity Vault
 
-```javascript
-// This WON'T work in TypeScript, React, Vue, etc.:
-window.despia = 'lighthaptic://';  // TypeScript errors, no type safety
-window.despia = 'getappversion://'; // No command queuing, no variable watching
-```
+Encrypted key-value storage backed by iCloud KV on iOS and Android App Backup on Android. Persists across uninstalls and reinstalls. Data syncs automatically across all devices sharing the same Apple ID or Google account.
 
-### Modern Frameworks (TypeScript, React, Vue, etc.)
+Set `locked=true` on any key to require Face ID or Touch ID before the value can be read back. Because the vault stores the actual value server-side and only returns it after biometric success, you can store real JWT tokens, session cookies, and API keys behind biometrics. This is a hardware-enforced security guarantee, not a client-side check that can be bypassed.
 
-```javascript
-// This WORKS perfectly in modern frameworks:
-import despia from 'despia-native';
+```js
+// Store a JWT token (reading it back requires Face ID / Touch ID)
+await despia('setvault://?key=sessionToken&value=abc123&locked=true');
 
-despia('lighthaptic://');  // Type-safe, queued, with error handling
-const result = await despia('getappversion://', ['versionNumber']); // Variable watching
+// Read triggers the biometric prompt; token is only returned on success
+const data  = await despia('readvault://?key=sessionToken', ['sessionToken']);
+const token = data.sessionToken;
 ```
 
-**Benefits of using this SDK:**
-- **TypeScript Support** - Full type definitions and autocomplete
-- **Command Queuing** - Sequential execution, no lost commands
-- **Variable Watching** - Automatic waiting for native responses
-- **Error Handling** - Timeouts, error management, debugging
-- **Type Safety** - Validated commands, autocomplete, IntelliSense
+If the key does not exist, `readvault://` throws. Wrap in try/catch to handle first-time users.
 
-**This package is REQUIRED for TypeScript, React, Vue, Angular, and other modern frameworks.**
 
-## Development Notes
+| Parameter | Description                                                      |
+| --------- | ---------------------------------------------------------------- |
+| `key`     | Storage key, e.g. `"userId"` or `"sessionToken"`                 |
+| `value`   | String value to store                                            |
+| `locked`  | `"true"` requires biometrics on read. `"false"` for open access. |
 
-### Environment Detection
-The SDK only works within the Despia native runtime. For development and testing:
 
-```javascript
-import despia from 'despia-native';
+**Store a value without biometric protection**
 
-if (navigator.userAgent.includes('despia')) {
-  // Use native features
-  despia('lighthaptic://');
-} else {
-  // Handle non-Despia environment
-  console.log('Running outside Despia runtime');
-}
-```
+```js
+await despia('setvault://?key=userId&value=user123&locked=false');
 
-### Always Use the Real Package
-- Use the real SDK in all environments (development, testing, production)
-- Don't create mock implementations - they won't work on actual devices
-- The SDK handles missing runtime gracefully
+const { userId } = await despia('readvault://?key=userId', ['userId']);
+```
 
-## Handling Non-Despia Environments
+**Protect a sensitive action with Face ID**
 
-The SDK won't work outside the Despia native runtime, but you can detect and handle this:
+```js
+async function confirmWithBiometrics() {
+  await despia('setvault://?key=confirm&value=yes&locked=true');
+  try {
+    const data = await despia('readvault://?key=confirm', ['confirm']);
+    if (data.confirm === 'yes') {
+      await performSensitiveAction();
+      await despia('setvault://?key=confirm&value=&locked=false');
+    }
+  } catch {
+    // User cancelled or biometric failed
+  }
+}
+```
 
-```javascript
-import despia from 'despia-native';
+**Prevent free trial abuse**
 
-// Check if running in Despia native runtime
-if (navigator.userAgent.includes('despia')) {
-  // Use Despia native features
-  despia('lighthaptic://');
-  const appInfo = await despia('getappversion://', ['versionNumber']);
-} else {
-  // Handle non-Despia environment (browser, development, etc.)
-  console.log('Running outside Despia runtime - native features unavailable');
-  // Provide fallback behavior or show appropriate message
+```js
+async function checkTrialEligibility() {
+  try {
+    const data = await despia('readvault://?key=hasUsedTrial', ['hasUsedTrial']);
+    return data.hasUsedTrial !== 'yes';
+  } catch {
+    // Key not found, first-time user
+    await despia('setvault://?key=hasUsedTrial&value=yes&locked=false');
+    return true;
+  }
 }
 ```
 
-**This is the correct way to handle different environments - use the real SDK with proper detection, never mock it.**
-
-## Usage
+---
 
-### Basic Despia Command Execution
+### GPS Location
 
-```javascript
-import despia from 'despia-native';
+```js
+// Set up the live update callback
+window.onLocationChange = (data) => {
+  if (!data.active) return;
+  console.log(data.latitude, data.longitude, data.horizontalAccuracy);
+};
 
-// Execute a Despia protocol command (no response needed)
-despia('lighthaptic://');
+// Start tracking (buffer in seconds, movement threshold in centimetres)
+despia('location://?buffer=60&movement=100');
 
-// Execute command and watch for response variables (await needed)
-const result = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
-console.log(result); // { versionNumber: '1.0.0', bundleNumber: '123' }
+// Stop tracking and retrieve the session
+const { locationSession } = await despia('stoplocation://', ['locationSession']);
 ```
 
-### Despia Command Examples
+**Server delivery**
 
-```javascript
-// Native Widgets
-despia('widget://${svg}?refresh=${refresh_time}');
+When `server` is set, each GPS point is POSTed to your endpoint as it is recorded. Server delivery, `window.onLocationChange`, and local session storage all run simultaneously and independently. Loss of network does not affect local storage or frontend callbacks.
 
-// RevenueCat In-App Purchases
-despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');
+```js
+despia('location://?server=https://api.example.com/track?user=USER_ID&buffer=30&movement=100');
+```
 
-// Restore Purchases
-const purchaseData = await despia("getpurchasehistory://", ["restoredData"]);
+Each POST body matches the location object shape returned by `stoplocation://`.
 
-// RevenueCat Paywalls
-despia('revenuecat://launchPaywall?external_id=user_777&offering=default');
+Full docs: [https://setup.despia.com/native-features/gps-location](https://setup.despia.com/native-features/gps-location)
 
-// Identity Vault
-await despia(`setvault://?key=userId&value=user123&locked=false`);
-const vaultData = await despia(`readvault://?key=userId`, ['userId']);
+---
 
-// OAuth Authentication
-despia(`oauth://?url=${encodeURIComponent(oauthUrl)}`);
+### RevenueCat In-App Purchases
 
-// Local Storage
-const encoded = encodeURIComponent(JSON.stringify(userData));
-await despia(`writevalue://${encoded}`);
-const data = await despia("readvalue://", ["storedValues"]);
+**Launch a paywall**
 
-// Read Clipboard
-const clipboardData = await despia('getclipboard://', ['clipboarddata']);
+```js
+despia(`revenuecat://launchPaywall?external_id=${userId}&offering=default`);
+```
 
-// Open App Settings
-despia("settingsapp://");
 
-// Contact Permissions
-despia('requestcontactpermission://');
-const contacts = await despia('readcontacts://', ['contacts']);
+| Parameter     | Required | Description                                                        |
+| ------------- | -------- | ------------------------------------------------------------------ |
+| `external_id` | Yes      | Your user ID in RevenueCat                                         |
+| `offering`    | Yes      | RevenueCat offering ID. Use `"default"` for your default offering. |
 
-// Background Location
-despia('backgroundlocationon://');
-// Use native browser geolocation API (not despia native runtime)
-const watchId = navigator.geolocation.watchPosition(
-  (position) => console.log('Location:', position),
-  (error) => console.error('Location error:', error)
-);
-// To stop
-despia('backgroundlocationoff://');
-navigator.geolocation.clearWatch(watchId);
 
-// Push Notifications
-despia('registerpush://');
-despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
-// Set OneSignal external user ID (call on every app load)
-despia(`setonesignalplayerid://?user_id=${YOUR_LOGGED_IN_USER_ID}`);
+**Direct purchase without paywall UI**
 
-// Haptic Feedback
-despia('lighthaptic://');
-despia('heavyhaptic://');
-despia('successhaptic://');
-despia('warninghaptic://');
-despia('errorhaptic://');
+```js
+// iOS
+despia(`revenuecat://purchase?external_id=${userId}&product=monthly_premium_ios`);
 
-// App Information
-const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
-const deviceInfo = await despia('get-uuid://', ['uuid']);
+// Android
+despia(`revenuecat://purchase?external_id=${userId}&product=premium:monthly_premium_android`);
+```
 
-// Screenshots and Scanning
-despia('takescreenshot://');
-despia('scanningmode://auto');
-despia('scanningmode://on');
-despia('scanningmode://off');
+**Handle purchase success**
 
-// Store and Location
-const storeData = await despia('getstorelocation://', ['storeLocation']);
+The Despia runtime calls `window.onRevenueCatPurchase()` immediately when the store confirms a transaction. This is a global function, not an event listener — part of how the bridge is designed to stay lightweight and offload heavy operations to the native layer.
 
-// Image and File Operations
-despia('savethisimage://?url=${image_url}');
-despia('file://${file_url}');
+This callback is a signal that a transaction occurred, not confirmation that access should be granted. If you have a backend, the callback fires before your server has received and processed the RevenueCat webhook. Always wait for your backend to confirm before unlocking features.
 
-// App Control
-despia('reset://');
-const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);
+If you have no backend, use `getpurchasehistory://` inside the callback to check entitlements directly from the store:
 
-// UI Controls
-despia('spinneron://');
-despia('spinneroff://');
-despia('hidebars://on');
-despia('hidebars://off');
+```js
+window.onRevenueCatPurchase = async () => {
+  const { restoredData } = await despia('getpurchasehistory://', ['restoredData']);
+  const active = (restoredData ?? []).filter(p => p.isActive);
 
-// Sharing
-despia('shareapp://message?=${message}&url=${url}');
+  if (active.some(p => p.entitlementId === 'premium')) unlockPremium();
+  if (active.some(p => p.entitlementId === 'no_ads'))  removeAds();
+};
+```
 
-// Status Bar Styling
-despia('statusbarcolor://{255, 255, 255}');
-despia('statusbartextcolor://{black}');
+**Restore purchases**
 
-// Biometric Authentication
-despia('bioauth://');
+```js
+const { restoredData } = await despia('getpurchasehistory://', ['restoredData']);
+const hasPremium = restoredData
+  .filter(p => p.isActive)
+  .some(p => p.entitlementId === 'premium');
 ```
 
-### Direct Window Variable Access
+Each purchase object includes `transactionId`, `productId`, `type`, `entitlementId`, `isActive`, `willRenew`, `purchaseDate`, `expirationDate`, `store`, `receipt`, and more. The response shape is normalized across iOS and Android.
+
+**Web fallback**
 
-```javascript
-// Access any window variable directly (useful for Despia response data)
-const currentUser = despia.currentUser;
-const deviceInfo = despia.deviceInfo;
-const appVersion = despia.appVersion;
+Neither `launchPaywall` nor `purchase` work in a standard browser. Gate behind the environment check and fall back to a RevenueCat Web Purchase Link:
+
+```js
+if (isDespia) {
+  despia(`revenuecat://launchPaywall?external_id=${userId}&offering=default`);
+} else {
+  window.location.href = `https://pay.rev.cat/<your_token>/${encodeURIComponent(userId)}`;
+}
 ```
 
-### Advanced Usage with Variable Watching
+Full RevenueCat docs: [https://setup.despia.com/native-features/revenuecat/reference](https://setup.despia.com/native-features/revenuecat/reference)
 
-```javascript
-// Watch multiple response variables
-const appData = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
+---
 
-// Chain multiple Despia commands
-despia('lighthaptic://');
-const appData2 = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
-despia('successhaptic://');
-```
+### AppsFlyer Attribution
 
-### Background Location Workflow
+Attribution data is recorded at install time by the native AppsFlyer SDK, cached on-device, and injected into the web layer on every page load. No requests, no waiting. Currently available on iOS, with Android coming soon.
 
-Background location tracking requires a two-step process:
+AppsFlyer must be enabled in **Despia > App > Settings > Integrations > AppsFlyer** with your dev key configured.
 
-```javascript
-// Step 1: Enable native background location tracking via Despia
-despia('backgroundlocationon://');
+**Attribution variables (injected on every page load)**
 
-// Step 2: Use native browser geolocation API for actual tracking (not despia native runtime)
-const watchId = navigator.geolocation.watchPosition(
-  (position) => {
-    console.log('Location update:', {
-      latitude: position.coords.latitude,
-      longitude: position.coords.longitude,
-      accuracy: position.coords.accuracy,
-      timestamp: position.timestamp
-    });
-  },
-  (error) => {
-    console.error('Location error:', error);
-  },
-  {
-    enableHighAccuracy: true,
-    timeout: 10000,
-    maximumAge: 60000
-  }
-);
+```js
+despia.appsFlyerAttribution // full attribution object (campaign, ad set, UTM params, etc.)
+despia.appsFlyerReferrer    // normalized source: "tiktok_ad", "facebook_organic", "organic", etc.
+despia.appsFlyerUID         // unique AppsFlyer user ID
+```
+
+**User identification (call after login)**
 
-// To stop tracking:
-// Step 1: Disable native background tracking via Despia
-despia('backgroundlocationoff://');
-// Step 2: Clear browser geolocation watch (native API)
-navigator.geolocation.clearWatch(watchId);
+```js
+despia('appsflyer://set_user_id?customer_user_id=' + encodeURIComponent(userId));
+despia('appsflyer://set_email?email=' + encodeURIComponent(email));
+despia('appsflyer://set_phone?phone=' + encodeURIComponent(phone)); // hashed with SHA256 automatically
 ```
 
-### Contact Access Workflow
+**GDPR consent**
 
-```javascript
-// Step 1: Request contact permission
-despia('requestcontactpermission://');
+```js
+// User accepted
+despia('appsflyer://set_consent?is_gdpr=true&has_consent=true');
 
-// Step 2: Read contacts after permission granted
-const contactData = await despia('readcontacts://', ['contacts']);
-console.log('Contacts:', contactData.contacts);
+// User declined
+despia('appsflyer://set_consent?is_gdpr=true&has_consent=false');
 ```
 
-### RevenueCat Paywall Workflow
+**Log in-app events**
 
-Create a payment system that uses RevenueCat Paywalls by launching native paywall interfaces configured in your RevenueCat dashboard:
+Standard `af_` prefixed events map automatically to Meta and TikTok conversion events. Custom events appear in AppsFlyer for funnel and retention analysis.
 
-```javascript
-// First, install the package:
-// npm install despia-native
+```js
+// af_purchase maps to Meta Purchase and TikTok CompletePayment
+const purchase = { af_revenue: 9.99, af_currency: 'USD', af_content_id: 'pro_plan' };
+despia('appsflyer://log_event?event_name=af_purchase&event_values=' + encodeURIComponent(JSON.stringify(purchase)));
 
-// Then import it:
-import despia from 'despia-native';
-
-// Launch a paywall for a specific offering
-despia('revenuecat://launchPaywall?external_id=USER_ID&offering=default');
+// af_complete_registration maps to Meta CompleteRegistration
+const reg = { af_registration_method: 'email' };
+despia('appsflyer://log_event?event_name=af_complete_registration&event_values=' + encodeURIComponent(JSON.stringify(reg)));
 
-// Example offerings you might configure:
-// - "default" - your main offering
-// - "premium" - premium tier offering
-// - "annual_sale" - special promotional offering
+// Custom event (AppsFlyer only)
+const onboarding = { step: 1, name: 'select_interests' };
+despia('appsflyer://log_event?event_name=onboarding_step&event_values=' + encodeURIComponent(JSON.stringify(onboarding)));
 ```
 
-**Handling Purchase Success:**
+`event_values` must always be `JSON.stringify()`ed and `encodeURIComponent()`ed. Event names are case-sensitive, lowercase alphanumeric and underscores only, max 300 unique names per day.
 
-The Despia Native Runtime will call the global function `onRevenueCatPurchase()` when an in-app purchase or subscription is successfully made on the client side. Although this should not grant access immediately, it's a good time to start polling your backend to check if the RevenueCat webhook has already updated the user's status or plan permissions.
+Full attribution docs: [https://setup.despia.com/analytics/appsflyer/introduction](https://setup.despia.com/analytics/appsflyer/introduction)
 
-```javascript
-// Define the global callback function
-window.onRevenueCatPurchase = function() {
-  console.log('Purchase successful! Polling backend for status update...');
-  
-  // Start polling your backend to check if RevenueCat webhook
-  // has updated the user's status or plan permissions
-  // This ensures you don't grant access before the webhook processes
-};
-```
+---
 
-This will launch a native paywall interface configured in your RevenueCat dashboard, handling purchases through Apple App Store and Google Play billing.
+### Push Notifications
 
-### Identity Vault Workflow
+Despia requests push permission and registers the device with OneSignal automatically at app launch. Call `setonesignalplayerid://` on every authenticated load to link the device to your user.
 
-The identity vault provides persistent, cross-device storage with optional biometric protection:
+```js
+// Link device to your user (call on every authenticated app load)
+despia(`setonesignalplayerid://?user_id=${userId}`);
 
-```javascript
-// First, install the package:
-// npm install despia-native
+// Send a local scheduled notification (fires after 60 seconds)
+despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
 
-// Then import it:
-import despia from 'despia-native';
+// Check push permission status
+const result = await despia('checkNativePushPermissions://', ['nativePushEnabled']);
+if (!result.nativePushEnabled) {
+  // Direct user to settings to enable notifications
+  despia('settingsapp://');
+}
+```
 
-// Store identity data
-await despia(`setvault://?key=${keyName}&value=${value}&locked=${isLocked}`);
+**Send to a specific user from your backend**
 
-// Retrieve identity data
-const data = await despia(`readvault://?key=${keyName}`, [keyName]);
-const value = data[keyName];
+```js
+await fetch('https://onesignal.com/api/v1/notifications', {
+  method: 'POST',
+  headers: {
+    'Content-Type':  'application/json',
+    'Authorization': 'Basic YOUR_REST_API_KEY',
+  },
+  body: JSON.stringify({
+    app_id: 'ONESIGNAL-APP-ID',
+    include_external_user_ids: [externalUserId],
+    headings: { en: title },
+    contents: { en: message },
+    data: { url: 'https://yourapp.com/messages/123' } // navigate WebView on tap
+  }),
+});
 ```
 
-**Parameters:**
+When configuring OneSignal, select **Native iOS** and **Native Android** as the platforms. For critical alerts that bypass Do Not Disturb, see the full push docs: [https://setup.despia.com](https://setup.despia.com)
 
-- **key** - Name for your stored data (use simple names like "userId", "deviceId", "sessionToken")
-- **value** - The data to store (text/string)
-- **locked** - Set to `'true'` to require Face ID/fingerprint, `'false'` for normal storage
+---
 
-**Features:**
+### OAuth Authentication
 
-- **Persistent storage** - Data survives app restarts, updates, and even uninstall/reinstall
-- **Cross-device sync** - Works across all user's devices with the same Apple ID or Google account
-- **User tracking** - Identify the same user even after they uninstall and reinstall your app
-- **Face ID protection** - Optional biometric lock for sensitive actions
-- **Automatic timeout** - 30-second timeout prevents app freezing
+The flow uses two Despia URL protocols. `oauth://` opens a secure browser session (ASWebAuthenticationSession on iOS, Chrome Custom Tabs on Android). The `{scheme}://oauth/` prefix on the return deeplink tells Despia to close that session and navigate your WebView to the path that follows.
 
-**Perfect for:**
+When running in Despia, use a native-specific redirect URI pointing to `/native-callback.html` rather than your regular web auth callback. This is a different redirect URI from your web flow. Register both with your OAuth provider.
 
-- Identifying users across sessions
-- Preventing free trial abuse (track device even after uninstall)
-- Storing login session tokens
-- Protecting sensitive actions with Face ID/Touch ID
-- Saving user preferences and app settings
+```js
+const isDespia = navigator.userAgent.toLowerCase().includes('despia');
 
-**Example Usage:**
+const redirectUri = isDespia
+  ? 'https://yourapp.com/native-callback.html'
+  : 'https://yourapp.com/auth/callback';
 
-```javascript
-// Store user ID (normal storage)
-await despia(`setvault://?key=userId&value=user123&locked=false`);
+const oauthUrl = `https://provider.com/oauth/authorize?client_id=xxx&redirect_uri=${encodeURIComponent(redirectUri)}`;
 
-// Store session token with biometric protection
-await despia(`setvault://?key=sessionToken&value=abc123xyz&locked=true`);
+if (isDespia) {
+  // Step 1: open a secure native browser session
+  despia(`oauth://?url=${encodeURIComponent(oauthUrl)}`);
+} else {
+  // Regular web flow
+  window.location.href = oauthUrl;
+}
+```
 
-// Retrieve stored data
-const userData = await despia(`readvault://?key=userId`, ['userId']);
-console.log('User ID:', userData.userId);
+`/native-callback.html` runs inside the secure browser session. It receives the tokens or authorization code from the provider, handles the exchange if needed, then fires the deeplink to close the session and return to the app:
 
-const sessionData = await despia(`readvault://?key=sessionToken`, ['sessionToken']);
-console.log('Session Token:', sessionData.sessionToken);
+```js
+// Step 2: from inside the callback page, fire the deeplink to return to your app
+window.location.href = `{yourscheme}://oauth/auth?access_token=${token}`;
 ```
 
-### OAuth Authentication Workflow
+Despia intercepts the deeplink, closes the browser session, and navigates your WebView to `/auth?access_token=xxx`.
 
-Launch OAuth authentication in a secure native browser session:
+Deeplink format: `{yourscheme}://oauth/{path}?params`
 
-```javascript
-// First, install the package:
-// npm install despia-native
+Your deeplink scheme is your app name in lowercase with no spaces (e.g. `myapp://`), or a custom Despialink set in the Despia editor.
 
-// Then import it:
-import despia from 'despia-native';
 
-// Launch OAuth flow
-const oauthUrl = 'https://your-provider.com/oauth/authorize?client_id=xxx&redirect_uri=xxx';
-despia(`oauth://?url=${encodeURIComponent(oauthUrl)}`);
-```
+| Deeplink                                     | Result                                                        |
+| -------------------------------------------- | ------------------------------------------------------------- |
+| `{yourscheme}://oauth/auth?access_token=xxx` | Browser closes, WebView navigates to `/auth?access_token=xxx` |
+| `{yourscheme}://oauth/home`                  | Browser closes, WebView navigates to `/home`                  |
+| `{yourscheme}://auth?access_token=xxx`       | Browser stays open, user is stuck                             |
 
-**How it works:**
 
-1. **Opens secure browser session:**
-   - **iOS**: ASWebAuthenticationSession (secure Safari sheet)
-   - **Android**: Chrome Custom Tabs (secure Chrome overlay)
+**Callback page**
 
-2. **User completes OAuth** in the secure browser session
+Use a plain HTML file at `public/native-callback.html` rather than a React or Vue route. React Router can strip the `#access_token` hash fragment during a route change, causing tokens to disappear before your callback logic runs. A plain HTML file bypasses the router entirely and reads the hash directly from the browser.
 
-3. **Parse tokens from callback URL** - OAuth providers typically return tokens in the URL hash or query parameters:
-   ```javascript
-   // Example: Parse tokens from URL hash (implicit flow)
-   const hash = window.location.hash.substring(1);
-   const hashParams = new URLSearchParams(hash);
-   const accessToken = hashParams.get('access_token');
-   const refreshToken = hashParams.get('refresh_token');
-   ```
+```html
+<!-- public/native-callback.html -->
+<script>
+  var params      = new URLSearchParams(window.location.search);
+  var hash        = new URLSearchParams(window.location.hash.substring(1));
+  var code        = params.get('code');        // authorization code flow
+  var accessToken = hash.get('access_token');  // implicit flow
 
-4. **Close browser and return to app** - Use your app's deeplink scheme with the `oauth/` prefix:
-   ```javascript
-   // From your callback page (still in secure browser session)
-   window.location.href = `myapp://oauth/auth?access_token=${accessToken}&refresh_token=${refreshToken}`;
-   ```
+  if (code) {
+    // exchange code via your backend, then fire deeplink with tokens
+  } else if (accessToken) {
+    window.location.href = '{yourscheme}://oauth/auth?access_token=' + encodeURIComponent(accessToken);
+  }
+</script>
+```
+
+**Already-mounted `/auth` page**
 
-5. **Handle deeplink in app** - The native app intercepts the deeplink, closes the browser session, and navigates your WebView to the specified path with query parameters.
+When Despia navigates the WebView to `/auth`, if that route is already active your framework does not remount the component. Token-reading logic that only runs on mount will not fire again. Fix per framework:
 
-**Deeplink format:** `{scheme}://oauth/{path}?params`
+- React: include `searchParams` in your `useEffect` dependency array
+- Vue: use `watch: { '$route.query': { immediate: true, handler } }` instead of reading params in `mounted()`
+- Vanilla JS: call your handler on load and add `window.addEventListener('popstate', handler)`
 
-- `myapp://` - Your app's deeplink scheme
-- `oauth/` - Required prefix that tells native code to close the browser session
-- `{path}` - Where to navigate in your app (e.g., `auth`, `home`, `profile`)
-- `?params` - Query parameters passed to that page
+Full docs: [https://setup.despia.com/native-features/o-auth-2-0](https://setup.despia.com/native-features/o-auth-2-0)
 
-**Examples:**
-- `myapp://oauth/auth?access_token=xxx` - Closes browser, opens `/auth?access_token=xxx`
-- `myapp://oauth/home` - Closes browser, opens `/home`
-- `myapp://oauth/profile?tab=settings` - Closes browser, opens `/profile?tab=settings`
+---
 
-**Perfect for:**
-- Google, Facebook, Apple, GitHub, and other OAuth providers
-- Secure authentication flows without leaving your app
-- Native browser sessions with automatic cleanup
+### Clipboard
 
-### Local Storage Workflow
+```js
+const { clipboarddata } = await despia('getclipboard://', ['clipboarddata']);
+```
 
-Create a local storage system with cross-platform support (data is cleared on app uninstall):
+---
 
-```javascript
-// First, install the package:
-// npm install despia-native
+### Contacts
 
-// Then import it:
-import despia from 'despia-native';
+```js
+const { contacts } = await despia('readcontacts://', ['contacts']);
+```
 
-// This SDK is compatible only with the Native Despia Runtime.
-// Ensure that the User Agent string includes "despia" before running this code.
-// If the User Agent string doesn't include "despia" you can use Local Storage as a web fallback.
+---
 
-// Save data
-const userData = { refresh_token: "SSBMT1ZFIERFU1BJQSBOQVRJVkUgU08gTVVDSCBJIFdBTk5BIEtJU1MgSVQh" };
-const encoded = encodeURIComponent(JSON.stringify(userData));
-await despia(`writevalue://${encoded}`);
+### App Information and Device Data
 
-// Retrieve data
-const data = await despia("readvalue://", ["storedValues"]);
-const userData = JSON.parse(decodeURIComponent(data.storedValues));
-console.log(userData.refresh_token);
+```js
+const { versionNumber, bundleNumber } = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
+const { uuid }             = await despia('get-uuid://',              ['uuid']);
+const { storeLocation }    = await despia('getstorelocation://',      ['storeLocation']);
+const { trackingDisabled } = await despia('user-disable-tracking://', ['trackingDisabled']);
 ```
 
-**How it works:**
-
-- **Save data**: Use `writevalue://` with a JSON-encoded string to store data on the device
-- **Retrieve data**: Use `readvalue://` with `["storedValues"]` to get the stored data
-- **Data format**: Data is stored as a single string and returned in the response object
-- **Cross-platform**: Works on both iOS and Android
-- **Lifecycle**: Data persists across app restarts but is cleared on app uninstall
+---
 
-**Important Notes:**
+### UI Controls and Styling
 
-- **Runtime compatibility**: Only works with Despia Native Runtime (check User Agent for "despia")
-- **Web fallback**: Use Local Storage as a fallback if not running in Despia Native Runtime
-- **UI blocking**: Refrain from blocking any UI elements or adding loading screens before data is loaded, as most sessions will not have initial data yet if no data has been stored
+```js
+despia('spinneron://');                     // Show loading spinner
+despia('spinneroff://');                    // Hide loading spinner
+despia('hidebars://on');                    // Hide status bar (full screen)
+despia('hidebars://off');                   // Restore status bar
+despia('statusbarcolor://{255, 255, 255}'); // Set status bar background (RGB)
+despia('statusbartextcolor://{black}');     // Set status bar text color: black | white
+despia('settingsapp://');                   // Open native app settings
+despia('reset://');                         // Reset the app
+```
 
-**Perfect for:**
+---
 
-- Storing user preferences and settings
-- Caching temporary data
-- Storing session tokens (non-sensitive)
-- App configuration data
+### File and Media Operations
 
-### Restore Purchases Workflow
+Despia automatically intercepts standard HTML file inputs and routes them to native UI. No Base64 blobs, no memory issues. File events are injected back into the standard HTML file input.
 
-Retrieve purchase history from the native app stores to implement "Restore Purchases" functionality and verify user entitlements:
+```html
+<!-- Opens a native action sheet with camera, document scanner, and media library -->
+<input type="file">
 
-```javascript
-// First, install the package:
-// npm install despia-native
+<!-- Opens native media gallery for images -->
+<input type="file" accept="image/*">
 
-// Then import it:
-import despia from 'despia-native';
+<!-- Opens native media gallery for video -->
+<input type="file" accept="video/*">
 
-// Retrieve purchase history
-const data = await despia("getpurchasehistory://", ["restoredData"]);
-const purchases = data.restoredData;
-console.log(purchases);
+<!-- Opens native camera directly -->
+<input type="file" accept="image/*" capture="environment">
 ```
 
-**How it works:**
-
-Despia queries the native platform's billing system to retrieve all purchases associated with the current user's App Store or Google Play account. This includes active subscriptions, expired subscriptions, consumables, and non-consumable (lifetime) purchases. The data is normalized into a consistent format across both iOS and Android platforms.
-
-**Response Structure:**
-
-Each purchase object in the response array includes:
-
-- **transactionId** - Unique identifier for this specific transaction
-- **originalTransactionId** - Identifier linking to the original purchase (useful for subscription renewals)
-- **productId** - The product identifier configured in App Store Connect / Google Play Console
-- **type** - Either `"subscription"` or `"product"` (one-time purchase)
-- **entitlementId** - The entitlement/access level this purchase grants
-- **externalUserId** - External user identifier if configured
-- **isAnonymous** - Boolean indicating if the purchase is anonymous
-- **isActive** - Boolean indicating if the purchase currently grants access
-- **willRenew** - Boolean indicating if a subscription will auto-renew
-- **purchaseDate** - ISO timestamp of the most recent transaction
-- **originalPurchaseDate** - ISO timestamp of the initial purchase
-- **expirationDate** - ISO timestamp when access expires (`null` for lifetime purchases)
-- **store** - Either `"app_store"` or `"play_store"`
-- **country** - User's country code
-- **environment** - `"production"` or `"sandbox"`
-- **receipt** - The raw receipt data for server-side validation
-
-**Example Response (iOS):**
-
-```javascript
-[
-    {
-        "transactionId": "1000000987654321",
-        "originalTransactionId": "1000000123456789",
-        "productId": "com.app.premium.monthly",
-        "type": "subscription",
-        "entitlementId": "premium",
-        "externalUserId": "abc123",
-        "isAnonymous": false,
-        "isActive": true,
-        "willRenew": true,
-        "purchaseDate": "2024-01-15T14:32:05Z",
-        "originalPurchaseDate": "2023-06-20T09:15:33Z",
-        "expirationDate": "2024-02-15T14:32:05Z",
-        "store": "app_store",
-        "country": "USA",
-        "receipt": "MIIbngYJKoZIhvcNAQcCoIIbajCCG2YCAQExDzAN...",
-        "environment": "production"
-    },
-    {
-        "transactionId": "1000000555555555",
-        "originalTransactionId": "1000000555555555",
-        "productId": "com.app.removeads",
-        "type": "product",
-        "entitlementId": "no_ads",
-        "externalUserId": "abc123",
-        "isAnonymous": false,
-        "isActive": true,
-        "willRenew": false,
-        "purchaseDate": "2023-12-01T08:00:00Z",
-        "originalPurchaseDate": "2023-12-01T08:00:00Z",
-        "expirationDate": null,
-        "store": "app_store",
-        "country": "USA",
-        "receipt": "MIIbngYJKoZIhvcNAQcCoIIbajCCG2YCAQExDzAN...",
-        "environment": "production"
-    }
-]
-```
+Additional file and media commands:
 
-**Example Response (Android):**
-
-```javascript
-[
-    {
-        "transactionId": "GPA.3372-4150-9088-12345",
-        "originalTransactionId": "GPA.3372-4150-9088-12345",
-        "productId": "com.app.premium.monthly",
-        "type": "subscription",
-        "entitlementId": "premium",
-        "externalUserId": "abc123",
-        "isAnonymous": false,
-        "isActive": true,
-        "willRenew": true,
-        "purchaseDate": "2024-01-15T14:32:05Z",
-        "originalPurchaseDate": "2023-06-20T09:15:33Z",
-        "expirationDate": "2024-02-15T14:32:05Z",
-        "store": "play_store",
-        "country": "US",
-        "receipt": "kefhajglhaljhfajkfajk.AO-J1OxBnT3hAjkl5FjpKc9...",
-        "environment": "production"
-    },
-    {
-        "transactionId": "GPA.3372-4150-9088-67890",
-        "originalTransactionId": "GPA.3372-4150-9088-67890",
-        "productId": "com.app.removeads",
-        "type": "product",
-        "entitlementId": "no_ads",
-        "externalUserId": "abc123",
-        "isAnonymous": false,
-        "isActive": true,
-        "willRenew": false,
-        "purchaseDate": "2023-12-01T08:00:00Z",
-        "originalPurchaseDate": "2023-12-01T08:00:00Z",
-        "expirationDate": null,
-        "store": "play_store",
-        "country": "US",
-        "receipt": "minodkpfokbofclncmaa.AO-J1Oy2fXpTml7rKxE3vNc9...",
-        "environment": "production"
-    }
-]
+```js
+despia('takescreenshot://');
+despia('savethisimage://?url=https://example.com/image.jpg');
+despia('file://https://example.com/document.pdf');
+despia('shareapp://message?=Check%20out%20this%20app&url=https://myapp.com');
+despia('scanningmode://auto'); // auto | on | off
 ```
 
-**Check Active Entitlements:**
+---
 
-```javascript
-const data = await despia("getpurchasehistory://", ["restoredData"]);
-const purchases = data.restoredData;
+### Apple Health (HealthKit)
 
-// Filter for active purchases only
-const activePurchases = purchases.filter(p => p.isActive);
+iOS only. Always gate behind `isDespiaIOS`. Despia requests permissions on the first call for each identifier.
 
-// Check if user has premium access
-const hasPremium = activePurchases.some(p => p.entitlementId === "premium");
+```js
+// Read historical data
+const data  = await despia('readhealthkit://HKQuantityTypeIdentifierStepCount?days=7', ['healthkitResponse']);
+const steps = data.healthkitResponse.HKQuantityTypeIdentifierStepCount;
+// [{ date: "2025-11-17", value: 9820, unit: "count" }, ...]
 
-if (hasPremium) {
-    // Grant premium features
-}
+// Write a value back to HealthKit
+despia('writehealthkit://HKQuantityTypeIdentifierBodyMass//74.5');
+
+// Observe changes and POST to your server whenever HealthKit updates
+despia('healthkit://observe?types=HKQuantityTypeIdentifierStepCount&frequency=hourly&server=https://api.example.com/webhook?user=USER_ID');
 ```
 
-**Perfect for:**
+Pass any valid `HKQuantityTypeIdentifier`, `HKCategoryTypeIdentifier`, `HKWorkoutTypeIdentifier`, or `HKCharacteristicTypeIdentifier` directly. Sleep, workouts, heart rate, body mass, and all other HealthKit types are supported. Full docs: [https://setup.despia.com](https://setup.despia.com)
 
-- Implementing "Restore Purchases" buttons required by App Store guidelines
-- Verifying user entitlements on app launch
-- Checking subscription status and renewal information
-- Server-side receipt validation using raw receipt data
-- Cross-platform purchase history retrieval
+---
 
-**Important Notes:**
+### AdMob Inline Ads
 
-- This feature requires native capabilities which are fully provided by the `despia-native` npm package
-- No additional native libraries are needed
-- Please follow the installation instructions for the `despia-native` npm package closely
-- Implementation as mentioned is critical for App Store compliance
+Despia implements Google's WebView API for Ads on both platforms, connecting the Mobile Ads SDK directly to the WebView so AdMob ads render as real DOM elements inside your web UI, not as native overlays. Enabled from **Despia > App > Settings > AdMob**. Requires a rebuild after enabling.
 
-### Read Clipboard Workflow
+Once enabled, serve ads using standard AdSense, Google Publisher Tag, or IMA for HTML5 tags. No Despia SDK calls needed on the web side.
 
-Read clipboard data from the device:
+```html
+<!-- AdSense banner -->
+<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"
+    data-ad-client="ca-pub-XXXXXXXXXXXXXXXX"></script>
+<ins class="adsbygoogle"
+     style="display:block"
+     data-ad-client="ca-pub-XXXXXXXXXXXXXXXX"
+     data-ad-slot="YYYYYYYYYY"
+     data-ad-format="auto"
+     data-full-width-responsive="true"></ins>
+<script>(adsbygoogle = window.adsbygoogle || []).push({});</script>
+```
 
-```javascript
-// First, install the package:
-// npm install despia-native
+Because ads are real DOM elements, placements that are impossible with native overlay ads — banners between feed cards, mid-article units, rewarded content gates, pre-roll video — are straightforward CSS and JavaScript.
 
-// Then import it:
-import despia from 'despia-native';
+Google WebView API for Ads references: [iOS](https://developers.google.com/admob/ios/browser/webview/api-for-ads) | [Android](https://developers.google.com/admob/android/browser/webview/api-for-ads) | Full Despia docs: [https://setup.despia.com](https://setup.despia.com)
 
-// Read clipboard data
-const clipboardData = await despia('getclipboard://', ['clipboarddata']);
+---
 
-// Access the clipboard content
-const content = clipboardData.clipboarddata;
+### Web Payment Request API
 
-// Display or process the clipboard content in your application
-console.log('Clipboard content:', content);
-```
+Despia polyfills support for the Web Payment Request API, enabling native Apple Pay on iOS and Google Pay on Android directly from your web UI. This is a known pain point with standard WebViews — Despia handles it by importing WebKit's Payment Request support on Android (`androidx.webkit:webkit:1.14.0` with `WebSettingsCompat.setPaymentRequestEnabled`) and the required Google Pay intent queries, and on iOS via WKWebView's built-in Apple Pay support.
 
-**How it works:**
+```js
+// Standard Web Payment Request API — works in Despia without any native code changes
+const request = new PaymentRequest(
+  [{ supportedMethods: 'https://apple.com/apple-pay' }], // or Google Pay method
+  {
+    total: { label: 'Total', amount: { currency: 'USD', value: '9.99' } }
+  }
+);
 
-- **Read clipboard**: Use `getclipboard://` with `['clipboarddata']` to retrieve the current clipboard content
-- **Access content**: The clipboard content is available through the `.clipboarddata` property of the returned object
-- **Native support**: Works on both iOS and Android platforms
+const result = await request.show();
+await result.complete('success');
+```
 
-**Perfect for:**
+Apple Pay on iOS and Google Pay on Android both work via the standard Web Payment Request API. No Despia-specific calls required. Reference: [Google Pay in Android WebView](https://developers.google.com/pay/api/android/guides/recipes/using-android-webview)
 
-- Reading text from the clipboard
-- Processing clipboard content in your app
-- Implementing paste functionality
-- Clipboard content validation
+---
 
-### Open App Settings Workflow
+### Web Storage APIs
 
-Open your app's native settings page where users can manage permissions:
+Despia runs your app on a secure origin (`http://localhost` via Local Server, or your remote URL). This means all standard web storage APIs work without any restrictions or workarounds, unlike other hybrid frameworks that require hacks or fall back to `file://` origins:
 
-```javascript
-// First, install the package:
-// npm install despia-native
+```js
+// localStorage works normally
+localStorage.setItem('userId', 'user123');
+const userId = localStorage.getItem('userId');
 
-// Then import it:
-import despia from 'despia-native';
+// IndexedDB works normally
+const db = await indexedDB.open('myapp', 1);
 
-// Open native app settings
-despia("settingsapp://");
+// Web Crypto works normally
+const key = await crypto.subtle.generateKey(
+  { name: 'AES-GCM', length: 256 },
+  true,
+  ['encrypt', 'decrypt']
+);
 ```
 
-**How it works:**
+For data that needs to survive uninstall and reinstall, or be locked behind Face ID, use [Identity Vault](#identity-vault) instead.
 
-- **Opens native settings**: Navigates to your app's settings page in the device's system settings
-- **Permission management**: Users can manage permissions like notifications, location, camera, microphone, and more
-- **One-time prompts**: Great for directing users to activate features that you can only ask once, like location or push notifications
+---
 
-**Perfect for:**
+### Local Server
 
-- Directing users to enable location services after they've denied the initial prompt
-- Helping users enable push notifications if they initially declined
-- Managing camera, microphone, or other permission settings
-- Providing a way to access app settings when permission prompts can't be shown again
+> **Built-in OTA updates. True offline support. Host with your existing web hosting. No proprietary infrastructure required.**
 
-**Example Usage:**
+No service workers. No workarounds. The Local Server downloads your complete web build to the device and serves it from a native on-device HTTP server at `http://localhost`. The app loads from device storage at native speed and works completely offline from the first launch after hydration.
 
-```javascript
-// Check if location permission is needed
-if (!navigator.geolocation) {
-  // Open settings so user can enable location
-  despia("settingsapp://");
-}
-
-// After user denies push notification permission
-// Provide a button to open settings
-function openNotificationSettings() {
-  despia("settingsapp://");
-}
-```
+When the user has a connection, Despia checks for updates in the background by comparing the `deployed_at` timestamp in your manifest. If a new build is available it downloads silently while the user continues using the app. The update applies on the next launch. If the connection is not stable, the locally cached version is served without interruption.
 
-### OneSignal Push Notifications Workflow
+You host the manifest and assets on your own infrastructure — Netlify, Vercel, AWS, your own server, anywhere. No proprietary hosting, no per-MAU fees, no vendor lock-in on your delivery pipeline.
 
-Set up OneSignal push notifications with external user IDs to connect your database user IDs with device registrations:
-
-```javascript
-// First, install the package:
-// npm install despia-native
+```bash
+npm install --save-dev @despia/local
+```
 
-// Then import it:
-import despia from 'despia-native';
+```js
+// vite.config.js (also available for Webpack, Rollup, Nuxt, SvelteKit, Astro, Remix, esbuild)
+import { defineConfig } from 'vite';
+import { despiaLocalPlugin } from '@despia/local/vite';
 
-// On every app load, set the external user ID
-// This connects your logged-in user ID with the device's OneSignal registration
-despia(`setonesignalplayerid://?user_id=${YOUR_LOGGED_IN_USER_ID}`);
+export default defineConfig({
+  plugins: [
+    despiaLocalPlugin({
+      outDir: 'dist',
+      entryHtml: 'index.html'
+    })
+  ]
+});
 ```
 
-**Setup Requirements:**
-
-1. **Create a OneSignal account** and configure your app
-2. **Set up iOS (Apple Push Key) and Android (Firebase)** configurations in OneSignal
-3. **Important**: When configuring OneSignal, select **"Native iOS"** and **"Native Android"** platforms since Despia apps are native mobile applications
-4. **Add your OneSignal App ID** to your Despia project settings
-
-**How it works:**
-
-- **External User IDs**: External IDs (your database user IDs) are now the default and recommended approach
-- **Player IDs**: Player IDs still work but are no longer suggested
-- **Device Registration**: Devices are automatically registered in OneSignal when the app is installed
-- **User Connection**: Calling `setonesignalplayerid://` on every app load connects your user ID with the device registration
-
-**Backend Integration Required:**
-
-You'll need to create a backend endpoint to send notifications using OneSignal's REST API with external user IDs:
-
-```javascript
-// Backend API endpoint - send to specific user
-const sendNotification = async (externalUserId, title, message) => {
-  const response = await fetch('https://onesignal.com/api/v1/notifications', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': 'Basic YOUR_REST_API_KEY'
-    },
-    body: JSON.stringify({
-      app_id: 'ONESIGNAL-APP-ID',
-      include_external_user_ids: [externalUserId], // Array with single ID
-      headings: { en: title },
-      contents: { en: message }
-    })
-  });
-  return response.json();
-};
+Or run via CLI after any build:
+
+```bash
+npx despia-local dist
 ```
 
-**Example Usage:**
+The plugin generates `despia/local.json` in your output directory alongside your assets. Deploy both to your existing web host. That is the entire setup.
 
-```javascript
-// In your app initialization or login flow
-function initializeApp(userId) {
-  // Set external user ID on every app load
-  despia(`setonesignalplayerid://?user_id=${userId}`);
-  
-  // Register for push notifications
-  despia('registerpush://');
+```json
+{
+  "entry": "/index.html",
+  "deployed_at": "1737225600000",
+  "assets": [
+    "/index.html",
+    "/assets/app.abc123.css",
+    "/assets/app.def456.js"
+  ]
 }
-
-// Send local push notification
-despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
 ```
 
-**Important Notes:**
+Full docs: [https://setup.despia.com/local-server/introduction](https://setup.despia.com/local-server/introduction)
 
-- This feature requires native capabilities which are fully provided by the `despia-native` npm package
-- No additional native libraries are needed
-- Please follow the installation instructions for the `despia-native` npm package closely
-- Implementation as mentioned is critical for proper push notification delivery
-- Call `setonesignalplayerid://` on every app load to ensure the user ID is always connected
+---
 
-**Perfect for:**
+### Local CDN
 
-- Sending targeted notifications to specific users
-- User-based notification management
-- Cross-device notification delivery
-- Personalized push notification campaigns
+Cache individual remote files on-device for offline playback and background downloads. Downloads use native OS transfer APIs (NSURLSession on iOS, WorkManager on Android) and continue when the app is closed, with automatic retry on network failure. On iOS a Live Activity shows real-time download progress. On Android a native notification appears in the system tray. Both require no setup.
 
-### Haptic Feedback
+```js
+// Called by the native runtime when a download completes.
+// This is a global function, not an event listener.
+window.contentServerChange = (item) => {
+  // item.local_cdn  - localhost URL to use for playback
+  // item.cdn        - original remote URL
+  // item.index      - the uniqueId you passed to the write call
+  // item.size       - file size in bytes
+  // item.status     - "cached" when complete
+  // item.local_path - absolute path on the device
 
-All haptic feedback commands have no response - they provide immediate tactile feedback:
+  console.log('Cached:', item.index, item.local_cdn);
+  addToDownloadsList(item);
+};
 
-```javascript
-// Basic haptic feedback
-despia('lighthaptic://');    // Light haptic feedback - subtle vibration
-despia('heavyhaptic://');    // Heavy haptic feedback - strong vibration
+// Fire and forget. Do not await with a watch key; large downloads take longer than the SDK's
+// 30-second variable-watch window. Use window.contentServerChange to receive the result instead.
+despia(
+  `localcdn://write?url=${remoteUrl}&filename=videos/clip.mp4&index=clip_1&push=true&pushmessage="Download complete"`
+);
 
-// Contextual haptic feedback
-despia('successhaptic://');  // Success haptic feedback - positive confirmation
-despia('warninghaptic://');  // Warning haptic feedback - attention alert
-despia('errorhaptic://');    // Error haptic feedback - negative feedback
+// Read cached items by ID
+const { cdnItems } = await despia(
+  `localcdn://read?index=${encodeURIComponent(JSON.stringify(['clip_1']))}`,
+  ['cdnItems']
+);
 
-// Use cases:
-// - Button press feedback (light/heavy)
-// - Success notifications (successhaptic)
-// - Warning alerts (warninghaptic)
-// - Error feedback (errorhaptic)
-// - UI interaction confirmation
+// Or query everything in the cache
+const { cdnItems: all } = await despia('localcdn://query', ['cdnItems']);
 ```
 
-### Biometric Authentication
-
-Biometric authentication requires setting up callback functions before running the command:
-
-```javascript
-// Step 1: Set up the biometric authentication SDK
-if (!document.getElementById("bioauth-sdk")) {
-    const script = document.createElement("script")
-    script.id = "bioauth-sdk"
-    script.type = "text/javascript"
-    script.textContent = `
-        function onBioAuthSuccess() {
-            window.bioauthSuccess()
-        }
-        function onBioAuthFailure(errorCode, errorMessage) {
-            window.bioauthFailure(errorCode, errorMessage)
-        }
-        function onBioAuthUnavailable() {
-            window.bioauthUnavailable()
-        }
-    `
-    document.head.appendChild(script)
-}
-
-// Step 2: Define your callback functions
-window.bioauthSuccess = function() {
-    if (navigator.userAgent.includes("despia")) {
-        console.log("Biometric authentication successful");
-        // Handle successful authentication
-        // Redirect user, unlock features, etc.
-    }
-}
-
-window.bioauthFailure = function(errorCode, errorMessage) {
-    if (navigator.userAgent.includes("despia")) {
-        console.log("Biometric authentication failed:", errorCode, errorMessage);
-        // Handle authentication failure
-        // Show error message, fallback to password, etc.
-    }
-}
+Use the `local_cdn` URL for playback:
 
-window.bioauthUnavailable = function() {
-    if (navigator.userAgent.includes("despia")) {
-        console.log("Biometric authentication unavailable");
-        // Handle when biometric auth is not available
-        // Fallback to alternative authentication method
-    }
-}
-
-// Step 3: Trigger biometric authentication
-despia('bioauth://');
+```html
+<video src="http://localhost:7777/localcdn/videos/clip.mp4" controls></video>
 ```
 
-### App Information & Device Data
-
-```javascript
-// Get app version information
-const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
-console.log('App Version:', appInfo.versionNumber);
-console.log('Bundle Number:', appInfo.bundleNumber);
+**HTTP upload API** (Local Server only)
 
-// Get device UUID (native device ID)
-const deviceData = await despia('get-uuid://', ['uuid']);
-console.log('Device UUID:', deviceData.uuid);
+```js
+const host = window.location.host; // Do not hardcode the port; it rotates per session
+const fd = new FormData();
+fd.append('file', fileInput.files[0]);
 
-// Get store location
-const storeData = await despia('getstorelocation://', ['storeLocation']);
-console.log('Store Location:', storeData.storeLocation);
-
-// Check tracking permission
-const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);
-console.log('Tracking Disabled:', trackingData.trackingDisabled);
+const res  = await fetch(`http://${host}/api/upload`, { method: 'POST', body: fd });
+const data = await res.json();
+// { success: true, fileName: "video.mp4", url: "http://localhost:7777/files/video.mp4" }
 ```
 
-### UI Controls & Styling
 
-```javascript
-// Loading spinner controls
-await despia('spinneron://');   // Show loading spinner
-await despia('spinneroff://');  // Hide loading spinner
+| Method             | Storage Path | URL Pattern                            |
+| ------------------ | ------------ | -------------------------------------- |
+| `localcdn://write` | `/localcdn/` | `localhost:{PORT}/localcdn/{filepath}` |
+| `/api/upload`      | `/files/`    | `localhost:{PORT}/files/{filename}`    |
 
-// Full screen mode
-await despia('hidebars://on');  // Hide status bar (full screen)
-await despia('hidebars://off'); // Show status bar
 
-// Status bar styling
-await despia('statusbarcolor://{255, 255, 255}');     // Set status bar background color (RGB)
-await despia('statusbartextcolor://{black}');         // Set status bar text color (black/white)
-```
+Full docs: [https://setup.despia.com/local-cdn/introduction](https://setup.despia.com/local-cdn/introduction)
 
-### File & Media Operations
+---
 
-```javascript
-// Take screenshot (saves to device)
-await despia('takescreenshot://');
+## Capability Reference
 
-// Save image from URL
-await despia('savethisimage://?url=https://example.com/image.jpg');
+A full index of native capabilities built into Despia.
 
-// Download file from URL
-await despia('file://https://example.com/document.pdf');
+**Core runtime:** Hardware-backed Identity Vault, Face ID / Touch ID / fingerprint biometrics, background GPS (including Samsung, Huawei, Xiaomi, and OnePlus), contacts, clipboard, haptics (5 types), native file system access, image saving, background audio, local push notifications, status bar controls, safe area CSS variables, device orientation per device class, prevent zoom, prevent sleep, fullscreen mode, splash screen, iOS Home Widgets, Siri Shortcuts, native share dialog, AirPrint, screen shield, PkPass for iOS and Android mobile wallets.
 
-// Share app with message and URL
-await despia('shareapp://message?=Check%20out%20this%20app&url=https://myapp.com');
-```
+**Integrated SDK bridges:** RevenueCat (purchases, subscriptions, restore, paywalls), OneSignal (remote push with external user ID mapping), AppsFlyer (attribution, deep linking, event tracking), AdMob (advertising), HealthKit (all major health identifiers).
 
-### Scanning Mode
+**Infrastructure:** ATT compliance, vendor ID tracking, device ID tracking via iCloud KV and Android App Backup, store location access, jailbreak detection with configurable blocking, App Clips, Share Extensions, and Home Widget management from the Despia editor.
 
-```javascript
-// Control scanning mode
-await despia('scanningmode://auto');  // Auto scanning mode
-await despia('scanningmode://on');    // Enable scanning
-await despia('scanningmode://off');   // Disable scanning
-```
-
-### App Reset
+**Native web interception:** `<input type="file">` routes to a native action sheet. The `capture` attribute opens the native camera. `accept="image/*"` or `accept="video/*"` opens the native media gallery. Deeplinks and HTTPS deeplinks are handled natively.
 
-```javascript
-// Reset app (use with caution)
-await despia('reset://');
-```
+---
 
-### Native Safe Area
+## Safe Area
 
-Access native safe area insets via CSS custom properties:
+Despia exposes top and bottom safe area insets as CSS custom properties set by the native runtime.
 
 ```css
-/* Use native safe area insets in your CSS */
-.my-element {
+.header {
   padding-top: var(--safe-area-top);
+}
+
+.footer {
   padding-bottom: var(--safe-area-bottom);
 }
 
-/* Full height with safe area consideration */
 .full-height {
   height: calc(100vh - var(--safe-area-top) - var(--safe-area-bottom));
 }
 ```
 
-**Note:** Despia only supports top and bottom safe area insets. Left and right safe area variables are not available.
+Note: left and right safe area variables are not available.
 
-These CSS variables are automatically provided by the Despia native runtime and represent the device's safe area insets (notches, home indicators, etc.).
+---
 
+## Extending the Runtime
 
+A common concern when adopting any hybrid framework is lock-in: can you escape the custom protocol API later?
 
-## API Reference
+The bridge pattern is consistent across both platforms and fully open. You can intercept any custom scheme in `WebViewController.swift` on iOS or `MainActivity.java` on Android, run native code, and write the result back to the WebView. The SDK resolves custom bridges identically to built-in capabilities. No special registration or plugin system required.
 
-### `despia(command, watch?)`
+**On the bridge architecture**
 
-- **command** (string): The Despia protocol command (e.g., `'lighthaptic://'`)
-- **watch** (string[], optional): Array of variable names to watch for in the response
+The scheme bridge is simple by design and has been running in production since 2011. A command goes in as a plain string, the native layer acts on it, and the result is written back as a named window variable. No serialization, no abstraction layers. Input is sanitized on the native side.
 
-Returns a Promise that resolves when all watched variables are available:
-- **Single variable**: 30-second timeout with observation. `null` values resolve immediately (useful for error/not-found signals). Other empty placeholders (`undefined`, `"n/a"`, `{}`, `[]`) are ignored. Promise always resolves; on timeout it resolves with `undefined`.
-- **Multiple variables**: Uses VariableTracker with 5-minute auto-cleanup. All variables must have non-null values. Any `null` value blocks resolution until all variables have real values.
+For file uploads, streaming, and binary data, Despia uses the on-device HTTP server at `http://localhost` rather than the scheme bridge. The two channels handle what each is suited for.
 
-### Timeout behavior
+A typed plugin system for community contributions and custom native development is in progress, alongside the open source Extension system planned for mid/late 2026.
 
-When you call `despia(command, ['someVariable'])`, the SDK waits up to 30 seconds for
-`window.someVariable` to be set by the native runtime. If it appears earlier, the
-Promise resolves with that value. If it is never set, the Promise still resolves
-after 30 seconds with `undefined` and a timeout is logged to the console. This
-prevents hanging Promises for long-running or failing native operations.
+**iOS: WebViewController.swift**
 
-### Fresh-data behavior
+```swift
+if requestURL.absoluteString.hasPrefix("mycustom://") {
+    let result = runMyNativeCode()
+    webView.evaluateJavaScript("window.myResult = '\(result)';")
+    decisionHandler(.cancel)
+    return
+}
+```
 
-Before observing, watched variables are cleared to avoid resolving on stale values.
-The observer behavior differs by variable count:
+**Android: MainActivity.java**
 
-- **Single variable**: `null` is treated as a valid resolution value (useful for error/not-found signals). The observer ignores other empty placeholders (`undefined`, `"n/a"`, `{}`, `[]`) and requires the value to change from its baseline before resolving.
+```java
+if (url.startsWith("mycustom://")) {
+    String result = runMyNativeCode();
+    webView.evaluateJavascript("window.myResult = '" + result + "';", null);
+    return true;
+}
+```
 
-- **Multiple variables**: All variables must have non-null values. The observer ignores empty placeholders (`undefined`, `null`, `"n/a"`, `{}`, `[]`) and requires all values to change from their baseline before resolving.
+**Call it from your web app**
 
-This ensures each call waits for a fresh write from the native side.
+```js
+import despia from 'despia-native';
 
-### Direct Property Access
+const data = await despia('mycustom://', ['myResult']);
+console.log(data.myResult);
+```
 
-Access any window variable directly through the despia object:
+Adding custom native code requires exporting the project and deploying outside of Despia's hosted CI/CD pipeline. Despia offers full Xcode and Android Studio project export for developers who need it. You own the code and can build and ship entirely independently at any point.
 
-```javascript
-despia.variableName // Equivalent to window.variableName
-```
+Each lifetime Despia license applies to one specific Despia project bound to one bundle ID, and grants export, editing, self-hosting, and custom CI/CD rights for that project only. Associated repositories must remain private. Reuse beyond that scope requires separate licensing or white-label terms.
 
-## Despia Protocol Format
+Projects and their licensing rights can be transferred between Despia accounts. Contact [license@despia.com](mailto:license@despia.com) for transfers or licensing questions, and [whitelabel@despia.com](mailto:whitelabel@despia.com) for white-label use cases.
 
-Despia uses a simple protocol format for all native integrations:
+> **Coming mid/late 2026:** An official open source Despia Extension system is currently in active development. It will allow developers to build and distribute custom native capabilities that work directly within the Despia editor, with no Xcode or Android Studio required.
 
-```
-feature://action?parameters
-```
+---
 
-Examples:
-- `lighthaptic://`
-- `getappversion://`
-- `revenuecat://purchase?external_id=user_777&product=monthly_premium`
-- `revenuecat://launchPaywall?external_id=user_777&offering=default`
-- `getpurchasehistory://`
-- `getclipboard://`
-- `settingsapp://`
-- `setonesignalplayerid://?user_id=user123`
-- `registerpush://`
-- `setvault://?key=userId&value=user123&locked=false`
-- `readvault://?key=userId`
-- `writevalue://{JSON-ENCODED-STRING}`
-- `readvalue://`
-- `oauth://?url=https://provider.com/oauth/authorize`
-- `requestcontactpermission://`
-- `savethisimage://?url=https://example.com/image.jpg`
-
-## Available Despia Features
-
-Your app can access these native features:
-
-- **Native Widgets** - Create widgets with SVG and refresh time
-- **In-App Purchases** - RevenueCat integration with external user IDs
-- **Restore Purchases** - Retrieve purchase history from App Store and Google Play
-- **Contact Access** - Request permissions and read contacts
-- **Background Location** - Native tracking with browser geolocation API
-- **Push Notifications** - OneSignal integration with external user IDs and local push messages
-- **Haptic Feedback** - Light, heavy, success, warning, and error feedback
-- **App Information** - Version numbers, bundle numbers, device UUID
-- **Clipboard Access** - Read clipboard content from device
-- **Screenshots** - Take device screenshots
-- **Scanning Mode** - Auto, on, and off scanning controls
-- **Store Location** - Get store location data
-- **File Operations** - Save images and download files
-- **Identity Vault** - Persistent cross-device storage with optional biometric protection
-- **Local Storage** - Cross-platform device storage (cleared on uninstall)
-- **OAuth Authentication** - Secure OAuth flows with native browser sessions
-- **App Control** - Reset app and disable tracking
-- **App Settings** - Open native app settings for permission management
-- **UI Controls** - Loading spinners and full screen mode
-- **Sharing** - Share app with custom messages and URLs
-- **Status Bar** - Control colors and text colors
-- **Biometric Authentication** - Native biometric auth with callbacks
-
-## TypeScript Support
-
-Full TypeScript definitions are included:
-
-```typescript
-import despia from 'despia-native';
+## Web Apps vs React Native
 
-// Type-safe usage with Despia commands
-const result: { versionNumber: string; bundleNumber: string } = await despia(
-  'getappversion://', 
-  ['versionNumber', 'bundleNumber']
-);
+This SDK is for web apps running inside the Despia runtime: React, Vue, Angular, Svelte, Next.js, Vite, Nuxt, and vanilla JavaScript.
 
-// Direct property access
-const deviceInfo: any = despia.deviceInfo;
-```
+It is not for React Native, Expo, or native mobile development.
 
-## Integration with Despia
+---
 
-Despia operates through a streamlined protocol handler system, allowing you to invoke native features using the global `window.despia` object. This npm package is the JavaScript SDK that makes your web app communicate with Despia's native runtime. The SDK provides:
+## Publishing to the App Store and Google Play
 
-- **Command Queuing** - Sequential execution of Despia commands via `window.despia` setter
-- **Variable Watching** - Async monitoring of response variables
-- **Hybrid Framework Compatible** - Works with Despia's hybrid app framework
-- **Direct Access** - Proxy-based access to window variables
+Despia provides fully automated iOS and Android store deployment from the web editor. No Mac required. One-click deployment spins up Mac Mini build infrastructure in the cloud, handles code signing, provisioning, and submits to both the App Store and Google Play — entirely from a browser.
 
-### How It Works
-Despia's protocol handler system eliminates the need for complex libraries or dependencies, making it compatible across various frameworks and platforms. The SDK uses the setter pattern to execute commands:
+Full deployment docs: [https://setup.despia.com/deployment/apple-ios/automatic](https://setup.despia.com/deployment/apple-ios/automatic)
 
-```javascript
-// When you call:
-despia('lighthaptic://');
+---
+
+## Open Source
+
+
+| Package                                                                    | Description           | License |
+| -------------------------------------------------------------------------- | --------------------- | ------- |
+| [despia-native](https://www.npmjs.com/package/despia-native)               | JavaScript SDK        | MIT     |
+| [@despia/local](https://www.npmjs.com/package/@despia/local)               | Offline asset bundler | MIT     |
+| [despia-version-guard](https://www.npmjs.com/package/despia-version-guard) | OTA version gating    | MIT     |
 
-// It internally executes:
-window.despia = 'lighthaptic://';
-```
 
-This streamlined approach triggers Despia's native runtime to handle the native command, providing seamless access to device capabilities directly from your web codebase.
+Native capability implementations are written in Swift and Java and included in full on project export.
+
+---
+
+## Support
+
+For questions or concerns regarding this package, contact the Despia team at [npm@despia.com](mailto:npm@despia.com).
+
+---
 
 ## License