In this tutorial, we walk you through how you can get your application setup to use Live Activities and provide a code sample of how to get your application to enter a Live Activity.

Requirements

• Follow our Live Activities Quickstart to ensure that your application is set up to use OneSignal and Live Activities.

Activity ID

OneSignal introduces the concept of an activity_id to help you track your Live Activities and update multiple Live Activities that your users have started with a single API call.

For example, you may want to use Live Activities for score updates during a sports game. You should assign a unique activity_id for all users following the game and then use the OneSignal API to update all Live Activities with that activity_id when the score changes.

In some cases, Live Activities are user-specific. For example, you may use them to tell a user about the status of a food delivery order. In this case, you should assign a different activity_id for each unique order.

OneSignal is designed to support Live Activities at scale, whether there are millions of users following a single event (like a sports game), or millions of users following individual events (like food delivery status) that you want to update.

Send Your First Live Activity

Step 1: Start a Live Activity

Import OneSignal and ActivityKit into your code and make sure that the Activity's type is accessible from both targets.

import ActivityKit
import OneSignal

Add code to begin a Live Activity and register the activity_id with OneSignal.

import UIKit

import ActivityKit
import OneSignal

class ViewController: UIViewController {
    ///... ViewController code ...

    func startLiveActivity() {

        let attributes = OneSignalWidgetAttributes(name: "OneSignal Dev App Live Activity")
        let contentState = OneSignalWidgetAttributes.ContentState(value: 5)

        do {

            let activity = try Activity<OneSignalWidgetAttributes>.request(

                    attributes: attributes,
                    contentState: contentState,
                    pushType: .token)

            Task {

                for await data in activity.pushTokenUpdates {

                    let myToken = data.map {String(format: "%02x", $0)}.joined()
                    OneSignal.enterLiveActivity("my_activity_id", withToken: myToken)
                }
            }

        } catch (let error) {
            print(error.localizedDescription)
        }
    }
}

📘

Client API Reference

Additional client API examples for Swift and other frameworks can be found in our SDK Reference

Step 2. Update a Live Activity

Follow our Live Activity Server API reference for instructions and examples on updating a Live Activity remotely.

Step 3. End a Live Activity

A Live Activity can be ended by the event being complete, the user removing it from the home screen, or the user revoking permission for Live Activities from their iOS Settings.

In order to end a Live Activity, we recommend that the application should:

1. Remove the Live Activity from the user's home screen
2. Send an Exit call using our OneSignal SDK.

By calling our SDK you enable us to provide more accurate data around the engagement of Live Activities. The SDK methods are below, but additionally do checkout our SDK Reference for more guidance.

OneSignal.exitLiveActivity("my_activity_id")

OneSignal.exitLiveActivity("my_activity_id", (res: object) => {
    loggingFunction("exitLiveActivity completed with result: ", JSON.stringify(res));
})

OneSignal.shared.exitLiveActivity("your_activity_id").then((v) {
    print("Successfully exit live activity");
}).catchError((error) {
    print("Failed to exit live activity: $error");
});

window.plugins.OneSignal.exitLiveActivity("my_activity_id");

OneSignalSDK.DotNet.OneSignal.Default.ExitLiveActivity("my_activity_id");

OneSignalSDK.DotNet.OneSignal.Default.ExitLiveActivity("my_activity_id");

OneSignal.Default.exitLiveActivity("my_activity_id");