iOS Live Activities

Live Activities overview

A Live Activity can be created:

• Anytime the app is in the foreground
• From activity intent
• From a notification action button
• From a push notification

Once created, a Live Activity can be displayed and updated for up to eight hours until it expires. After it expires, an activity can continue to be displayed for up to four hours before it is automatically dismissed. Multiple Live Activities can be started by an app, and a device can show multiple activities from different apps, the maximum number of which may depend on a range of factors.

Updates to Live Activities are made through push notifications and/or background tasks in the app. For more timely updates, Airship recommends using push notifications or push notifications in addition to background tasks.

When updating through push notifications, APNs allows a certain budget of updates per hour. If an app exceeds this budget, notifications will be throttled. To avoid being throttled, a mix of low priority (priority 5) and high priority notifications (priority 10) can be used.

In addition to priorities and background tasks, if a use case requires frequent push updates, an app can also set the plist flag NSSupportsLiveActivitiesFrequentUpdates  to prevent being throttled. However, the end user is able to disable frequent updates in the app settings.

For more information on implementing Live Activities, see Apple documentation:

• ActivityKit developer guide 
• Human Interface Guidelines 

Airship support for Live Activities

Airship’s Live Activity support allows starting Live Activities through a push and tracking each Live Activity’s unique push token by a name on the app’s channel. The name can then be used to send updates to a Live Activity. The name can be unique to the device or shared across multiple devices. Airship handles mapping the name back to the token for the specified audience and sends an update to each token. All tokens are tracked under the device channel. They do not increase your billable audience.

For example, to provide updates for tracking a sports game, create a Live Activity with name sports-game-123. The app will track and display changes through the Airship SDK using that name. The name can be unique to a single device or shared across multiple devices.

Setup

To support Live Activities, you must call restore once after takeOff during application(_:didFinishLaunchingWithOptions:) with all the Live Activity types that you might track with Airship. This allows Airship to resume tracking any previously tracked activities across app inits and to automatically track the pushToStartToken that allows starting activities through a push notification.

Airship.takeOff(config, launchOptions: launchOptions)

Airship.channel.restoreLiveActivityTracking { restorer in
    await restorer.restore(forType: Activity<DeliveryAttributes>.self)
    await restorer.restore(forType: Activity<SomeOtherAttributes>.self)
}

Starting and tracking a Live Activity from the app

To start a Live Activity from the app, make sure to set the pushType to .token. After it is created, immediately track it with Airship.channel.trackLiveActivity(_:name:).

let activity = try Activity.request(
    attributes: attributes,
    contentState: state,
    pushType: .token
)

Airship.channel.trackLiveActivity(
    activity,
    name: "order-1234"
)

Starting and tracking a Live Activity from a push notification

After the restore call above, Airship will track the pushToStartTokens for the activity’s attribute types. You can then start a Live Activity through a push notification. Starting a Live Activity does not automatically track it. Instead, the app will be woken up and you must call through to Airship with the activity instance and the name. It is recommended that you provide the name you will use to track the activity in the activity’s attributes.

There is no entry point into the app when it is started for a Live Activity being created. Instead, you need to query Live Activities on init and when a pushToStartToken update is received to track them through Airship. Airship provides an extension Activity<T>.airshipWatchActivities(activityBlock:) that can be used to do this for you.

In this example, we assume the orderNumber on our DeliveryAttributes will be used to send updates through Airship after it is created:

Airship.channel.restoreLiveActivityTracking { restorer in
    await restorer.restore(forType: Activity<DeliveryAttributes>.self)
}

Activity<DeliveryAttributes>.airshipWatchActivities { activity in
    Airship.channel.trackLiveActivity(activity, name: activity.attributes.orderNumber)
}

You can then send a create request through the Push API by specifying a live_activity payload with a start event.

In this example, an update is being sent to the named user “customer#123” and the above application code will track the activity using the orderNumber “order-1234”.

{
    "audience": {
        "named_user": "customer#123",
    },
    "device_types": [
        "ios"
    ],
    "notification": {
        "ios": {
            "live_activity": {
                "event": "start",
                "attributes_type": "DeliveryAttributes",
                 "attributes": {
                    "order_number": "order-1234"
                },
                "content_state": {
                    "stops_away": "0",
                    "driver": "Jeff Moleyes"
                },
                "alert": {
                    "title": "Delivery",
                    "body": "Order out for delivery!"
                },
                "priority": 10
            }
        }
    }
}

Updating a Live Activity from a push notification

Once an activity is tracked with Airship, you can send an update through the Push API by specifying a live_activity payload.

In this example, an update is being sent to all channels that have a Live Activity named “order-1234”.

{
    "audience": "all",
    "device_types": [
        "ios"
    ],
    "notification": {
        "ios": {
            "live_activity": {
                "name": "order-1234",
                "event": "update",
                "content_state": {
                    "stops_away": "0",
                    "driver": "Jeff Moleyes"
                },
                "dismissal_date": 1666261020,
                "alert": {
                    "title": "Order Delivered",
                    "body": "Hope you enjoy!"
                },
                "priority": 10,
                "stale_date": 1666261020,
                "relevance_score": 50
            }
        }
    }
}