Skip to main content
Native rebuild required. Extension files must be compiled into a rebuilt native app. Uploading files does not change an installed binary. Automatic discovery of hosted /despia/extensions.json during a normal rebuild is under review and is not yet confirmed in deployed builds.
V3 Extensions let you add your own native code to a Despia V3 app. You write the Swift (iOS) and Kotlin or Java (Android) files, describe them in a JSON manifest, and serve them from your web app. A native rebuild compiles them into your app. Your web code calls the included extension with the Despia JS SDK. For example, read the Recorder state from a client event:
Use V3 Extensions when you need a native capability that Despia does not offer as a feature yet, or when you need full control over the native code. The ready-made extensions below include source you can inspect and customize.

Ready-made extensions

These ready-made extensions include native source you can adapt. Copying it to your website supplies source for a native rebuild. Read the installation steps and platform limits before adapting an extension. Browse, clone or fork the public source to inspect and understand it. Public GitHub forks remain public. For private development, licensed users can clone the source into a private workspace or private version-control repository. Customize an extension for your licensed app, or use its source as a reference when developing a new native capability. The Despia-authored code uses the Despia V3 Extension Source-Available Commercial License. It is proprietary, not open source. Local inspection copies and GitHub forks for inspection are permitted under the license. Other copying, modification, building, execution and deployment require a valid Despia commercial license for the particular app and operating system, plus a valid Despia project for that app. The standard price is USD 249 per application per operating system. iOS and Android require separate licenses. Keep the LICENSE, copyright and third-party notices with your copies; standalone redistribution is restricted except for the GitHub forks expressly permitted by the license. Read each repository’s LICENSE for the full terms. Earlier license grants and third-party rights remain intact. Your own extension code remains yours. Start with a ready-made extension, or use its Swift, Kotlin or Java code as a reference for a new native capability. You can change the native implementation and its web API within the supported extension contract. Declare its files, routes and dependencies in the manifest, and account for the platform APIs, signing, entitlements and store policies it needs. Changed source requires build verification and a new native build.
Experimental. V3 only.
  • V3 Extensions work only in Despia V3. They are never migrated to V4. V4 has its own first-party plugins and plugin system instead. You can stay on V3 as long as you want.
  • You own and maintain the native code. That includes the code you copy from an extension.
  • Despia provides the ready-made extensions and the extension system. Despia does not support code you have customised.

AI skill

An Agent Skill teaches your coding agent this page and references for Background Recorder, Live Activities and Home Widgets, so it can write an extension without web access. It is for the Despia V3 runtime only. Install it from the extension-skill repository:
Or copy skills/despia-v3-extensions from that repository into your project’s .claude/skills/ folder.

Frameworks, app builders and editors

The Despia JS SDK works with React, Vue, Svelte, Next.js, TanStack and HTML apps. Import it in your project, then call it from a client lifecycle hook or click handler inside the installed Despia V3 app. React and Vue both have browser access in client code. Server rendering must not execute native calls. For Lovable, Base44, Replit or another app builder, use a project that supports custom JavaScript and serves the extension files at their exact HTTPS paths. A route that returns your web app’s HTML instead of the requested JSON or Swift file needs a hosting fix before build verification. Edit the native files in your repository with Claude Code, Codex, Cursor or your usual editor. Connect the builder’s GitHub repository when you need direct access to its static files. The native code must pass build verification and be compiled into a native rebuild. A browser preview alone does not provide native extension features.

How it works

1

The manifest declares the extension

Each extension has a manifest.json. It declares the extension id, its routes, the typed parameters of each route, the answer variable and callback of each route, its events, and the native files for each platform.
2

Despia builds it into your app

Your files are served from your app’s own HTTPS origin. The extension build process fetches and verifies the index, source files and pinned dependencies, then compiles them into a new native build. Signed inputs bind the build to your app. Changed source needs fresh build verification and a native rebuild; it cannot be applied over-the-air.
3

Your web app calls a route

The page sends extension://<id>/<route>?<params>. In a build that includes the extension runtime, it first checks the call: the extension and route exist, only declared parameters are present, and each value has the declared type. Only then does it call your native handler.
4

