Live Activities

// access
nexus.liveActivities

NexusLiveActivitiesCopy Anchor Link

Live Activities — a live, updating view of an in-progress event on the iOS Lock Screen / Dynamic Island and as an Android live notification. The classic server-side use case: start when the event begins, update as it changes, end when it's done.

Templated (recommended) — design in the Nexus console, send only data; the SDKs render it on iOS + Android in each device's language: nexus.liveActivities.template('order_tracking', 'order_42').step('pending').etaAt(eta).value('driver', 'Ahmed').toUser('u_1').start() then nexus.liveActivities.activity('order_42').step('arrived').update().

Plain (your own iOS widget): nexus.liveActivities.activity('DeliveryAttributes', 'order_42').status('Preparing').progress(20).toUser('u_1').start().

NexusLiveActivitiesCopy Anchor Link

new NexusLiveActivities(http: NexusHttp, id: NexusIdentity)

Parameters

Returns NexusLiveActivities

activity()Copy Anchor Link

activity(activityTypeOrId: string, activityId?: string): NexusLiveActivityBuilder

Start a fluent Live Activity. activity(type, id) for start; activity(id) for update/end.

Parameters

Returns NexusLiveActivityBuilder

template()Copy Anchor Link

template(template: string | Record<string, unknown>, activityId: string): NexusLiveActivityBuilder

A templated activity: template is a template key from the console (e.g. "order_tracking") or an inline design object.

Parameters

Returns NexusLiveActivityBuilder

startTemplate()Copy Anchor Link

async startTemplate(template: string | Record<string, unknown>, activityId: string, data: LiveActivityData = {}, options: LiveActivityTemplateStartOptions = {}): Promise<LiveActivityResult>

Start a templated activity (plain form).

Parameters

Returns Promise<LiveActivityResult>

updateData()Copy Anchor Link

async updateData(activityId: string, data: LiveActivityData, options: { staleDate?: string; priority?: number } = {}): Promise<LiveActivityResult>

Update a templated activity with partial data (merged server-side).

Parameters

Returns Promise<LiveActivityResult>

start()Copy Anchor Link

async start(activityType: string, activityId: string, contentState: Record<string, unknown>, options: { distinctIds?: string[]; attributes?: Record<string, unknown>; staleDate?: string; priority?: number } = {}): Promise<LiveActivityResult>

Start an activity (plain form). Omit distinctIds for a shared activity.

Parameters

Returns Promise<LiveActivityResult>

update()Copy Anchor Link

async update(activityId: string, contentState: Record<string, unknown>, options: { staleDate?: string; priority?: number } = {}): Promise<LiveActivityResult>

Parameters

Returns Promise<LiveActivityResult>

end()Copy Anchor Link

async end(activityId: string, options: { contentState?: Record<string, unknown>; data?: LiveActivityData; dismissalDate?: string } = {}): Promise<LiveActivityResult>

End an activity. Templated: data is the final state shown before dismissal (e.g. { step: 'completed' }).

Parameters

Returns Promise<LiveActivityResult>

registerPushToStartToken()Copy Anchor Link

async registerPushToStartToken(activityType: string, token: string): Promise<void>

Register an iOS push-to-start token (client-side; exposed for BYO).

Parameters

registerActivity()Copy Anchor Link

async registerActivity(activityId: string, activityType: string, options: { platform?: string; updateToken?: string; contentState?: Record<string, unknown> } = {}): Promise<void>

Register a running activity instance's update token (client-side; BYO).

Parameters

event()Copy Anchor Link

async event(activityId: string, type: 'receipt' | 'click' | 'failed', options: { platform?: string } = {}): Promise<void>

Report a receipt / click / failure for analytics.

Parameters

NexusLiveActivityBuilderCopy Anchor Link

Fluent builder for a Live Activity. Template data setters (step, etaAt, value, canceled, …) send data; the plain setters (status, set, …) send a contentState for your own widget.

NexusLiveActivityBuilderCopy Anchor Link

new NexusLiveActivityBuilder(http: NexusHttp, activityId: string, activityType?: string, _template?: string | Record<string, unknown>)

Parameters

Returns NexusLiveActivityBuilder

step()Copy Anchor Link

step(step: string): this

Current step (a step id or label of the template).

Parameters

Returns this

etaAt()Copy Anchor Link

etaAt(at: Date | number): this

Arrival time → a live countdown on the device (Date, unix seconds or ms).

Parameters

Returns this

eta()Copy Anchor Link

eta(text: string): this

A fixed ETA text instead of a countdown, e.g. "8 min" (the eta value).

