> ## 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/ko/example-full-integration-overview.md)의 일부입니다. 앱은 공유 주택을 위한 청소 당번표 앱인 **Clean Beans**이며, Expo(React Native)와 Supabase 백엔드로 만들어졌습니다.

ID는 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/ko/time-operators.md)를 사용한 "7일 동안 비활성" 같은 세그먼트 |
| `last_room_cleaned` | `Kitchen` | 개인화된 문구 |
| `avatar_filename` | `baked_bean.png` | 메시지에 사용자 아바타 표시 |
| `household_name` | `The Smiths` | 개인화된 문구 |
| `weekly_leader` | `George` | 순위표 메시지 |

> [!NOTE]
>
> 태그 값은 문자열입니다. OneSignal의 시간 연산자로 비교할 수 있도록 타임스탬프는 Unix 초 단위로 저장하세요.

## 커스텀 이벤트: 방금 일어난 일 \\

앱은 청소 세션이 시작될 때와 끝날 때 각각 이벤트를 기록합니다.

```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를 사용할 계획이었지만 구축 전에 전환했습니다. 커스텀 지표에는 유료 요금제가 필요합니다. 클릭과 앱 세션은 모든 요금제에서 추적됩니다.

> [card] [태그](https://documentation.onesignal.com/docs/ko/add-user-data-tags.md)
>
> 태그 추가, 삭제 및 활용.

> [card] [커스텀 이벤트](https://documentation.onesignal.com/docs/ko/custom-events.md)
>
> SDK 또는 백엔드에서 이벤트 보내기.

> [card] [전환 지표](https://documentation.onesignal.com/docs/ko/conversion-metrics.md)
>
> 기여 기간과 보고서.


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