PushizoDocs
Channels

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}'
  • target is only for start: include_external_ids, include_subscription_ids, included_segments or all. Only iOS devices with a push-to-start token for this type are targeted.
  • If activity_id is not given, a lac_… 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.queued webhook 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:

FieldValue
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

SymptomCause
Start 422 HS_NO_RECIPIENTSNo 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_RECIPIENTSThe activity has ended on the device, or the SDK has not yet reported the update token.
Nothing happens on the deviceThe 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.

On this page