Set up Live Activities

Live Activities display real-time updates on the Lock Screen and Dynamic Island, without the user opening your app. Use them for time-sensitive events such as order tracking, live scores, or limited-time offers.

Blueshift delivers the push. Your app defines and renders the widget.

Before you begin

• Devices running iOS 17.2 or later
• Blueshift iOS SDK 2.8.0 or later
• The Push Notifications capability added under Signing & Capabilities in your Xcode project
• Token-based (.p8) push authentication configured on your Blueshift push adapter
• A widget extension target in your Xcode project

Step 1: Add the SDK to your app

Use either Swift Package Manager or CocoaPods. If your project already includes the Blueshift iOS SDK, follow Add Live Activity support to an existing installation below instead.

Install with Swift Package Manager

1. In Xcode, go to File > Add Package Dependencies.

2. Enter the repository URL and press Return:

   Text

   https://github.com/blueshift-labs/Blueshift-iOS-SDK.git

3. Set Add to Project to your app project, then click Add Package.

4. In the Choose Package Products dialog that opens, set the Add to Target column as follows:

   Package product	Add to target
   BlueShift_iOS_SDK	Your app target
   BlueShift_iOS_SDK_LiveActivity	Your app target
   BlueShift_iOS_SDK_SwiftUI	None
   BlueShift_iOS_Extension_SDK	None

5. Click Add Package.

Note: If BlueShift_iOS_SDK_LiveActivity does not appear in the product list, the package is resolved to a version earlier than 2.8.0. Go to File > Packages > Update to Latest Package Versions, then add the product from your app target's General > Frameworks, Libraries, and Embedded Content.

Next, link the library to your widget extension, which renders the Live Activity:

1. In the Xcode navigator, click your project file.
2. Select your widget extension target.
3. Go to Build Phases > Link Binary With Libraries.
4. Click +, search for BlueShift_iOS_SDK_LiveActivity, then click Add.

Install with CocoaPods

The SDK is published on CocoaPods as BlueShift-iOS-SDK. In your Podfile, add the Live Activity pod to your app target and nest your widget extension target inside it:

target 'YourApp' do
  pod 'BlueShift-iOS-SDK/LiveActivity'

  target 'YourWidgetExtension' do
    inherit! :search_paths
  end
end

inherit! :search_paths reuses the framework built for the app target, so the widget extension does not need a separate copy.

Then run:

pod install

Add Live Activity support to an existing installation

Live Activity support ships as a separate module. Updating to 2.8.0 does not add it — you also need to add the module to your project.

Swift Package Manager

1. In Xcode, go to Project > Package Dependencies and update BlueShift-iOS-SDK to 2.8.0 or later.
2. Select your app target and go to General > Frameworks, Libraries, and Embedded Content.
3. Click +, select BlueShift_iOS_SDK_LiveActivity, then click Add.

CocoaPods

Add the Live Activity subspec alongside your existing pod:

pod 'BlueShift-iOS-SDK'
pod 'BlueShift-iOS-SDK/LiveActivity'

Then run:

pod update BlueShift-iOS-SDK

Your widget extension also needs the library. See Install with Swift Package Manager or Install with CocoaPods above for the setup.

Step 2: Define your activity attributes

Your ActivityAttributes struct must conform to both ActivityAttributes and BlueshiftActivityAttributes. The bsftActivityId property is required — it links the activity on the device to the ID you send in the API call.

import ActivityKit
import BlueShift_iOS_SDK
import BlueShift_iOS_SDK_LiveActivity

struct DeliveryActivityAttribute: ActivityAttributes, BlueshiftActivityAttributes {
    var bsftActivityId: String?
    var activityName: String

    public struct ContentState: Codable, Hashable {
        var title: String?
        var subtitle: String?
        var progress: Double?
    }
}

Add this file to both targets. Select the file in Xcode, open the File Inspector, and under Target Membership select both your app target and your widget extension target. If the file is missing from the widget extension, the build fails with Cannot find type 'BlueshiftActivityAttributes' in scope.

Important: The property names in ContentState must exactly match the keys you send in content_state in the API call. A mismatch is not reported as an error. The API returns a success response and the device discards the update.

Step 3: Register your activity types

Register each activity type at app launch, inside application(_:didFinishLaunchingWithOptions:) in your AppDelegate. This registers the device with Blueshift so it can receive remotely started Live Activities.

import BlueShift_iOS_SDK
import BlueShift_iOS_SDK_LiveActivity

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // Your existing Blueshift SDK setup

    if #available(iOS 17.2, *) {
        BlueshiftLiveActivityManager.shared.registerPushToStart(
            forType: Activity<DeliveryActivityAttribute>.self,
            name: "DeliveryActivityAttribute"
        )
    }

    return true
}

Register each activity type in a separate call. The name parameter must match the activity_attributes_type value you send in the API call.

How it works

1. The device sends a push-to-start token to Blueshift when the app launches.
2. Your backend calls Start a Live Activity. Blueshift builds the payload and delivers the push to the device.
3. iOS creates the Live Activity and displays it on the Lock Screen and Dynamic Island.
4. The SDK registers the activity's instance token with Blueshift.
5. Your backend calls Update a Live Activity to change the content or end the activity.

Limits

Activities beyond the concurrent limit, and payloads above the size limit, are not delivered. For events that run longer than the update window, end the activity and start a new one for each stage. For more information, see Apple's Live Activity constraints.

Implementation notes

• The user must allow Live Activities. The first time an activity is started remotely, iOS asks the user to allow Live Activities for your app. Until the user responds, the activity is not registered with Blueshift and updates to it fail.

• The SDK registers the activity with Blueshift after it starts on the device. Updates sent before registration completes return a Running Live Activity not found error. Retry the update instead of treating it as a permanent failure.

• A success response means the push was dispatched, not displayed. Delivery depends on the device's state and the user's settings.

Next steps

• Start a Live Activity (coming soon)
• Update a Live Activity (coming soon)