Guides
Log InSign Up

Live Activities

Learn about Live Activities, a powerful and interactive push notification for iOS and iPadOS devices

Suggest Edits

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 Activities are a powerful mobile app engagement and retention tool and should always provide user value (e.g., they provide the convenience of not needing to repeatedly go back into a mobile app to check status).
  • Test that deep links go to the right spot in your app.
  • Consider utilizing 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 optimize user engagement.

  • Only update a Live Activity when new content is available. Too many updates affect 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 or gamified in a time-sensitive manner.

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 unsubscribes 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. Dynamic Islands can use several presentations, depending on how many live activities are active. All presentations must be supported. This Apple guide covers implementation examples of each presentation.
  • 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)

Recommended

Implement Android Live Updates

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

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

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.

  1. Remove the Live Activity from the user's home screen
  2. 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

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

Updated about 2 months ago