# Class LiveActivity

java.lang.Object
com.codename1.surfaces.LiveActivity

public final class LiveActivity extends Object

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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `end(Map<String,Object> finalState)`
  Ends the activity, optionally showing a final state before the platform dismisses the surface.
  `void`
  `end(Map<String,Object> finalState, boolean dismissImmediately)`
  Ends the activity.
  `static void`
  `endRemote(String id, String finalStateJson, boolean dismissImmediately)`
  Push-framework entry point that ends an already-running native activity by id.
  `String`
  `getId()`
  Returns the platform id of the activity, or null for inert handles.
  `boolean`
  `isActive()`
  Returns true while the activity is running (false for inert handles and after `end`).
  `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)`).
  `static LiveActivity`
  `start(LiveActivityDescriptor descriptor, Map<String,Object> initialState)`
  Starts a live activity.
  `void`
  `update(Map<String,Object> state)`
  Pushes a fresh state map to the running activity.
  `static void`
  `updateRemote(String id, String stateJson)`
  Push-framework entry point that updates an already-running native activity by id.

  ### Methods inherited from class Object

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

- ## 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`: the activity layout and regions
    - `initialState`: 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`: 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`: 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`: the final state to show, or null to keep the last state
    - `dismissImmediately`: 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.