> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 示例应用：Live Activities

> 示例应用 Clean Beans 如何从后端启动、更新和结束 iOS Live Activities，并附上小组件代码和 API 请求。

本页面是[示例应用：完整的 OneSignal 集成](https://documentation.onesignal.com/docs/cn/example-full-integration-overview.md)的一部分，该指南从头到尾跟随一个真实应用。这个应用是 **Clean Beans**，一款面向合租家庭的打扫值日表应用，使用 Expo（React Native）和 Supabase 后端构建。

Live Activity 是显示在 iOS 锁屏和灵动岛（Dynamic Island）上的一个小型实时更新视图。Clean Beans 使用了两个：一个是距离用户打扫时段的倒计时，另一个是连续记录即将中断时的警告。

![iOS 锁屏上的打扫提醒 Live Activity](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-LiveActivity-countdown.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=d3e51363076f6271d5f47cfec850e5e2)

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

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

## 设置应用 \\

跨平台应用可以让 OneSignal 管理 Live Activity 的生命周期。启动时调用一次即可，JavaScript 部分仅此而已。

```typescript app/_layout.tsx theme={null}
// Enable Live Activities with the default attributes type
OneSignal.LiveActivities.setupDefault({
  enablePushToStart: true,
  enablePushToUpdate: true,
});
```

您需要编写的唯一原生代码是用 SwiftUI 实现的小组件布局。Clean Beans 通过一个小型 Expo 配置插件将小组件扩展添加到 iOS 项目中，因此每次构建时仍可从头生成项目。

```javascript plugins/withLiveActivityWidget.js theme={null}
const WIDGET_TARGET_NAME = "CleanBeansWidgetExtension";
const WIDGET_BUNDLE_ID_SUFFIX = ".CleanBeansWidgetExtension";
const DEPLOYMENT_TARGET = "16.2";
```

## 绘制小组件 \\

小组件使用 OneSignal 的 `DefaultLiveActivityAttributes`，它可以携带任意格式的数据。一个小组件通过读取 `type` 值并选择布局来同时支持两种活动。

```swift plugins/widget/CleanBeansWidgetLiveActivity.swift theme={null}
struct CleanBeansWidgetLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: DefaultLiveActivityAttributes.self) { context in
            // Dispatch based on activity type
            let activityType = context.attributes.data["type"]?.asString() ?? "streak-warning"

            if activityType == "cleaning-reminder" {
                CleaningReminderLockScreen(context: context)
            } else {
                StreakWarningLockScreen(context: context)
            }

        } dynamicIsland: { context in
            let activityType = context.attributes.data["type"]?.asString() ?? "streak-warning"

            if activityType == "cleaning-reminder" {
                return cleaningReminderDynamicIsland(context: context)
            } else {
                return streakWarningDynamicIsland(context: context)
            }
        }
    }
}
```

每个布局都从后端发送的数据中读取值。`attributes` 在活动启动时确定。`state` 可以随每次更新而变化。

```swift plugins/widget/CleanBeansWidgetLiveActivity.swift theme={null}
let title = context.attributes.data["title"]?.asString() ?? "Streak Warning"
let message = context.state.data["message"]?.asDict()?["en"]?.asString()
    ?? "Your streak is at risk!"
let streakCount = context.state.data["streakCount"]?.asInt() ?? 0
let midnightTs = context.state.data["midnightTs"]?.asInt() ?? 0
let midnightDate = Date(timeIntervalSince1970: Double(midnightTs))
```

倒计时使用 SwiftUI 的计时器样式绘制，无需服务器进一步更新即可在设备上走动。

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

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

```typescript supabase/functions/streak-warning/index.ts theme={null}
const payload = {
  event: 'start',
  activity_id: activityId,
  include_aliases: {
    external_id: [user.id],
  },
  target_channel: 'push',
  event_attributes: {
    data: {
      title: 'Streak Warning',
    },
  },
  event_updates: {
    data: {
      message: {
        en: `Your ${user.streakCount}-day streak ends at midnight!`,
      },
      streakCount: user.streakCount,
      midnightTs: user.midnightTs,
      userName: user.name,
    },
  },
  name: 'Streak Warning',
  contents: {
    en: `Your ${user.streakCount}-day streak ends at midnight!`,
  },
  headings: {
    en: 'Streak at risk!',
  },
  priority: 10,
};

const res = await fetch(
  `https://api.onesignal.com/apps/${ONESIGNAL_APP_ID}/activities/activity/DefaultLiveActivityAttributes`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Key ${ONESIGNAL_REST_API_KEY}`,
    },
    body: JSON.stringify(payload),
  }
);
```

![倒计时到午夜的连续记录警告 Live Activity](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-LA-warning.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=586ca54b6a57f7d1647d5e9bb5aa874f)

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

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

打扫提醒会经历三个阶段。每个阶段都是针对同一活动的单独请求。

| 阶段 | 时机 | 请求 | 小组件显示内容 |
| - | - | - | - |
| 倒计时 | 时段开始前一小时 | `start` | 倒计时到开始时间的计时器 |
| 进行中 | 时段开始 | `update` | “It's your scheduled cleaning time, jump to it!” |
| 已结束 | 时段结束 | `end` | 五秒后消失 |

函数会计算每位用户应处于哪个阶段。

```typescript supabase/functions/cleaning-activity/index.ts theme={null}
function getDesiredPhase(
  currentHour: number,
  window: CleaningWindow,
): 'countdown' | 'active' | null {
  const reminderHour = (window.start - 1 + 24) % 24;

  // Active: inside the cleaning window
  if (isHourInRange(currentHour, window.start, window.end)) return 'active';

  // Countdown: the single hour before the window starts
  if (currentHour === reminderHour) return 'countdown';

  return null;
}
```

它会将当前阶段存储在用户资料中，并且只有在目标阶段不同时才发送请求。这让每小时任务可以安全地重复运行。

更新和结束使用与启动不同的端点。活动在 URL 中指定，因此这些请求不包含定向信息。

```typescript supabase/functions/cleaning-activity/index.ts theme={null}
async function updateCleaningActivity(activityId: string): Promise<boolean> {
  const payload = {
    event: 'update',
    event_updates: {
      data: {
        message: { en: "It's your scheduled cleaning time, jump to it!" },
        phase: 'active',
        targetTs: 0,
      },
    },
    name: 'Cleaning Active',
    contents: { en: "It's your scheduled cleaning time!" },
    priority: 10,
  };

  // ...
}

