public final class LiveActivity

Object
LiveActivity

A running live activity: an ongoing-state surface (delivery, timer, ride, score) presented on the iOS lock screen and Dynamic Island, as an ongoing Android notification, or as a floating pill window on desktop. Start it with a descriptor and an initial state, then push fresh state maps as the situation evolves – updates ship only the state, the layout is re-interpolated on the surface:

LiveActivity delivery = LiveActivity.start(descriptor, initialState);
...
delivery.update(stateMap("Arriving now", eta, 1.0f));
delivery.end(null);

On platforms without live activity support start(...) returns an inert handle whose methods are safe no-ops (isActive() returns false), so app code needs no platform checks.

Methods

`public static boolean isSupported()`	Returns true when this platform can present live activities, including when doing so still depends on a permission the user has not been asked for yet (Android 13+ raises that prompt from `start(LiveActivityDescriptor, Map)`).
`public static` `LiveActivity start(LiveActivityDescriptor descriptor, Map<String, Object> initialState)`	Starts a live activity.
`public static void updateRemote(String id, String stateJson)`	Push-framework entry point that updates an already-running native activity by id.
`public static void endRemote(String id, String finalStateJson, boolean dismissImmediately)`	Push-framework entry point that ends an already-running native activity by id.
`public void update(Map<String, Object> state)`	Pushes a fresh state map to the running activity.
`public void end(Map<String, Object> finalState)`	Ends the activity, optionally showing a final state before the platform dismisses the surface.
`public void end(Map<String, Object> finalState, boolean dismissImmediately)`	Ends the activity.
`public boolean isActive()`	Returns true while the activity is running (false for inert handles and after `end`).
`public` `String getId()`	Returns the platform id of the activity, or null for inert handles.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone

Method details

isSupported

public static boolean isSupported()

Returns true when this platform can present live activities, including when doing so still depends on a permission the user has not been asked for yet (Android 13+ raises that prompt from start(LiveActivityDescriptor, Map)). It turns false once the user has refused that prompt as often as start will raise it, or has switched notifications off for the app.

Returns

true when live activities are supported

start

public static LiveActivity start(LiveActivityDescriptor descriptor, Map<String, Object> initialState)

Starts a live activity. On unsupported platforms (or when the platform refuses, e.g. the user disabled live activities) this returns an inert handle rather than throwing.

On Android 13 and newer the ongoing notification a live activity lowers to needs the POST_NOTIFICATIONS permission, so the first start on a fresh install raises the system prompt and blocks until the user answers. Start that first activity with your app in the foreground: a background service or push handler has no UI to prompt from and the start is refused. The prompt is raised at most twice across an install, after which isSupported() reports false.

Threading

Callable from any thread, and a background thread is the right one. Starting an activity serializes the descriptor, writes its PNG blobs where the platform renderer can reach them and makes a synchronous native request (Activity.request is an XPC round trip on iOS). The simulator makes all of that free, so an app that starts activities on the EDT looks fine there and stalls on hardware; Surfaces.setDiagnosticsEnabled(Boolean) describes the checks that catch it. Note also that the returned handle is the only way to update or end this activity: check isActive() rather than tracking a flag of your own, or a start that the platform refused leaves you starting a second activity on top of a live one.

Parameters

descriptor LiveActivityDescriptor: the activity layout and regions
initialState Map<String, Object>: the initial state map, may be null

Returns

a handle to the running activity; check isActive() to know whether it is live

updateRemote

public static void updateRemote(String id, String stateJson)

Push-framework entry point that updates an already-running native activity by id.

endRemote

public static void endRemote(String id, String finalStateJson, boolean dismissImmediately)

Push-framework entry point that ends an already-running native activity by id. finalStateJson may be null to keep the last published state, matching the SurfaceBridge contract.

update

public void update(Map<String, Object> state)

Pushes a fresh state map to the running activity. A no-op on an inert or ended handle.

Parameters

state Map<String, Object>: the new state map

end

public void end(Map<String, Object> finalState)

Ends the activity, optionally showing a final state before the platform dismisses the surface. A no-op on an inert or already-ended handle.

Parameters

finalState Map<String, Object>: the final state to show, or null to keep the last state

end

public void end(Map<String, Object> finalState, boolean dismissImmediately)

Ends the activity.

Parameters

finalState Map<String, Object>: the final state to show, or null to keep the last state
dismissImmediately boolean: true to remove the surface right away instead of letting the platform linger on the final state

isActive

public boolean isActive()

Returns true while the activity is running (false for inert handles and after end).

getId

public String getId()

Returns the platform id of the activity, or null for inert handles. Action events from this activity carry the descriptor’s activity type as their source.