Skip to main content
This page is part of Example app: a full OneSignal integration, which follows one real app from end to end. The app is Clean Beans, a cleaning rota for shared homes, built with Expo (React Native) and a Supabase backend. A Live Activity is a small, live-updating view on the iOS Lock Screen and in the Dynamic Island. Clean Beans uses two: a countdown to the user’s cleaning window, and a warning when a streak is about to end.
A cleaning reminder Live Activity on the iOS Lock Screen

The cleaning reminder counting down on the Lock Screen.

Live Activities are normally started by the app. Clean Beans starts them from the backend, because they need to appear at a set time whether or not the app is open. OneSignal’s push-to-start makes that possible.

Set up the app

A cross-platform app can let OneSignal manage the Live Activity’s lifecycle. One call at startup is all the JavaScript needed.
app/_layout.tsx
The only native code you write is the widget’s layout, in SwiftUI. Clean Beans adds the widget extension to the iOS project with a small Expo config plugin, so the project can still be generated from scratch on every build.
plugins/withLiveActivityWidget.js

Draw the widget

The widget uses OneSignal’s DefaultLiveActivityAttributes, which carries free-form data. One widget serves both activities by reading a type value and choosing a layout.
plugins/widget/CleanBeansWidgetLiveActivity.swift
Each layout reads its values from the data the backend sent. attributes are fixed when the activity starts. state can change with each update.
plugins/widget/CleanBeansWidgetLiveActivity.swift
A countdown is drawn with SwiftUI’s timer style, which ticks on the device without any further updates from the server.

Streak warning: start an activity from the backend

At 7 PM local time, anyone with a streak who has not cleaned today gets a countdown to midnight. The hourly function finds them using the same time zone matching as the push reminders, then starts an activity for each.
supabase/functions/streak-warning/index.ts
A streak warning Live Activity counting down to midnight

The streak warning counts down to midnight.

Cleaning reminder: start, update, end

The cleaning reminder moves through three phases. Each is a separate request for the same activity. The function works out which phase each user should be in.
supabase/functions/cleaning-activity/index.ts
It stores the current phase on the user’s profile and only sends a request when the desired phase is different. That makes the hourly job safe to run repeatedly. Updating and ending use a different endpoint from starting. The activity is named in the URL, so these requests carry no targeting.
supabase/functions/cleaning-activity/index.ts
These requests use priority: 10 because each one is a change of phase that should appear immediately, and a person gets at most a few in a day. Priority 10 counts against the budget Apple allows each device for Live Activity updates. For anything that updates often, such as a score or a progress bar, start with 5.
Send updates and ends to /apps/{app_id}/live_activities/{activity_id}/notifications, not to the start endpoint. Clean Beans originally sent all three to the start endpoint, and every update and end was rejected with “Missing required parameter - event_attributes”.
Give each activity its own activity_id and store it when the activity starts. OneSignal does not accept further updates to an activity_id once that activity has ended, so a fixed ID per user would stop working after the first day.

Cross-platform setup

setupDefault and the widget extension.

Start Live Activity

The push-to-start API.

Update Live Activity

Update and end requests.