Live Activities

A quick start guide to adding Live Activity notification support to your Android application with the Pushly PushSDK

Android Live Activity notifications provides a similar feature-set and experience to iOS Live Activities on the Android platform allowing for real-time updated content via push notifications.

The PushSDK helps you streamline Live Activity registration and updates by allowing developers to register and manage the Live Activity handlers which can then be updated via our server API.

Prerequisites

Before you can integrate Live Activities with the SDK the following requirements must be met:

• An Android Send Integration configured with a Firebase Sender ID and Server API Key or Service Account.

• An Android app.

• A device or emulator running API 19+ (Android 4.4) with Google Play Store Services installed.

• PushSDK release supporting Live Activities (See version support chart below).

Step 1: Android SDK Setup

For applications not already using the PushSDK please see our Native App Push setup guide for Android.

For applications already using the PushSDK you might need to upgrade to a later version that includes Live Activity support. Use the following tables to determine if you need to upgrade your installation.

SDK	Earliest Version with Live Activities
Kotlin / Java	1.3.0+

app/build.gradle

dependencies {
    ...
    implementation 'com.pushly.android:pushsdk:[1.3, 2.0['
}

Step 2: Creating a Handler for Live Activity Updates

To handle and display updates you will need to implement the PNLiveActivityHandler class. The handler requires a name that will uniquely identifier this type of activity and start via push. An optional notification channelId can also be specified to group Live Activity notifications into their own channel. When no custom channel ID is specified the PushSDK will use a default channel.

An onUpdate method must be implemented and is responsible for handling any Live Activity event as it is received (start, update, or end). Use this method to customize how updates are displayed to users.

Kotlin

class MyActivityHandler : PNLiveActivityHandler(
    name = "game_updates",
    channelId = "sports_channel"
) {
    override fun onUpdate(context: Context, contentState: ContentState): PNLiveActivityUpdateResult {
        // Create your notification builder
        val builder = Notification.Builder(context, channelId)
            .setSmallIcon(R.drawable.ic_notification)
            .setContentTitle("Game Update")
            .setContentText("${contentState.getString("home_team")} vs ${contentState.getString("away_team")}")
        
        // Return builder with the result
        return PNLiveActivityUpdateResult.Ok(builder)
    }
}

Java

class MyActivityHandler extends PNLiveActivityHandler {
    public MyActivityHandler() {
        super("game_updates", "sports_channel");
    }

    @Override
    public @NonNull PNLiveActivityUpdateResult onUpdate(@NonNull Context context, @NonNull ContentState contentState) {
        String homeTeam = contentState.getStringOrDefault("home_team", "Home Team");
        String awayTeam = contentState.getStringOrDefault("away_team", "Away Team");

        // Create your notification builder
        NotificationCompat.Builder builder = new NotificationCompat.Builder(context, this.getChannelId())
                .setSmallIcon(R.drawable.ic_notification)
                .setContentTitle("Game Update")
                .setContentText(String.format("%s, vs %s", homeTeam, awayTeam));

        // Return builder with the result
        return new PNLiveActivityUpdateResult.Ok(builder);
    }
}

Registering the Handler

Once you have implemented your handler you will need to register it with the PushSDK. The following code snippet shows how to register the handler:

Kotlin

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // ... PushSDK configuration code

        PushSDK.LiveActivities.register(MyActivityHandler())
    }
}

Java

class MainApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        
        // ... PushSDK configuration code

        PushSDK.LiveActivities.register(new MyActivityHandler());
    }
}

Step 3: Starting a Live Activity

Starting from Within the App

The following code snippet requests to start a Live Activity using a unique activityId , a handler name that corresponds to a previously register handler class, and the initial contentState of the activity. In this scenario we will use the PNLiveActivityHandler class registered with the name: game_updates.

Kotlin

class MainActivity : AppCompatActivity() {
    public fun startLiveActivity() {
        PushSDK.LiveActivities.start(
            activityId = "my_activity_id",
            handler = "game_updates", // Must match registered handler name
            contentState = contentStateOf(
                "home_team" to "Chiefs",
                "home_team_score" to 0,
                "away_team" to "Chargers",
                "away_team_score" to 0
            )
        )
    }
}

Java

class MainActivity extends AppCompatActivity {
    public void startLiveActivity() {
        PushSDK.LiveActivities.start(
            "my_activity_id",
            "game_updates", // Must match registered handler name
            ContentState.builder()
                .put("home_team", "Chiefs")
                .put("home_team_score", 0)
                .put("away_team", "Chargers")
                .put("away_team_score", 0)
                .build()
        );
    }
}

Content State

ContentState is used to pass data to Live Activities. You can create your state using convenience method contentStateOf():

Kotlin

val state = contentStateOf(
    "key1" to "value1",
    "key2" to 42,
    "key3" to null
)

Java

ContentState state = ContentState.builder()
    .put("key1", "value1")
    .put("key2", 1)
    .put("key3", null)
    .build();

ContentState supports the following value types: String, Int, Long, Float, Double, Boolean, null.

Starting via Push

Once you have registered the handler with the PushSDK you can use our Live Activity API documentation to send a start event by specifying the corresponding handler name name in the activity.android.data.handler_name property and passing the associated unique activity identifier in the request path - in this scenario we used my_activity_id which we can then use in subsequent update events.

Example Start Request

POST Request to:
https://api.pushly.com/domains/{domain_id}/live-activities/my_activity_id
{
    "name": "my-request-event-name",
    "event": "start",
    "activity": {
        "android": {
            "data": {
                "handler_name": "game_updates",
                "content_state": {
                    "home_team": "Chiefs",
                    "home_team_score": 0,
                    "away_team": "Chargers",
                    "away_team_score": 0
                },
                "notification": {
                    "title": "The Game Has Begun",
                    "body": "Stay tuned for more updates!"
                }
            }
        }
    }
}

Step 4: Send Your Live Activity an Update

Once the Live Activity has been started, either locally or via push, you can use our Live Activity API documentation to send updates to all registered Live Activities via a single request.

Example Update Event

POST Request to:
https://api.pushly.com/domains/{domain_id}/live-activities/my_activity_id
{
    "name": "my-request-event-name",
    "event": "update",
    "activity": {
        "android": {
            "data": {
                "content_state": {
                    "home_team": "Chiefs",
                    "home_team_score": 7,
                    "away_team": "Chargers",
                    "away_team_score": 0
                }
            }
        }
    }
}

Step 5: Removing Live Activities

In a similar fashion to how iOS Live Activities work Android Live Activity notifications will automatically end and self-cleanup after 12 hours from the time they are started. However, there might be situations where you want to cleanup the activity before that time limit has occurred. In those scenarios you can remove a single activity or remove all active activities with the following methods:

Remove a Specific Activity

Kotlin

PushSDK.LiveActivities.remove(activityId = "my_activity_id")

Java

PushSDK.LiveActivities.remove("my_activity_id");

Remove All Activities

Kotlin

PushSDK.LiveActivities.removeAll()

Java

PushSDK.LiveActivities.removeAll();

Best Practices

1. Always register handlers in your application's onCreate method for proper initialization.

2. Return a properly configured Notification.Builder in the handler's onUpdate method.

3. Use consistent activity IDs to properly track and update specific activities.

4. Handle all possible states in your handler's onUpdate method.

5. Implement proper error handling in your handler.

6. Use meaningful handler names that reflect their purpose.

7. Clean up activities when they're no longer needed using and end event or manually calling one of the remove methods.