Live Activities

Display real-time, persistent information on your users' Lock Screen and Dynamic Island (iOS) or as ongoing notifications (Android). Live Activities are perfect for delivery tracking, live scores, countdowns, and any task with a clear start and end.

How It Works

1. You choose a template that matches your use case (e.g., status-tracker, countdown)
2. Your backend calls the NativeSuite API to start a Live Activity, passing the template and data
3. NativeSuite delivers it to the user's device — iOS shows it on the Lock Screen and Dynamic Island, Android shows an ongoing notification
4. Your backend sends updates to change the displayed data in real time
5. When the task is done, your backend ends the activity

Your users see live, glanceable information without opening the app.

Available Templates

NativeSuite includes 8 pre-built templates. Each template defines the layout — you provide the data. See the Live Activity Templates reference for detailed field documentation, views for each template, and a quick-reference table.

status-tracker

A step-by-step progress indicator with ETA. Ideal for deliveries, order fulfillment, and multi-stage workflows.

Static data (set once):

Field	Description
title	Header text (e.g., "Order #1234")
steps	Comma-separated step names (e.g., "Confirmed,Preparing,On the way,Delivered")

Dynamic data (updated over time):

Field	Description
currentStep	Zero-based index of the current step
status	Current status text (e.g., "Driver is 5 minutes away")
eta	Estimated time (e.g., "12:35 PM")
statusIcon	SF Symbol name for the compact view (e.g., "car.fill")

metric-live

A large number with trend indicator. Ideal for stock prices, live scores, counters.

Static data:

Field	Description
label	Metric label (e.g., "AAPL", "Home Team")

Dynamic data:

Field	Description
value	Current value (e.g., "$187.42", "3")
change	Change amount (e.g., "+2.3%", "+1")
trend	Direction: up, down, or neutral

countdown

A live countdown timer. Ideal for auctions, reservations, event starts.

Static data:

Field	Description
label	Title (e.g., "Auction Ending")
subtitle	Optional subtitle

Dynamic data:

Field	Description
targetDate	ISO 8601 timestamp to count down to
remaining	Fallback text if targetDate is not set (e.g., "04:32")

progress-bar

A progress bar with percentage. Ideal for uploads, processing jobs, goals.

Static data:

Field	Description
label	Title (e.g., "Uploading report.pdf")

Dynamic data:

Field	Description
progress	Percentage as a number string, 0-100 (e.g., "73")
detail	Optional detail text (e.g., "3.2 MB of 4.4 MB")

two-column

Two side-by-side metrics. Ideal for comparisons, versus scores.

Static data:

Field	Description
title	Header text

Dynamic data:

Field	Description
leftValue	Left metric value
leftLabel	Left metric label
rightValue	Right metric value
rightLabel	Right metric label

key-value-list

A list of key-value pairs. Ideal for flight info, booking details, order summaries.

Static data:

Field	Description
title	Header text

Dynamic data:

Field	Description
items	Comma-separated key:value pairs (e.g., "Flight:BA204,Gate:B12,Status:Boarding")
primaryValue	Value shown in compact views

image-banner

A title and subtitle with status text. Ideal for events, promotions, live broadcasts.

Dynamic data:

Field	Description
title	Main title
subtitle	Subtitle text
status	Status badge text

mini-table

A small grid of stats. Ideal for sports box scores, dashboards.

Static data:

Field	Description
title	Header text

Dynamic data:

Field	Description
rows	Comma-separated label:value pairs (e.g., "Q1:28-24,Q2:31-27,Q3:22-25")
primaryValue	Value shown in compact views

Starting a Live Activity

Call the NativeSuite API from your backend:

curl -X POST https://api.nativesuite.io/api/apps/{appId}/live-activities \
  -H "X-NativeSuite-Key: {your-app-secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "templateSlug": "status-tracker",
    "attributes": {
      "title": "Order #1234",
      "steps": "Confirmed,Preparing,On the way,Delivered"
    },
    "contentState": {
      "currentStep": "0",
      "status": "Order confirmed",
      "eta": "12:35 PM",
      "statusIcon": "checkmark.circle.fill"
    },
    "targetUsers": ["550e8400-e29b-41d4-a716-446655440000"]
  }'

See the Live Activities API reference for the full specification.

Updating a Live Activity

Send new content state to update what's displayed:

curl -X PATCH https://api.nativesuite.io/api/apps/{appId}/live-activities/{activityId} \
  -H "X-NativeSuite-Key: {your-app-secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "contentState": {
      "currentStep": "2",
      "status": "Driver is 5 minutes away",
      "eta": "12:30 PM",
      "statusIcon": "car.fill"
    }
  }'

Updates are delivered in real time. On iOS, the Lock Screen and Dynamic Island refresh instantly. On Android, the ongoing notification updates in place.

Ending a Live Activity

When the task is complete:

curl -X DELETE https://api.nativesuite.io/api/apps/{appId}/live-activities/{activityId} \
  -H "X-NativeSuite-Key: {your-app-secret}"

On iOS, the activity fades from the Dynamic Island and persists on the Lock Screen for up to 4 hours showing the final state. On Android, the ongoing notification is dismissed.

Platform Differences

Feature	iOS	Android
Display	Lock Screen + Dynamic Island	Ongoing notification
Duration limit	8h Dynamic Island, 12h Lock Screen	No system limit
User dismissal	Cannot dismiss while active	Can dismiss (swipe)
Update speed	Near-instant	Near-instant
Requires	iOS 16.1+ (17.1+ for server-start)	Android 8.0+

Despite the platform differences, the API is the same — you call one endpoint and NativeSuite handles the platform-specific delivery.

Billing

Live Activities are billed by duration — the total time your activities are running across all users. Each plan includes a monthly allocation of minutes:

Plan	Included
Free	Disabled
Growth	Included minutes per month
Scale	Higher allocation + overage billing

Check your current usage in the dashboard under Billing.

Example: If you start 10 delivery-tracking activities that each run for 30 minutes, that's 300 minutes (5 hours) of usage.

Best Practices

• Choose the right template — Match the template to your content. A delivery should use status-tracker, not metric-live
• Update frequently enough — Users expect real-time data. For deliveries, update every 1-2 minutes. For scores, update on every event
• Don't forget to end — Always call the end endpoint when the task is complete. Activities left running consume your billing minutes
• Keep data concise — Lock Screen and Dynamic Island have limited space. Short values work best
• All values are strings — Both attributes and contentState use string values in their dictionaries