iOS Live Activities
Live Activities show live content on the lock screen and in the Dynamic Island: order tracking, delivery time, match scores, journey status. With Pushizo, you start, update and end activities from the server…
Live Activities show live content on the lock screen and in the Dynamic Island: order tracking, delivery time, match
scores, journey status. With Pushizo, you start, update and end activities from the server
(docs/adr/0024-ios-live-activities.md).
Requirements: iOS 16.1+ (remote start, i.e. push-to-start, requires iOS 17.2+), an iOS push channel in the app (APNs .p8 key)
and an ActivityAttributes type defined in the Widget Extension.
1. Define the type
Via Messages → Live Activities → New type or the API. The type name must exactly match the Swift type name.
struct DeliveryAttributes: ActivityAttributes, PushizoLiveActivityAttributes {
struct ContentState: Codable, Hashable {
var eta: Int
var status: String
}
var orderId: String
var pushizo: PushizoActivityData?
}curl -X POST https://api.pushizo.com/v1/apps/$APP_ID/live-activities/types \
-H "Authorization: Bearer $HS_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"DeliveryAttributes","content_state_schema":{"type":"object","properties":{"eta":{"type":"integer","minimum":0},"status":{"type":"string","enum":["hazirlaniyor","yolda","teslim"]}},"required":["eta","status"]},"attributes_schema":{"type":"object","properties":{"orderId":{"type":"string"}},"required":["orderId"]}}'The schema language is flat objects with primitive fields (string, integer, number, boolean; optional enum, maxLength,
minimum, maximum, required). A field not in the schema, a missing required field or a wrong type returns 422 HS_CONTENT_INVALID;
such content is not sent because the device could not decode it.
2. Register in the SDK
if #available(iOS 16.1, *) {
Pushizo.LiveActivities.register(DeliveryAttributes.self)
}The SDK reports the push-to-start token for the type and the update token of every activity that starts to Pushizo;
when the activity ends, it deletes the token. Add NSSupportsLiveActivities = YES to Info.plist. Details:
iOS SDK. The Flutter, React Native, Capacitor, Cordova, MAUI and Unity bridges use the general-purpose
PushizoDefaultLiveActivityAttributes type; in that case, define a type with this name in the dashboard.
3. Start, update, end
curl -X POST https://api.pushizo.com/v1/apps/$APP_ID/live-activities/DeliveryAttributes/start \
-H "Authorization: Bearer $HS_API_KEY" -H "Content-Type: application/json" \
-d '{"activity_id":"order-42","target":{"include_external_ids":["user-1"]},"attributes":{"orderId":"42"},"content_state":{"eta":25,"status":"hazirlaniyor"},"alert":{"title":{"tr":"Siparişin hazırlanıyor"}},"stale_date":1792090000}'curl -X POST https://api.pushizo.com/v1/apps/$APP_ID/live-activities/DeliveryAttributes/update \
-H "Authorization: Bearer $HS_API_KEY" -H "Content-Type: application/json" \
-d '{"activity_id":"order-42","content_state":{"eta":10,"status":"yolda"}}'curl -X POST https://api.pushizo.com/v1/apps/$APP_ID/live-activities/DeliveryAttributes/end \
-H "Authorization: Bearer $HS_API_KEY" -H "Content-Type: application/json" \
-d '{"activity_id":"order-42","content_state":{"eta":0,"status":"teslim"},"dismissal_date":1792093600}'targetis only for start:include_external_ids,include_subscription_ids,included_segmentsorall. Only iOS devices with a push-to-start token for this type are targeted.- If
activity_idis not given, alac_…ID is generated and returned in the response; update/end use this ID. - Update/end go to the tokens the devices reported for this activity; if there are none, 422
HS_NO_RECIPIENTS(the activity may have ended or the device may not have reported yet). priority: 10 (default, immediate) or 5 (energy-friendly; subject to Apple's budget).- Quiet hours and frequency caps do not apply. Quota and the
message.queuedwebhook work as for regular messages; the send appears in the Messages list and in message tracking.
Response (202): { "message_id": "msg_…", "activity_id": "order-42", "event": "start", "recipients_estimate": 1 }.
4. Automatic flow with journeys
In the journey builder, add a Live Activity step: type, event (start/update/end) and activity key. Steps with the same
key target the same activity within the same run (ID <run>-<key>). Values can contain Liquid:
| Field | Value |
|---|---|
orderId (attribute) | {{ context.order_id }} |
eta (content) | {{ user.tags.eta }} |
Liquid output is converted to the type in the schema ("15" → 15). If the user has no token, the step is skipped and the run continues;
if a value does not match the schema, the step is counted as failed (the run still continues) and appears in journey analytics.
Troubleshooting
| Symptom | Cause |
|---|---|
Start 422 HS_NO_RECIPIENTS | No iOS 17.2+ device in the target has a push-to-start token for this type; register was not called or there is no notification permission. |
Update 422 HS_NO_RECIPIENTS | The activity has ended on the device, or the SDK has not yet reported the update token. |
| Nothing happens on the device | The type name does not match the Swift type name, or the ContentState fields do not match the schema. |
Delivery failed (Unregistered) | The token became invalid; Pushizo deletes only this token, the device subscription is not affected. |
iOS critical alerts, interruption levels and sound
This guide explains the aps fields Pushizo supports in iOS notifications, how to use ios_interruption_level (time-sensitive / critical) and how sound/volume behaves. Critical alerts require an entitlement that Apple grants only on application…
Location-based targeting
With the user's permission, you can collect the device location and build segments such as "users within X km of this point" (ADR-0025).