async function endCleaningActivity(activityId: string): Promise<boolean> {
  const payload = {
    event: 'end',
    event_updates: {
      data: {
        message: { en: 'Cleaning window ended' },
        phase: 'ended',
      },
    },
    name: 'Cleaning Ended',
    dismissal_date: Math.floor(Date.now() / 1000) + 5, // dismiss after 5s
    priority: 10,
  };

  // ...
}
```

> [!NOTE]
>
> 这些请求使用 `priority: 10`，因为每个请求都是应立即显示的阶段变化，而且每人每天最多只收到几次。优先级 `10` 会计入 Apple 为每台设备分配的 Live Activity 更新预算。对于频繁更新的内容（例如比分或进度条），请从 `5` 开始。

> [!WARNING]
>
> 请将更新和结束请求发送到 `/apps/{app_id}/live_activities/{activity_id}/notifications`，而不是启动端点。Clean Beans 最初把三种请求都发送到了启动端点，结果每次更新和结束都被拒绝，并返回“Missing required parameter - event\_attributes”。

> [!NOTE]
>
> 为每个活动分配独立的 `activity_id`，并在活动启动时保存。活动结束后，OneSignal 不再接受针对该 `activity_id` 的更新，因此如果每位用户使用固定 ID，第一天之后就会失效。

> [card] [跨平台设置](https://documentation.onesignal.com/docs/cn/cross-platform-live-activity-setup.md)
>
> `setupDefault` 和小组件扩展。

> [card] [启动 Live Activity](https://documentation.onesignal.com/reference/start-live-activity.md)
>
> push-to-start API。

> [card] [更新 Live Activity](https://documentation.onesignal.com/reference/update-live-activity-api.md)
>
> 更新和结束请求。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.