The answer comes back once

Every admitted call gets one terminal answer in its calling document. The runtime sets the route’s answer variable on window and then calls the route’s callback with it.

Source and build verification

The build verifies source hashes, the complete pinned dependency graph, app identity and the signed build lock. Signing checks also compare the compiled artifact with those inputs. These checks protect build hosts, signing keys and app boundaries. You remain responsible for the behavior and maintenance of your extension code. Apple-managed capabilities, provisioning and store requirements still apply.

Folder layout in your web app

Put the files in your web app’s public folder, so they are served from your app’s own origin:
extensions.json names your app and lists the extension folders:
public/despia/extensions.json
extensions.json holds the app identity and lists the extension folders. The three identity values:
  • client_id: your app’s id in Despia. Open your app in the Despia editor and copy the id from the address bar: in a URL ending /builder/<id>, the part after /builder/ is your client id.
  • ios_bundle_id: your app’s iOS bundle id, the one Despia builds your iOS app with.
  • android_package: your app’s Android package name, the one Despia builds your Android app with.
The signed build inputs bind the extensions to exactly this app. If a value does not match the app being built, the build stops with an error that names the value (NX-L013 for client_id). extensions.json lists 1 to 8 folders, and each folder name matches [a-z][a-z0-9]{1,23}. Any other key is refused, including manifest_version. Each folder has its own manifest.json with a version field. A folder listed twice is also refused. The folder name is the id in the scheme. public/despia/recorder/ is called as extension://recorder/<route>. File paths in manifest.json are relative to the extension’s folder and start with ios/ or android/, for example ios/app/RecorderExtension.swift. An extension can only name files inside its own folder. A manifest.json that also sets "id" is refused, because the folder name is the id. To add an extension to your app, copy its folder under public/despia/ and add its name to extensions.json. Build verification covers extensions.json, every manifest.json and each referenced file. A change to any of them needs a fresh verified snapshot and native rebuild.
Calls are accepted only from the top-level page of your app’s own HTTPS origin, or from origins you list in bridge.allowed_origins. Iframes, other origins, popups and page sheets get no answer.

Declaring routes, outputs and events

Each route in manifest.json declares its parameters and its output. The output names the window variable that receives the answer and the callback that is called with it:
public/despia/recorder/manifest.json (excerpt)
For this route the runtime runs window.recorderStart = <result> and then window.onRecorderStart(window.recorderStart). If you leave output out, the defaults are <id><Route>Result for the variable and on<Id><Route>Result for the callback. For the route above that would be recorderStartResult and onRecorderStartResult. Events are declared next to the routes, each with its own callback:
Your native code sends an event with emit("state", data), and the page’s window.onRecorderState(data) runs. With scope: "document" (the default), only pages that have called the extension receive it. With scope: "app", the trusted top-level page that is loaded receives it. Events are notifications only. Always read the current state through a route.

Parameter types

Parameters are declared per route. Anything not declared is refused with bad_request. An int may declare min and max anywhere in the range -(2^53-1) to 2^53-1 (the default is -2^31 to 2^31-1), and a value outside it is refused. A string’s max is at most 4096. Keep large data on the native side and pass identifiers through the bridge. A call URL is at most 8192 characters, and each extension accepts up to 20 calls per second.

Calling a route with the Despia JS SDK

Install the SDK in your web project:
Import despia from despia-native. The examples use the published 1.0.28 API. A command without watched variables resolves when queued, not when the native operation finishes. Pass one answer variable when you need a result:
recorderStatus is the output variable declared by the Recorder manifest. Serialize calls that watch the same declared variable: await one before starting the next, including calls from other components. Sharing a watched variable across concurrent requests can mix responses. The SDK resolves native error answers as well as successes. Read the full envelope through reply.recorderStatus, including ok, code, error and data. Check answer.ok; a native failure does not reject the SDK promise. A single-variable watch resolves to undefined after 30 seconds if no value arrives. That timeout does not cancel native work. Inspect the returned native envelope rather than assuming every command uses the same error shape.

React

