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 theLICENSE, 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.
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: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’spublic 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.
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 inmanifest.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)
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:
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 withbad_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: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, useonMounted, 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: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 inios.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
awaitinhandle, checkcall.isActivebefore you start something new. Once the route’stimeout_mshas passed, the page already has itstimeoutanswer. - Do not mark
handlenonisolatedor@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 inios.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 inandroid.entry_class. It implements com.despia.nativeext.NativeExtension. From the recorder extension:
android/recorder/java/despia/ext/recorder/RecorderExtension.java (excerpt)
handlegets the call and a reply callback. Callreply.reply(ExtResult.ok(json))orreply.reply(ExtResult.error(code, message))once.onCreateruns inApplication.onCreateof the main process, before any activity or WebView. It also runs when WorkManager or a receiver starts the process. Listapplication_createinandroid.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) orb64(standard or URL-safe base64), exactly one of them, and lower-casehexin answers. - UUIDs and lists. UUIDs are
stringparameters 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
stringparameter, 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.1with a random per-file token in the URL, and answer with that URL.
Declaring native work
Both ways are declared in an extension’smanifest.json.
- Typed. On iOS,
targets[].kindis a preset:widgetkit,notification-service,notification-content,shareorintents. On Android, a module withkind: "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 fullinfo_plist,entitlements, link targets and packages. On Android,kind: "custom"pointsdirat your own module with its ownbuild.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 underios.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:
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:
<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:
- 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 answersplatform_limit. - Android
meta_data. Application<meta-data>entries, each anameand exactly one ofvalueorresource. 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.
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 underrequires), 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.