Live Activities

A live, updating view of an in-progress order, ride or delivery — iOS Lock Screen and Dynamic Island, Android 16 Live Updates — driven from your backend.

A Live Activity shows the state of something happening now — an order being delivered, a ride on its way — on the iOS Lock Screen / Dynamic Island (ActivityKit) and as an Android 16 Live Update (a promoted ongoing notification; older Android shows an ongoing notification with a progress bar).

You design it once as a template in the console; your server then sends only data: the current step, a progress value, an ETA, a few placeholder values.

Templates

In Live Activities → Templates design the layout (steps, progress or text), colours (light and dark), icons, the tracker image that moves along the bar, step labels and texts with {{placeholders}} — with live iOS, Dynamic Island and Android previews and per-language translations. Saving validates every language against the 4 KB push limit, so a saved template is always deliverable.

Each device receives the template in its own app language (exact match, then the base language — pt_BR → pt — then the template default). Pass lang to force one.

Driving it from your backend

$la = $nexus->liveActivities();

$la->template('order_tracking', 'order_42')            // template key + your id
    ->step('pending')
    ->etaAt(new DateTimeImmutable('+25 minutes'))     // live countdown on the device
    ->values(['driver' => 'Ahmed', 'quantity' => '500 L · Diesel'])
    ->toUser('user_7')
    ->start();

$la->activity('order_42')->step('on_the_way')->progress(0.4)->update();   // partial, merged
$la->activity('order_42')->step('completed')->end();
$la->activity('order_42')->canceled()->end();

In Laravel, return a NexusLiveActivityMessage from toNexusLiveActivity() — one notification per order status. See the PHP SDK.

Data fields

Field	Effect
`step`	The current step — matches a step's `id` or `label`, ignoring case, spaces and `_` (so `"On the Way"` works).
`progress`	0–1 — moves the tracker between the current and the next step.
`etaAt`	Unix seconds (SDK builders accept dates) — a live countdown that ticks on the device with no further pushes. `values.eta` shows fixed text instead.
`values`	Fills `{{placeholders}}`.
`state`	`canceled` (red, steps greyed) or `done`.

Updates are partial — send only what changed; null clears a field.
Payloads are checked against the 4 KB APNs / FCM limit before sending, so an oversized activity is a clear API error, not a silent drop.
The start result carries iosTargets and, when iOS got nothing, an iosWarning saying why.
Priority 10 (immediate) updates are metered; priority 5 (routine) are not.

App setup

await Nexus.init(const NexusConfig(apiKey: 'nxs_live_xxx', liveActivityEnabled: true));

Apple requires Live Activity UI in a Widget Extension. The SDK ships the renderer as the NexusLiveActivityKit pod, so the extension is three lines:

Xcode → File → New → Target → Widget Extension (iOS 16.1+). Replace the generated Swift with:

import NexusLiveActivityKit
import SwiftUI
import WidgetKit

@main struct AppWidgets: WidgetBundle { var body: some Widget { NexusLiveActivityWidget() } }

ios/Podfile:

target 'LiveActivityWidget' do
  use_frameworks!
  pod 'NexusLiveActivityKit', :path => '.symlinks/plugins/nexus_flutter/ios'
end

App Info.plist: NSSupportsLiveActivities = YES (and NSSupportsLiveActivitiesFrequentUpdates = YES).
Upload your APNs key in the console (Live Activities cannot go through FCM).

Optional: enable the same App Group on app and extension and set NexusAppGroup in both Info.plists so template images are pre-cached for the widget (widgets cannot download).

Nothing on iOS?

If the user turned Live Activities off (Settings → your app → Live Activities), iOS silently drops every Live Activity push. With SDK logging on, the SDK warns about it at launch.

Without a template

For a fully custom SwiftUI widget, define your own ActivityAttributes and send plain content state: activity('DeliveryAttributes', 'order_42').title(…).status(…).progress(20).start(). Register tokens yourself with registerPushToStartToken / registerActivity.

Reference

Flutter · JavaScript · PHP · Python · .NET · REST

TemplatesCopy Anchor Link

Driving it from your backendCopy Anchor Link

Data fieldsCopy Anchor Link

App setupCopy Anchor Link

Without a templateCopy Anchor Link