Importing the SDK is safe during server rendering. Call it from a client event or lifecycle hook. In Next.js, put the component behind a client boundary. Keep calls sharing an output variable sequential, including calls from other components.

Vue

Use the same SDK function from a Vue click handler. For an automatic call, use onMounted, never server setup execution.

Events

Use the extension’s state or journal routes to recover after page loads. Events are notifications, not a replay guarantee. Register the declared native callback before starting the operation, and remove your handler when its component unmounts:
The SDK proxy reads existing browser properties such as despia.onRecorderState. It does not register event handlers when you assign to that proxy. Event registration above uses the native callback global explicitly; commands still go through the SDK. Run this registration only in the browser. The extension manifest defines each event’s callback and scope.

The result

Every answer has the same shape: An error carries a code and a message, and nothing else. If the page must tell failures apart, give each one its own code.

Error codes

In a build containing the extension runtime, a call to an extension or route that is not registered answers your explicit callback if you gave one; otherwise it fires despia-feature-not-included. A build without the extension runtime cannot answer these calls. For missing responses, see Troubleshooting extension builds.

The iOS handler

The manifest names the entry type in ios.app.entry_type. It is a class marked @MainActor that conforms to NativeExtension. From the recorder extension:
ios/app/RecorderExtension.swift (excerpt)
  • handle(_:) runs on the main actor for every checked call. Return .ok([...]) with your data, or .error(code:message:).
  • didLaunch(_:) runs once at every launch, before any web view exists, also when iOS launches the app in the background.
  • After any await in handle, check call.isActive before you start something new. Once the route’s timeout_ms has passed, the page already has its timeout answer.
  • Do not mark handle nonisolated or @concurrent. Do background work explicitly and return to the main actor before you touch extension state.
NativeExtContext gives you dataDirectory, appGroupIdentifier(_:), appGroupURL(_:), backgroundSessionIdentifier(_:), isApprovedURL(_:route:param:), onExpiration(of:_:), emit(_:_:) and log(_:). Only these types are supported API.

Lifecycle hooks

Each hook is called only when its name is listed in ios.app.lifecycle. The runtime stays the app’s only system delegate. handleBackgroundURLSession(name:completion:) receives events for a session declared in background_url_sessions. Set a background task’s expiration handler with context.onExpiration(of:_:), never task.expirationHandler.

The Android handler

The manifest names the entry class in android.entry_class. It implements com.despia.nativeext.NativeExtension. From the recorder extension:
android/recorder/java/despia/ext/recorder/RecorderExtension.java (excerpt)
  • handle gets the call and a reply callback. Call reply.reply(ExtResult.ok(json)) or reply.reply(ExtResult.error(code, message)) once.
  • onCreate runs in Application.onCreate of the main process, before any activity or WebView. It also runs when WorkManager or a receiver starts the process. List application_create in android.lifecycle.
ExtContext gives you app(), dataDir(), emit(event, json), log(msg), resultKey(name) and isApprovedUrl(url, route, param). Use isApprovedUrl to check a stored URL again before delayed work, such as a Worker or a service, sends anything to it.

Patterns the extensions use

The bridge answer is a JavaScript string with typed parameters. These conventions keep that workable.
  • Bytes. A parameter named hex (hex digits, even length) or b64 (standard or URL-safe base64), exactly one of them, and lower-case hex in answers.
  • UUIDs and lists. UUIDs are string parameters in 16-bit, 32-bit or 128-bit form, and answers give lower-case 128-bit. Lists are comma-separated strings.
  • A table in one parameter. One string parameter, with entries separated by , and fields by ~. The extension parses it and refuses it whole.
  • Answers the platform needs at once. When the platform asks for a value the page cannot give in time, the extension answers from a native value store that the page sets, and reports each write as an event.
  • Events a page may miss. An event sent while no page is loaded is dropped. Keep each event in a native journal with a sequence number, offer a route that reads it (events?after=<seq>), and keep state readable through its own route.
  • Files. File bytes never belong in a bridge answer. Serve the file from the extension on 127.0.0.1 with a random per-file token in the URL, and answer with that URL.

Declaring native work

