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

# Example app: tags, custom events, and Conversion Metrics

> How the Clean Beans example app uses tags for current state, custom events for actions, and Conversion Metrics to measure what messages achieve.

This page is part of [Example app: a full OneSignal integration](https://documentation.onesignal.com/docs/en/example-full-integration-overview.md), 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.

Identity tells OneSignal who someone is. Tags and events tell it what they are like and what they do. Clean Beans uses three kinds of data, each for a different job.

| Data | Describes | Used for |
| - | - | - |
| **Tags** | The user's current state | Personalizing messages and building segments |
| **Custom events** | Something the user just did | Triggering Journeys and measuring conversions |
| **Conversion Metrics** | Which messages led to an event | Reporting on what your messaging achieves |

## Tags: the user's current state

After sign-in, after each cleaning session, and after a profile edit, the app gathers a few facts from Supabase and writes them as tags.

```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);
```

| Tag | Example | Typical use |
| - | - | - |
| `user_name` | `George` | Greeting in in-app messages and emails |
| `streak_count` | `5` | Segments such as "streak in progress" |
| `last_clean_ts` | `1720454400` | Segments such as "inactive for 7 days", using [time operators](https://documentation.onesignal.com/docs/en/time-operators.md) |
| `last_room_cleaned` | `Kitchen` | Personalized copy |
| `avatar_filename` | `baked_bean.png` | Showing the user's avatar in a message |
| `household_name` | `The Smiths` | Personalized copy |
| `weekly_leader` | `George` | Leaderboard messages |

> [!NOTE]
>
> Tag values are strings. Store timestamps as Unix seconds so that OneSignal's time operators can compare them.

## Custom events: what just happened

The app records an event when a cleaning session starts and another when it finishes.

```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),
});
```

The completed event carries two numbers, `tasks_completed` and `minutes_cleaned`. They are sent as numbers, not strings, because Conversion Metrics can only total a property that OneSignal has seen as a number.

The session screen fires the event and refreshes the tags at the moment the user confirms what they cleaned.

```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: what your messages achieved

A Conversion Metric counts a custom event and credits it to the messages that came before it. With the event above, Clean Beans can see how many cleaning sessions each reminder led to, and how many minutes of cleaning that added up to.

![A OneSignal message report showing conversion metrics for cleaning sessions](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-conversion-metrics.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=fbb4363265a1b330198afdc0a37feefd)

A push message report showing the cleaning sessions and minutes attributed to it.

**Dashboard setup.** Go to **Settings > Analytics > Conversion Metrics** and create one metric per row.

| Metric name | Custom event | Track a value | Property |
| - | - | - | - |
| Cleaning sessions | `cleaning_session_completed` | No | |
| Minutes cleaned | `cleaning_session_completed` | Yes | `minutes_cleaned` |
| Tasks completed | `cleaning_session_completed` | Yes | `tasks_completed` |

> [!WARNING]
>
> The "Track a value for each event" option only appears once the event has arrived with a number-typed property, and it can only be turned on when the metric is created. Send the event from a real session first, check that it has arrived in **Data > Events & Conversions**, and then create the two value metrics.

> [!NOTE]
>
> Conversion Metrics replace Custom Outcomes (`OneSignal.Session.addOutcome()`), which are being deprecated. Clean Beans originally planned to use Outcomes and switched before building. Custom metrics require a paid plan. Clicks and app sessions are tracked on every plan.

> [card] [Tags](https://documentation.onesignal.com/docs/en/add-user-data-tags.md)
>
> Add, remove, and use tags.

> [card] [Custom events](https://documentation.onesignal.com/docs/en/custom-events.md)
>
> Send events from the SDK or your backend.

> [card] [Conversion metrics](https://documentation.onesignal.com/docs/en/conversion-metrics.md)
>
> Attribution windows and reporting.


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