跳转到主要内容
本页面是示例应用:完整的 OneSignal 集成的一部分,该指南从头到尾跟随一个真实应用。这个应用是 Clean Beans,一款面向合租家庭的打扫值日表应用,使用 Expo(React Native)和 Supabase 后端构建。 Live Activity 是显示在 iOS 锁屏和灵动岛(Dynamic Island)上的一个小型实时更新视图。Clean Beans 使用了两个:一个是距离用户打扫时段的倒计时,另一个是连续记录即将中断时的警告。
iOS 锁屏上的打扫提醒 Live Activity

锁屏上正在倒计时的打扫提醒。

Live Activities 通常由应用启动。Clean Beans 从后端启动它们,因为无论应用是否打开,它们都需要在设定的时间出现。OneSignal 的 push-to-start 让这成为可能。

设置应用 \

跨平台应用可以让 OneSignal 管理 Live Activity 的生命周期。启动时调用一次即可,JavaScript 部分仅此而已。
app/_layout.tsx
您需要编写的唯一原生代码是用 SwiftUI 实现的小组件布局。Clean Beans 通过一个小型 Expo 配置插件将小组件扩展添加到 iOS 项目中,因此每次构建时仍可从头生成项目。
plugins/withLiveActivityWidget.js

绘制小组件 \

小组件使用 OneSignal 的 DefaultLiveActivityAttributes,它可以携带任意格式的数据。一个小组件通过读取 type 值并选择布局来同时支持两种活动。
plugins/widget/CleanBeansWidgetLiveActivity.swift
每个布局都从后端发送的数据中读取值。attributes 在活动启动时确定。state 可以随每次更新而变化。
plugins/widget/CleanBeansWidgetLiveActivity.swift
倒计时使用 SwiftUI 的计时器样式绘制,无需服务器进一步更新即可在设备上走动。

连续记录警告:从后端启动活动 \

在当地时间晚上 7 点,有连续记录但今天还没打扫的用户会收到一个到午夜的倒计时。每小时运行的函数使用与推送提醒相同的时区匹配找出这些用户,然后为每人启动一个活动。
supabase/functions/streak-warning/index.ts
倒计时到午夜的连续记录警告 Live Activity

倒计时到午夜的连续记录警告。

打扫提醒:启动、更新、结束 \

打扫提醒会经历三个阶段。每个阶段都是针对同一活动的单独请求。 函数会计算每位用户应处于哪个阶段。
supabase/functions/cleaning-activity/index.ts
它会将当前阶段存储在用户资料中,并且只有在目标阶段不同时才发送请求。这让每小时任务可以安全地重复运行。 更新和结束使用与启动不同的端点。活动在 URL 中指定,因此这些请求不包含定向信息。
supabase/functions/cleaning-activity/index.ts
这些请求使用 priority: 10,因为每个请求都是应立即显示的阶段变化,而且每人每天最多只收到几次。优先级 10 会计入 Apple 为每台设备分配的 Live Activity 更新预算。对于频繁更新的内容(例如比分或进度条),请从 5 开始。
请将更新和结束请求发送到 /apps/{app_id}/live_activities/{activity_id}/notifications,而不是启动端点。Clean Beans 最初把三种请求都发送到了启动端点,结果每次更新和结束都被拒绝,并返回“Missing required parameter - event_attributes”。
为每个活动分配独立的 activity_id,并在活动启动时保存。活动结束后,OneSignal 不再接受针对该 activity_id 的更新,因此如果每位用户使用固定 ID,第一天之后就会失效。

跨平台设置

setupDefault 和小组件扩展。

启动 Live Activity

push-to-start API。

更新 Live Activity

更新和结束请求。