Both ways are declared in an extension’s manifest.json.
  • Typed. On iOS, targets[].kind is a preset: widgetkit, notification-service, notification-content, share or intents. On Android, a module with kind: "typed" lists sources, resources, permissions and components (service, receiver, provider, activity) from a fixed vocabulary, and the build writes the Gradle file and manifest.
  • Custom. On iOS, kind: "custom" takes a product type, build settings, script phases, a full info_plist, entitlements, link targets and packages. On Android, kind: "custom" points dir at your own module with its own build.gradle, AndroidManifest.xml, sources and resources.

Adding a Swift package or a Maven library

Declare dependencies and include their required graph files. Build verification covers the complete pinned dependency closure. A package URL or Maven coordinate alone does not describe that graph or prove it was compiled into the app. You do not need to manually copy library binaries into the app. iOS: a Swift package from GitHub. List it under ios.packages in manifest.json with its GitHub URL, the full commit revision of the release you want, and the products you use. Then link the product in your app target under ios.app.packages. For example:
Swift packages come from github.com over https. ios.package_resolved is required for remote packages and names the complete pinned SwiftPM graph, including transitive packages. Include that file in the extension folder. The snippet above is an excerpt; use the extension’s graph file or generate the graph for your own dependency set. A missing graph is refused with NX-M100. iOS: a CocoaPod. The manifest also accepts CocoaPods. Declare exact pod names and versions in ios.pods, point ios.podfile_lock at the lockfile under your extension’s ios/ folder, and put the installed-tree SHA-256 for every root pod in that lockfile in ios.pod_trees:
This is an illustrative manifest excerpt. Replace <installed-tree-sha256> with the measured 64-character lowercase hexadecimal digest for each root pod in the complete lockfile closure. Include the declared versions and spec checksums. The build checks the installed trees and preserves the base app’s existing pods. Android: a Maven library. Add a custom module in manifest.json that points at your own module folder, and list the libraries in that module’s build.gradle with implementation, the same way as in Android Studio:
Maven libraries come from Google’s Maven repository and Maven Central. A library published only on a vendor’s own Maven server is not accepted yet. Both ways may also declare:
  • Android min_sdk (21 to 36, typed modules). The module builds at that level. On a device below it, the extension is never created and every route answers platform_limit.
  • Android meta_data. Application <meta-data> entries, each a name and exactly one of value or resource. A name the app already declares, or another extension declares, is refused. Keep account values in your config, not in a public repository.
  • iOS packages[].weak: true. Every product of that package is linked as optional, so an app whose deployment target is below the package’s minimum still launches. Guard its use with #available.
Files are accepted by type: source and text formats, assets and binaries. Every file must be covered by its manifest.json, and an unreferenced file is refused. A custom Android module dir covers its declared module tree recursively. Hidden files (names that start with a dot) are always refused. Binaries must be declared and covered by the verified build inputs.

What the build owns

You cannot set these. The build sets them for you: bundle id and package name, versions, team and signing, URL types, App Transport Security, purpose strings and permissions your app already sets in Despia (declare them under requires), and push and associated-domain entitlements. App Groups are logical names. A group named nativeext becomes group.<bundle id>.nx.nativeext. Build errors in your files are reported by their served path, <extension>/<ios|android>/<your path>:<line>:<column>, for example recorder/ios/app/RecorderExtension.swift:42:17. Secrets, tokens and build machine paths are redacted.

Platform limits to plan for

  • iOS. Background audio continues only while the audio session stays active. Recording must start in the foreground, and a force-quit ends it. Lock Screen widget families need iOS 16 and update on WidgetKit’s budget. App Groups and new App IDs are manual steps in the Apple Developer portal.
  • Android. Android 14 and later only start a microphone foreground service while the app is visible. Lock Screen widgets depend on the device, so the foreground service notification is the guaranteed Lock Screen presence. Google Play requires foreground service type declarations.
  • Files. Android WorkManager stops a regular worker after 10 minutes, and an upload restarts from its first byte.
  • Both. Apple managed capabilities and restricted Android permissions need approval from Apple or Google and pass the store’s own review.