Skip to main content
Source: Live Activities repository. Read its LICENSE before using or modifying the extension. This extension starts, updates, ends and lists native activities from your web app. It includes delivery, score and timer templates. On iOS it uses ActivityKit for the Lock Screen and Dynamic Island. On Android it uses ongoing notifications, with Live Updates on Android 16 and later when the system allows promotion. It is for the Despia V3 runtime. You own and maintain the copied native code. First-party V4 support comes through the new package registry. Read V3 Extensions for build verification and rebuild requirements.

Install

  1. Copy the files below into public/despia/liveactivity/ in your web app, keeping their ios/ and android/ paths.
  2. Add "liveactivity" to the extensions array in public/despia/extensions.json, keeping your app identity and any other extension names.
  3. Rebuild and install your native app with the extension compiled in. Changing native files requires fresh build verification and a new build.
The manifest adds the NXLiveActivity WidgetKit target on iOS. The Android custom module adds its notification permissions, notification service extension and dismiss receiver. Local calls work without OneSignal; server updates require the base app’s push integration and your server configuration. Do not put server credentials in your web app.

Call it from your web app

Install the SDK with npm install despia-native. Import despia from despia-native and watch the route’s declared output variable. Call these functions from client events. Timer times are Unix seconds.

Routes and answers

Each success answer uses {ok: true, data: ...}. Failures use {ok: false, code, error}. The table lists the fields inside data. stale_minutes is 0 to 720. relevance is 0 to 100. dismiss=after requires dismiss_minutes, from 0 to 240. IDs contain 1 to 64 letters, digits, dots, underscores or hyphens. The combined attributes and state, including the injected activityId, must fit in 4096 UTF-8 bytes. Each row in activities has activityId, template, state, origin, pushToken, attributes and content. On Android pushToken is null and pushToStart is empty. iOS authorization fields are enabled, frequentPushes, onesignal and platform. Android fields are enabled, permission, promoted, liveUpdates, onesignal and platform. onesignal is linked or not_linked.

Templates

The template source files define these fields. Edit the Swift template, Android template and registries together when adding your own template.

Events

Events have app scope and reach the trusted top-level page. Read list to recover the current state after a page loads. Do not rely only on events.

Errors

Besides the standard bridge errors, the extension can return unknown_template, activities_disabled, exists, bad_value, too_large and unknown_activity. iOS can also return activity_failed, not_foreground, too_many or unsupported. Android can return storage_failed or busy while a notification permission prompt is open. settings can return unavailable.

Platform limits

  • iOS local starts require the app to be in the foreground. The extension widget target declares iOS 16.6. Push-to-start requires iOS 17.2 or later. ActivityKit and the user’s settings control visibility, lifetime and push delivery.
  • Android 16 and later can promote an eligible ongoing notification to a Live Update. Earlier versions use an ordinary ongoing notification. Promotion is not guaranteed.
  • Android has no ActivityKit relevance score. When you pass relevance, Android reports this in platformDifferences.relevance instead of applying it.
  • On Android 7, ended notifications are removed immediately because notification timeouts are unavailable. On later Android versions the extension uses a timeout for default and after dismissal.
The extension skill includes a reference for this extension.

Files

Copy each file to its title’s path. The extensions.json block is an example for a new app; merge the extension name into your existing file rather than replacing its app identity.
public/despia/extensions.json
public/despia/liveactivity/manifest.json