Parameters

Returns this

value()Copy Anchor Link

value(key: string, value: string | number | boolean): this

One {{placeholder}} value.

Parameters

Returns this

values()Copy Anchor Link

values(values: Record<string, string | number | boolean>): this

Parameters

Returns this

canceled()Copy Anchor Link

canceled(): this

Show the canceled state.

Returns this

done()Copy Anchor Link

done(): this

Show the finished state.

Returns this

data()Copy Anchor Link

data(data: LiveActivityData): this

Partial template data (merged).

Parameters

Returns this

lang()Copy Anchor Link

lang(lang: string): this

Start only: force one language for every recipient (default: each device's own).

Parameters

Returns this

alert()Copy Anchor Link

alert(title: string, body?: string): this

Start only: the iOS alert shown with the start.

Parameters

Returns this

title()Copy Anchor Link

title(v: string): this

Parameters

Returns this

subtitle()Copy Anchor Link

subtitle(v: string): this

Parameters

Returns this

body()Copy Anchor Link

body(v: string): this

Parameters

Returns this

status()Copy Anchor Link

status(v: string): this

Parameters

Returns this

progress()Copy Anchor Link

progress(v: number): this

Progress 0–1 (or 0–100). Templated: toward the next step / along the bar.

Parameters

Returns this

set()Copy Anchor Link

set(key: string, value: unknown): this

Parameters

Returns this

state()Copy Anchor Link

state(state: Record<string, unknown>): this

Parameters

Returns this

toUsers()Copy Anchor Link

toUsers(distinctIds: string[]): this

Parameters

Returns this

toUser()Copy Anchor Link

toUser(distinctId: string): this

Parameters

Returns this

shared()Copy Anchor Link

shared(): this

A shared activity (many users watching one event).

Returns this

attributes()Copy Anchor Link

attributes(attributes: Record<string, unknown>): this

Parameters

Returns this

priority()Copy Anchor Link

priority(priority: number): this

APNs priority: 5 = routine (unmetered), 10 = immediate (metered).

Parameters

Returns this

staleAt()Copy Anchor Link

staleAt(iso: string): this

Parameters

Returns this

dismissAt()Copy Anchor Link

dismissAt(iso: string): this

Parameters

Returns this

start()Copy Anchor Link

async start(): Promise<LiveActivityResult>

Returns Promise<LiveActivityResult>

update()Copy Anchor Link

async update(): Promise<LiveActivityResult>

Returns Promise<LiveActivityResult>

end()Copy Anchor Link

async end(): Promise<LiveActivityResult>

Returns Promise<LiveActivityResult>

LiveActivityResultCopy Anchor Link

iosCopy Anchor Link

ios: number

androidCopy Anchor Link

android: number

iosTargetsCopy Anchor Link

iosTargets?: number

Start only: iOS devices registered for the activity type.

iosWarningCopy Anchor Link

iosWarning?: string

Start only: why iOS got fewer deliveries than targets (no devices, APNs not set up, Apple's error).

LiveActivityDataCopy Anchor Link

Data for a templated Live Activity (the design lives in a template made in the Nexus console, or sent inline). On update, send only what changed — the server merges it into the current data (null clears a field).

stepCopy Anchor Link

step?: string | null

Current step id (or label) of a steps template, e.g. "on_the_way".

stateCopy Anchor Link

state?: 'active' | 'canceled' | 'done' | (string & {}) | null

"active" | "canceled" | "done".

progressCopy Anchor Link

progress?: number | null

0–1: the tracker's position toward the next step (or along the bar).

etaAtCopy Anchor Link

etaAt?: number | null

Arrival time, unix seconds — a live countdown on the device.

valuesCopy Anchor Link

values?: Record<string, string | number | boolean | null>

Values for the template's {{placeholders}}; eta shows as fixed ETA text.

titleCopy Anchor Link

title?: string | null

Override the template's texts for this activity.

subtitleCopy Anchor Link

subtitle?: string | null

bodyCopy Anchor Link

body?: string | null

LiveActivityTemplateStartOptionsCopy Anchor Link

distinctIdsCopy Anchor Link

distinctIds?: string[]

Omit for a shared activity (everyone).

langCopy Anchor Link

lang?: string

Force one language for every recipient (default: each device's app language).

alertCopy Anchor Link

alert?: { title: string; body?: string }

iOS alert shown with the start (default: the template's current texts).

attributesCopy Anchor Link

attributes?: Record<string, unknown>

staleDateCopy Anchor Link

staleDate?: string

priorityCopy Anchor Link

priority?: number