> ## 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.

# 示例应用：标签、自定义事件和 Conversion Metrics

> 示例应用 Clean Beans 如何用标签记录当前状态、用自定义事件记录行为，并用 Conversion Metrics 衡量消息的成效。

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

身份告诉 OneSignal 某人是谁。标签和事件告诉它这个人是什么样的、做了什么。Clean Beans 使用三类数据，各有不同用途。

| 数据 | 描述 | 用途 |
| - | - | - |
| **标签** | 用户的当前状态 | 个性化消息和创建细分 |
| **自定义事件** | 用户刚刚做的事 | 触发 Journeys 和衡量转化 |
| **Conversion Metrics** | 哪些消息促成了某个事件 | 报告消息的成效 |

## 标签：用户的当前状态 \\

在登录后、每次打扫会话后以及编辑资料后，应用会从 Supabase 收集一些信息并写入标签。

```typescript src/lib/onesignalSync.ts theme={null}
// ── 5. Push tags to OneSignal ────────────────────────────
const tags: Record<string, string> = {
  user_name: profile.name || '',
  streak_count: String(profile.streak_count ?? 0),
  last_clean_ts: lastCleanTs,
  last_room_cleaned: lastRoomCleaned,
  avatar_filename: avatarFilename,
  household_name: householdName,
  weekly_leader: weeklyLeader,
};

OneSignal.User.addTags(tags);
```

| 标签 | 示例 | 典型用途 |
| - | - | - |
| `user_name` | `George` | 应用内消息和邮件中的问候语 |
| `streak_count` | `5` | 例如“连续记录进行中”的细分 |
| `last_clean_ts` | `1720454400` | 使用[时间运算符](https://documentation.onesignal.com/docs/cn/time-operators.md)创建例如“7 天未活跃”的细分 |
| `last_room_cleaned` | `Kitchen` | 个性化文案 |
| `avatar_filename` | `baked_bean.png` | 在消息中显示用户头像 |
| `household_name` | `The Smiths` | 个性化文案 |
| `weekly_leader` | `George` | 排行榜消息 |

> [!NOTE]
>
> 标签值是字符串。请将时间戳存储为 Unix 秒，以便 OneSignal 的时间运算符进行比较。

## 自定义事件：刚刚发生了什么 \\

应用会在打扫会话开始时记录一个事件，在结束时再记录一个。

```typescript src/lib/onesignalSync.ts theme={null}
OneSignal.User.trackEvent('cleaning_session_started', {
  external_id: ctx.external_id,
  user_name: ctx.user_name,
  household_name: ctx.household_name,
  room_name: roomName,
});
```

```typescript src/lib/onesignalSync.ts theme={null}
OneSignal.User.trackEvent('cleaning_session_completed', {
  external_id: ctx.external_id,
  user_name: ctx.user_name,
  household_name: ctx.household_name,
  room_name: roomName,
  tasks_completed: stats.tasksCompleted,
  minutes_cleaned: Math.round(stats.minutesCleaned),
});
```

完成事件带有两个数字：`tasks_completed` 和 `minutes_cleaned`。它们以数字而不是字符串发送，因为 Conversion Metrics 只能对 OneSignal 识别为数字的属性求和。

会话界面会在用户确认打扫内容时触发该事件并刷新标签。

```typescript app/clean-session.tsx theme={null}
// Fire session completed custom event and sync updated tags to OneSignal
if (room) {
  trackSessionCompleted(room.name, { tasksCompleted: ids.length, minutesCleaned: mins }).catch(console.warn);
}
syncOneSignalTags();
```

## Conversion Metrics：消息带来了什么 \\

Conversion Metric 会统计自定义事件，并将其归因到之前发送的消息。借助上面的事件，Clean Beans 可以看到每条提醒带来了多少次打扫会话，以及累计了多少分钟的打扫时间。

![显示打扫会话转化指标的 OneSignal 消息报告](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-conversion-metrics.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=fbb4363265a1b330198afdc0a37feefd)

显示归因于该推送的打扫会话和分钟数的推送消息报告。

**仪表板设置。** 前往 **Settings > Analytics > Conversion Metrics**，每行创建一个指标。

| 指标名称 | 自定义事件 | 跟踪数值 | 属性 |
| - | - | - | - |
| Cleaning sessions | `cleaning_session_completed` | 否 | |
| Minutes cleaned | `cleaning_session_completed` | 是 | `minutes_cleaned` |
| Tasks completed | `cleaning_session_completed` | 是 | `tasks_completed` |

> [!WARNING]
>
> “Track a value for each event”选项只有在事件携带数字类型属性到达后才会出现，并且只能在创建指标时开启。请先从一次真实会话发送事件，在 **Data > Events & Conversions** 中确认已到达，然后再创建这两个数值指标。

> [!NOTE]
>
> Conversion Metrics 取代了即将弃用的 Custom Outcomes（`OneSignal.Session.addOutcome()`）。Clean Beans 最初计划使用 Outcomes，在开发前改用了 Conversion Metrics。自定义指标需要付费套餐。点击和应用会话在所有套餐中都会被跟踪。

> [card] [标签](https://documentation.onesignal.com/docs/cn/add-user-data-tags.md)
>
> 添加、删除和使用标签。

> [card] [自定义事件](https://documentation.onesignal.com/docs/cn/custom-events.md)
>
> 从 SDK 或后端发送事件。

> [card] [转化指标](https://documentation.onesignal.com/docs/cn/conversion-metrics.md)
>
> 归因窗口和报告。


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