> ## Documentation Index
> Fetch the complete documentation index at: https://setup.despia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# V3 Extensions

> Add your own Swift and Kotlin or Java code to a Despia V3 app and call it from your web app with one extension:// scheme.

> [!WARNING]
>
> **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:

```javascript theme={null}
import despia from 'despia-native';

// Run from a browser click handler or client lifecycle hook.
async function readRecorderStatus() {
  const reply = await despia('extension://recorder/status', ['recorderStatus']);
  const answer = reply.recorderStatus;
  if (answer === undefined) { console.error('No native reply within 30 seconds'); return; }
  if (!answer.ok) console.error(answer.code, answer.error);
  return answer;
}
```

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](https://docs.github.com/en/pull-requests/reference/forks). 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.

| Extension | What it adds | Source |
| - | - | - |
| [Background Recorder](https://setup.despia.com/experiments/samples/recorder.md) | Records audio in the background and uploads it | [GitHub](https://github.com/despia-legacy/recorder) |
| [Live Activities](https://setup.despia.com/experiments/samples/live-activities.md) | Starts, updates and ends delivery, score and timer activities | [GitHub](https://github.com/despia-legacy/live-activities) |
| [Home Widgets](https://setup.despia.com/experiments/samples/home-widgets.md) | Fills native stat and list widgets and reads taps | [GitHub](https://github.com/despia-legacy/home-widgets) |

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.

> [!WARNING]
>
> **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](https://github.com/despia-legacy/extension-skill):

```bash theme={null}
npx skills add despia-legacy/extension-skill
```

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:

```text theme={null}
public/despia/
├── extensions.json              # your app identity and the list of extension folders
└── recorder/                    # one folder per extension; the folder name is the extension id
    ├── manifest.json            # routes, parameters, outputs, events and native files
    ├── ios/
    │   └── ...                  # Swift sources and targets
    └── android/
        └── ...                  # Java or Kotlin sources and resources
```

`extensions.json` names your app and lists the extension folders:

```json public/despia/extensions.json theme={null}
{
  "app": {
    "client_id": "<your client id>",
    "ios_bundle_id": "com.example.app",
    "android_package": "com.example.app"
  },
  "extensions": ["recorder"]
}
```

`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.

> [!NOTE]
>
> 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:

```json public/despia/recorder/manifest.json (excerpt) theme={null}
{
  "name": "start",
  "params": {
    "upload": {
      "type": "https_url",
      "hosts": ["upload.example.com"],
      "required": true
    }
  },
  "output": {
    "variable": "recorderStart",
    "callback": "onRecorderStart"
  }
}
```

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:

```json theme={null}
"events": [
  { "name": "state", "callback": "onRecorderState", "scope": "document" }
]
```

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`.

| Type | Value |
| - | - |
| `string` | Text, with an optional `max` length |
| `int` | Whole number |
| `bool` | `true` or `false` |
| `enum` | One of a declared list of values |
| `https_url` | An `https` URL whose host is in the route's `hosts` list |

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:

```bash theme={null}
npm install despia-native
```

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:

```javascript theme={null}
import despia from 'despia-native';

// Run from a browser click handler or client lifecycle hook.
async function readRecorderStatus() {
  const reply = await despia('extension://recorder/status', ['recorderStatus']);
  const answer = reply.recorderStatus;
  if (answer === undefined) { console.error('No native reply within 30 seconds'); return; }
  if (!answer.ok) console.error(answer.code, answer.error);
  return answer;
}
```

`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.

```jsx theme={null}
'use client';
import {useState} from 'react';
import despia from 'despia-native';

export function RecorderStatus() {
  const [message, setMessage] = useState('');
  const [busy, setBusy] = useState(false);
  async function readStatus() {
    if (busy) return;
    setBusy(true);
    try {
      const reply = await despia('extension://recorder/status', ['recorderStatus']);
      const answer = reply.recorderStatus;
      setMessage(answer === undefined ? 'No native reply within 30 seconds'
        : answer.ok ? answer.data.state : answer.code + ': ' + answer.error);
    } finally {
      setBusy(false);
    }
  }
  return <button disabled={busy} onClick={readStatus}>{message || 'Read recording status'}</button>;
}
```

### Vue

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

```vue theme={null}
<script setup>
import {ref} from 'vue';
import despia from 'despia-native';
const message = ref('');
const busy = ref(false);
async function readStatus() {
  if (busy.value) return;
  busy.value = true;
  try {
    const reply = await despia('extension://recorder/status', ['recorderStatus']);
    const answer = reply.recorderStatus;
    message.value = answer === undefined ? 'No native reply within 30 seconds'
      : answer.ok ? answer.data.state : answer.code + ': ' + answer.error;
  } finally {
    busy.value = false;
  }
}
</script>
<template>
  <button :disabled="busy" @click="readStatus">{{ message || 'Read recording status' }}</button>
</template>
```

### 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:

```javascript theme={null}
import despia from 'despia-native';

const previous = despia.onRecorderState;
const onState = recording => {
  if (typeof previous === 'function') {
    try { previous(recording); }
    catch (error) { console.error('Previous recorder listener failed', error); }
  }
  console.log(recording.recordingId, recording.state);
};
globalThis.onRecorderState = onState;

// Call this during component cleanup.
function stopListening() {
  if (globalThis.onRecorderState !== onState) return;
  if (previous === undefined) delete globalThis.onRecorderState;
  else globalThis.onRecorderState = previous;
}
```

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:

| Field | Meaning |
| - | - |
| `ok` | `true` on success, `false` on error |
| `provider` | The provider of the answer |
| `platform` | The platform that answered |
| `runtime` | `3` |
| `bridge` | `1` |
| `extension` | The extension id |
| `route` | The route name |
| `data` | Your handler's data on success, `null` on error |
| `error` | The error message on error |
| `code` | The error code on error |

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

| Code | When |
| - | - |
| `bad_request` | An undeclared parameter, a missing required one, or a value of the wrong type |
| `not_registered` | This build does not contain the extension or route |
| `forbidden_frame` | The call did not come from the top-level page |
| `forbidden_origin` | The call came from an origin that is not allowed |
| `rate_limited` | More than 20 calls per second to one extension |
| `timeout` | The handler did not answer within the route's `timeout_ms` |
| `unavailable` | The capability is not available right now |
| `platform_limit` | This platform or OS version has no such capability. Every route of an Android extension answers it on a device below the extension's `android.min_sdk` |
| `handler_error` | Your handler failed |
| Your own codes | Any code your handler returns, for example `busy` or `permission_denied` |

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](https://setup.despia.com/experiments/extension-troubleshooting.md).

***

## 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](https://setup.despia.com/experiments/samples/recorder.md):

```swift ios/app/RecorderExtension.swift (excerpt) theme={null}
@MainActor
final class RecorderExtension: NSObject, NativeExtension {
    required override init() { super.init() }

    func didLaunch(_ context: NativeExtContext) {
        ctx = context
        // ...
    }

    func handle(_ call: NativeExtCall) async -> NativeExtResult {
        // ...
        switch call.route {
        case "start": return await start(call)
        case "stop": return stop(call.params["id"] as? String ?? "")
        case "status": return status(call.params["id"] as? String)
        case "discard": return discard(call.params["id"] as? String ?? "")
        case "upload": return upload(call.params["id"] as? String ?? "", call.params["upload"] as? String ?? "")
        default: return .error(code: "not_registered", message: call.route)
        }
    }
}
```

* `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.

| `lifecycle` name | Hook |
| - | - |
| `launch` | `didLaunch(_:)` |
| `scene` | `sceneDidChange(_:)`: foreground and background changes |
| `background_task` | `handleBackgroundTask(name:task:)` for a name in `background_tasks` |
| `open_url` | `openURL(_:)` for a URL scheme your extension claims |
| `user_activity` | `continueUserActivity(_:)` |
| `push_token` | `didRegisterPushToken(_:)` |
| `remote_notification` | `didReceiveRemoteNotification(_:completion:)` |
| `notification` | `willPresentNotification(_:)` and `didReceiveNotificationResponse(_:completion:)` |
| `bluetooth_restoration` | `restoreBluetoothCentrals(_:)` |
| `terminate` | `willTerminate()` |

`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:

```java android/recorder/java/despia/ext/recorder/RecorderExtension.java (excerpt) theme={null}
public final class RecorderExtension implements NativeExtension {
    private static volatile ExtContext policy;
    private ExtContext ctx;

    @Override
    public void onCreate(ExtContext context) {
        ctx = context;
        policy = context;
        RecorderStore.setListener(snapshot -> ctx.emit("state", snapshot));
        // ...
    }

    @Override
    public void handle(ExtCall call, ExtResult.Callback reply) {
        Context app = ctx.app();
        try {
            switch (call.route) {
                case "start": {
                    if (ContextCompat.checkSelfPermission(app, Manifest.permission.RECORD_AUDIO) != PackageManager.PERMISSION_GRANTED) {
                        reply.reply(ExtResult.error("permission_denied", "RECORD_AUDIO is not granted; request it from the page first"));
                        return;
                    }
                    // ...
                }
                // ...
                default:
                    reply.reply(ExtResult.error("not_registered", call.route));
            }
        } catch (RecorderStore.StorageException e) {
            reply.reply(storageFailed(e, "read"));
        } catch (JSONException e) {
            reply.reply(ExtResult.error("handler_error", e.getMessage()));
        }
    }
}
```

* `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:

```json theme={null}
{
  "ios": {
    "packages": [
      {
        "name": "stream-video-swift",
        "remote": {
          "url": "https://github.com/GetStream/stream-video-swift",
          "revision": "5fda355f0a682ebbf1e131d80d38386acd4c4406"
        },
        "products": ["StreamVideo"]
      }
    ],
    "package_resolved": "ios/Package.resolved",
    "app": {
      "packages": ["StreamVideo"]
    }
  }
}
```

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`:

```json theme={null}
{
  "ios": {
    "pods": [{ "name": "Lottie", "version": "4.5.0" }],
    "podfile_lock": "ios/Podfile.lock",
    "pod_trees": {
      "Lottie": "<installed-tree-sha256>"
    }
  }
}
```

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:

```json theme={null}
{
  "android": {
    "modules": [
      { "kind": "custom", "name": "streamcall", "dir": "android/streamcall", "link": "implementation" }
    ]
  }
}
```

```groovy theme={null}
// public/despia/streamcall/android/streamcall/build.gradle
dependencies {
    implementation project(':nativeext-api')
    implementation 'io.getstream:stream-video-android-core:1.35.0'
}
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.