This page is part of the Customer.io documentation. For the complete documentation index, see llms.txt.

20

Live Activities

Live Activities let you push real-time, continuously updated notifications to the iOS Lock Screen and Dynamic Island, like a delivery tracker, a live score, or a countdown. Define your activity’s data model, render it with your own widget, and let Customer.io push updates without your app being open.

See How live notifications work to learn more about the live notification lifecycle.

How the pieces fit

• You define an ActivityKit ActivityAttributes type describing your activity’s data, and a widget that renders it. The SDK never renders your activity—the design is entirely yours.
• The SDK observes activities of the types you register, captures and registers push tokens, and reports lifecycle events to Customer.io.
• Your server starts, updates, and ends activities by calling the API—it never talks to APNs.

Before you begin

You need to complete two one-time setup steps in Xcode:

1. Add a Widget Extension target (File > New > Target > Widget Extension) if you don’t already have one. Your Live Activity UI lives here.
2. Enable Live Activities by setting NSSupportsLiveActivities to YES in your app target’s Info settings. If your activity updates frequently, also set NSSupportsLiveActivitiesFrequentUpdates to YES.

Step 1: Add the SDK packages

Live Activities span two libraries. Add each to the correct target, using the names for your dependency manager:

The attributes library (LiveActivities_Attributes or CustomerIOLiveActivitiesAttributes) contains only protocols and value types—no SDK machinery—so it’s safe to import in your widget extension, which needs it to share your activity’s data model with the app. Add it to both the app target and the widget extension target.

If your app uses the bundled templates, also add the templates library to both targets—LiveActivities_Templates with Swift Package Manager, or CustomerIOLiveActivitiesTemplates with CocoaPods.

Step 2: Define your activity’s data model

Create an ActivityAttributes type describing your activity. Make the file a member of both your app target and your widget extension target—ActivityKit matches the two sides by the type’s name and Codable shape, so sharing one source file is the intended pattern.

import ActivityKit
import CioLiveActivities_Attributes

struct DeliveryActivityAttributes: CIOActivityAttribute {
    // Reverse-DNS identifier, registered with the SDK and matched
    // server-side to route pushes.
    static let identifier = "io.customer.liveactivities.deliverytracking"

    // Managed by Customer.io. Declare it with a default and never set it
    // yourself—the SDK fills it in on local start, and Customer.io fills
    // it in for push-to-start.
    var cioInstanceId: String = ""

    // Your static fields—set once at start, never change.
    var orderNumber: String

    // Your dynamic fields—updated over the activity's life.
    struct ContentState: Codable, Hashable, CIOMetadataCarrying {
        var title: String
        var subtitle: String?
        var estimatedArrival: EpochSecondsDate?

        // Deep-link and delivery metadata for the push that produced
        // this state. nil for locally-driven updates.
        var cioMetadata: CIOLiveActivityMetadata?
    }
}

Three Customer.io-specific pieces to note:

• CIOActivityAttribute is a one-property protocol (cioInstanceId) that opts your activity type into push-to-start, so your server can create the activity remotely. A plain ActivityAttributes type also works. The SDK still observes it for local starts, updates, and ends, but you can only start conforming activity types from your server.
• CIOMetadataCarrying is optional. Declare cioMetadata on your ContentState to receive each update’s deep link and delivery attribution.
• EpochSecondsDate decodes the epoch-second date fields Customer.io sends, so live countdowns work without custom decoding.

Step 3: Build your widget

Render your activity in your widget extension with a standard ActivityKit ActivityConfiguration. This is your SwiftUI—Customer.io doesn’t constrain the design.

import ActivityKit
import CioLiveActivities_Attributes
import SwiftUI
import WidgetKit

struct DeliveryActivityWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: DeliveryActivityAttributes.self) { context in
            // Your Lock Screen view
            DeliveryLockScreenView(state: context.state)
                .cioWidgetUrl(context.state.cioMetadata)
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.bottom) {
                    Text(context.state.title)
                }
            } compactLeading: {
                Image(systemName: "shippingbox.fill")
            } compactTrailing: {
                Text(context.state.subtitle ?? "")
            } minimal: {
                Image(systemName: "shippingbox.fill")
            }
        }
    }
}

Use .cioWidgetUrl(context.state.cioMetadata) so a tap opens the deep link your server attached to the latest push and is attributed to the exact delivery. Add the widget to your extension’s WidgetBundle.

Step 4: Initialize the module

Add the Live Activities module to your SDK configuration and register each activity type you want Customer.io to observe. The module is registered with the main SDK, so there’s no separate instance to hold onto—you drive activities through CustomerIO.liveActivities.

import CioDataPipelines
import CioLiveActivities

let configBuilder = SDKConfigBuilder(cdpApiKey: "YOUR_CDP_API_KEY")

if #available(iOS 16.2, *) {
    configBuilder.addModule(
        LiveActivitiesModule(
            config: LiveActivityConfigBuilder()
                .register(
                    DeliveryActivityAttributes.self,
                    identifier: DeliveryActivityAttributes.identifier
                )
                .build()
        )
    )
}

CustomerIO.initialize(withConfig: configBuilder.build())

The register call tells the SDK which activity type to watch. From here on, any activity of that type is observed automatically. The SDK registers its tokens with Customer.io and reports its lifecycle. There’s no per-activity code.

Step 5: Start an activity

There are two ways to start a live activity:

• From your server (push-to-start): You call the API when you’re ready to start an activity and iOS creates it on the device. Your app doesn’t need to be open. This is the most common path for activities like delivery tracking and live scores, and requires iOS 17.2.
• From your app: Start the activity through the module when something happens in the app. This is a common path for activities like a workout progress tracker.

From your server

Call the start endpoint to start an activity for a person. Customer.io sends the push-to-start message, and iOS creates the activity with the attributes and content state from your payload.

From your app

Start the activity through the module—when a customer places an order, for example:

let activity = try CustomerIO.liveActivities.start(
    DeliveryActivityAttributes(orderNumber: "CIO-1234"),
    contentState: .init(title: "Order received")
)

start returns a CIOLiveActivity handle. Calling activity.update(_:) changes the Live Activity on the device but isn’t reported to Customer.io. Calling activity.end(_:) ends it locally and reports the end. If your app already starts activities with raw ActivityKit calls, pass them to CustomerIO.liveActivities.adopt(_:) so the SDK can manage future updates and the end—but note that adopt doesn’t report that activity’s original start.

Once the activity is running, your server can push subsequent updates by calling the update endpoint with the activity’s instance ID. You don’t need to manage push tokens yourself.

Handle deep links

When a customer taps an activity, and the latest push carried a deep link, iOS opens your app with the widget URL. Pass it through CustomerIO.liveActivities.handleWidgetUrl(_:) before your own routing so the tap is attributed to the exact delivery:

func application(_ app: UIApplication, open url: URL,
                 options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    guard let destination = CustomerIO.liveActivities.handleWidgetUrl(url) else {
        return true
    }
    return handleDeepLink(destination)
}

handleWidgetUrl records the tap for metrics. For non-Customer.io URLs, it returns the original URL unchanged. For a Customer.io widget URL, it returns the embedded destination, or nil if no destination was provided.

Related pages

• Live notifications overview
• How live notifications work
• Payload reference