Due to the up-to-date nature of Live Activities, you need to use our Update Live Activity API to update them. Before they can be updated, they need to start by using the push-to-start and/or click-to-start options as discussed in our Live activities developer setup docs. If using push-to-start, you can use the Start Live Activity API.

The Basics

The best Live Activities provide value to users by escalating relevant information to the home screen. Instead of users constantly going into an app to check for statuses or updates, they can get updates at a glance of their phone.

Live Activities are best for events or tasks with a defined beginning and an end. Do not use a Live Activity to display ads or serve purely promotional purposes. They need to provide user value, or it risks providing a negative user experience and being turned off by the user.

Some other important details about Live Activities:

Live Activities has its own on/off toggle within the Settings app, then under the specific app. This means that a user who has opted out of Push Notifications can still receive Live Activities, and that a user who has Live Activities toggled off could still be opted into Push Notifications.
The first time a user receives a Live Activity, they will be prompted to either allow or not allow future Live Activities.

Many of the following best practices below are a summary of what Apple recommends in their Live Activities Human Interface Guidelines, along with additional OneSignal recommendations.

Live Activities Checklist

User Experience

Functionality:

Live Activity needs to provide user value (typically they provide convenience).
Test that deep links go to the right spot in your app.
Using multiple channels:
- Use push to get customers into the app where they can find important information, and then use Live Activities to track additional updates.
- Use an Alert Notification to get users' attention on Live Activity updates. Don’t use push notifications to alert users about updates. Refer to our API documentation.

Content:

If you must promote something, ensure it is intrinsically tied to a live event or task. We recommend using gamification to bring value to live updates and to optimize user engagement.
Only update a Live Activity when new content is available. Too many updates affects a user's battery life.
Avoid displaying sensitive information in a Live Activity.

Duration:

Start a Live Activity when users would expect it to start. Otherwise, it runs a risk of a user going into their settings app and turning off Live Activities from your app.
Remove the Live Activity from the Lock Screen shortly after the conclusion of the Live Activity (15-30 min).
Ensure a Live Activity is for an event or task that is no longer than 8 hours, and that it is only showing for as long as it is useful to the user.
If you must promote something, ensure it is intrinsically tied to a live event or task

User Journey:

Ensure that a Live Activity appears when expected, usually when a user takes an action (e.g. to follow an event) or opens the app to check for updates (e.g. updated delivery time).

All users: Live Activities should only appear when a user expects them to. Any user can toggle Live Activities on/off in their Settings app at any time.
New users: Ensure a valuable first Live Activity to minimize users unsubscribing from future Live Activities.
If a user is seeing a Live Activity for the first time, they are prompted to allow or not allow all Live Activities in the future. Therefore, it is critical that the first Live Activity a user sees quickly provides value.

User Interface Design

Use a logo mark in each Live Activity and its presentations.
Consider each Live Activity presentation - Compact, Minimal, Expanded, Lock Screen code samples of these views.
Consider different screen sizes.
Prioritize important information to make it easy to understand at a quick glance.
Don’t add elements to your app that draw attention to the Dynamic Island.
Use margins and maintain space between elements and margins.
Design for both Light and Dark mode, or set your Live Activity colors to a dark background tint .activityBackgroundTint(Color.black)with a light foreground color. .activitySystemActionForegroundColor(Color.white)

Use a bold color for the background that aligns with your branding.
Consider adding interactivity such as a button for quick controls (e.g. call delivery driver) or to respond to an update.
Review Apple's guide on displaying Live Activities
Live Activities use WidgetKit functionality and SwiftUI for their user interface. Read Apple's Guide Displaying live data with Live Activities.

Implement Android Live Updates

Android supports the creation of notifications that behave similar to iOS Live Activities. More information is available in our guide on Android Live Updates.

How to create and update a Live Activity

These steps differ from our Push-To-Start Live Activities Guide in that it enables you to start a Live Activity remotely without users needing to be in the app for it to show.

Requirements

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

Activity ID

We've introduced an Activity ID in the Update Live Activity API to help you track your Live Activities and update multiple Live Activities that your users have started with a single API call.

For instance, if you want to update scores during a sports game, you can use Live Activities by assigning a unique Activity ID to each game. Whenever the score changes, use the API to update all Live Activities associated with that Activity ID, assuring that all users following the game receive the updates.
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 millions of users are 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

1. Start a Live Activity

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

import ActivityKit
import OneSignalFramework

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

import SwiftUI

import ActivityKit
import OneSignalFramework

struct ContentView: View {
    @StateObject private var viewModel = LiveActivityViewModel()

    var body: some View {
        VStack {
            Button("Start Live Activity") {
                viewModel.startLiveActivity()
            }
        }
    }
}


class LiveActivityViewModel: ObservableObject {
    func startLiveActivity() {
        let attributes = laLiveActivityAttributes(name: "OneSignal Dev App Live Activity")
        let contentState = laLiveActivityAttributes.ContentState(value:5)
        
        do {
            let activity = try Activity<laLiveActivityAttributes>.request(
                attributes: attributes,
                contentState: contentState,
                pushType: .token)
            
            Task {
                for await data in activity.pushTokenUpdates {
                    let myToken = data.map { String(format: "%02x", $0) }.joined()
                    OneSignal.LiveActivities.enter("my_activity_id", withToken: myToken)
                }
            }
        } catch {
            print(error.localizedDescription)
        }
    }
}

import UIKit

import ActivityKit
import OneSignalFramework

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.LiveActivities.enter("my_activity_id", withToken: myToken)
                }
            }

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

2. Update a Live Activity

Submit a request to the Update Live Activity API.

3. End a Live Activity

In addition to users ending a live activity by removing it from their home screen or revoking permissions for Live activities from their settings, you can programmatically end a Live Activity using our SDK.

Use the SDK

For Live Activities that were started by calling the enter method in the SDK.

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

OneSignal.LiveActivities.exit("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");

Use the API

For Live Activities started via pushToStart token

The event parameter is set to "end"
The dismissal_date is set to the time the Live Activity should disappear