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

# 예제 앱: OneSignal 전체 통합

> 실제 앱인 Clean Beans를 따라가며 Expo와 Supabase에서 푸시, 인앱, 이메일, SMS, Live Activities, Event Streams가 어떻게 함께 동작하는지 확인하세요.

대부분의 OneSignal 가이드는 한 번에 하나의 기능을 설명합니다. 이 가이드는 하나의 앱을 처음부터 끝까지 따라가며, 프로덕션에서 실행되는 코드와 함께 모든 메시징 기능이 어떻게 연결되었는지 보여줍니다.

앱은 공유 주택을 위한 청소 당번표 앱인 **Clean Beans**입니다. Expo(React Native)로 만들어졌으며 데이터베이스, 인증, 백엔드 함수에 Supabase를 사용합니다. 앱이 보내는 모든 메시지는 OneSignal이 처리합니다.

![Clean Beans의 세 화면: 대시보드, 청소 세션, 주간 당번표](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-dashboard-session-rota.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=f8fc7eac8e69faea6aece66f73c2d820)

Clean Beans: 대시보드, 청소 세션, 주간 당번표.

## Clean Beans가 하는 일 \\

가구가 방을 추가하면 앱은 이를 적절한 빈도의 청소 작업 목록으로 바꿉니다. 당번표 생성기는 각 사람의 가용 시간에 맞춰 작업을 일주일에 걸쳐 배분합니다. 구성원들은 청소 세션을 진행하고, 작업을 체크하고, 매일 연속 기록을 쌓고, 서로 kudos를 보내고, 주간 순위표에서 경쟁합니다.

청소는 공유되고, 반복되며, 시간 제한이 있기 때문에 알림, 소셜 업데이트, 카운트다운, 요약, 코칭 등 거의 모든 종류의 메시지에 잘 맞습니다.

## 이 가이드가 있는 이유 \\

이 가이드를 사용해 세 가지 질문에 답하세요.

* **어떤 OneSignal 기능이 어떤 작업에 맞을까요?** 각 페이지는 앱이 해야 했던 일에서 시작해 그 일을 하는 기능을 보여줍니다.
* **코드는 어디에 둘까요?** 어떤 작업은 앱에, 어떤 작업은 백엔드에, 어떤 작업은 OneSignal 대시보드에 속합니다. 각 예제에서 어디에 속하는지 알려줍니다.
* **무엇이 잘못될 수 있을까요?** 각 페이지의 경고와 참고에는 실제로 출시하면서 배운 내용이 담겨 있습니다. `collapse_id` 설정은 시도했다가 제거했으며, [안정적이고 올바르게 동작하는 푸시](https://documentation.onesignal.com/docs/ko/example-full-integration-reliable-push.md)에서 그 이유를 설명합니다.

## 읽는 방법 \\

이 가이드는 주제별로 한 페이지씩 구성되어 있습니다. 순서대로 읽을 필요는 없습니다. [SDK 설정 및 사용자 ID](https://documentation.onesignal.com/docs/ko/example-full-integration-sdk-setup.md)는 다른 모든 내용의 기반입니다. 그 이후의 각 페이지는 독립적으로 읽을 수 있습니다.

대부분의 기능은 같은 방식으로 소개됩니다.

1. **사용자에게 보이는 것**, 보통 스크린샷과 함께 제공됩니다.
2. **작동 방식**, 누가 무엇을 하는지에 대한 짧은 흐름입니다.
3. **코드**, 앱에서 가져온 것입니다. 각 코드 블록의 제목은 원본 파일입니다.
4. **대시보드 설정**, 기능을 OneSignal에서 구성해야 하는 경우입니다.

제한 사항과 예상치 못한 동작은 해당 기능 옆의 경고와 참고에 표시되어 있습니다.

> [!NOTE]
>
> 코드는 실제 코드이지만, 식별자는 `YOUR_ONESIGNAL_APP_ID`, `YOUR_PROJECT_REF` 같은 자리표시자로 바꿨습니다. 긴 파일은 중요한 줄만 남겼습니다. `// ...`만 있는 줄은 코드를 생략한 위치를 나타냅니다.

## 구성 요소가 함께 동작하는 방식 \\

| 위치 | 담당하는 일 | 예시 |
| - | - | - |
| **Expo 앱** | 기기나 로그인한 사용자가 필요한 모든 것 | SDK 초기화, 권한 요청, 사용자 식별, 태그, 커스텀 이벤트, 인앱 메시지 트리거, 탭 처리 |
| **Supabase 백엔드** | 일정이나 데이터 변경으로 트리거되는 모든 것 | 알림, 소셜 푸시, 주간 이메일, SMS 코드와 초대, Live Activities 시작, Event Stream 웹훅 수신 |
| **OneSignal 대시보드** | 릴리스 없이 바꿀 수 있어야 하는 콘텐츠와 타겟팅 | 인앱 메시지, 이메일 템플릿, 세그먼트, Conversion Metrics, Event Stream |

**External ID**가 이 세 가지를 연결합니다. Clean Beans는 로그인 시 External ID를 Supabase 사용자 ID로 설정하므로, 백엔드는 이미 저장하고 있는 ID로 누구에게나 메시지를 보낼 수 있습니다.

![Expo 앱, Supabase 백엔드, OneSignal 대시보드를 보여주는 아키텍처 다이어그램](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/clean-beans-architecture.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=b6d5655991cdf5b4de0645b9d7f9cd95)

앱, 백엔드, 대시보드는 각각 OneSignal과 통신합니다. External ID가 이들을 한 사용자로 연결합니다.

## 기능 맵 \\

| 앱에 필요했던 것 | OneSignal 기능 | 페이지 |
| - | - | - |
| 각 기기가 누구의 것인지 파악 | External ID, 이메일 구독 | [SDK 설정 및 사용자 ID](https://documentation.onesignal.com/docs/ko/example-full-integration-sdk-setup.md) |
| 개인화 및 세그먼트 | 태그, 커스텀 이벤트, Conversion Metrics | [태그, 커스텀 이벤트, Conversion Metrics](https://documentation.onesignal.com/docs/ko/example-full-integration-tags-events.md) |
| 작업 알림 | 예약된 함수에서 Create message API 호출 | [백엔드에서 푸시 보내기](https://documentation.onesignal.com/docs/ko/example-full-integration-backend-push.md) |
| 하우스메이트에게 일어난 일 알리기 | 앱 및 데이터베이스 이벤트에서 Create message API 호출 | [백엔드에서 푸시 보내기](https://documentation.onesignal.com/docs/ko/example-full-integration-backend-push.md) |
| 알림을 두 번 보내지 않기 | 멱등성 키 | [안정적이고 올바르게 동작하는 푸시](https://documentation.onesignal.com/docs/ko/example-full-integration-reliable-push.md) |
| 푸시마다 적절하게 동작하게 하기 | 만료, 그룹화, 중단 수준, 배지 | [안정적이고 올바르게 동작하는 푸시](https://documentation.onesignal.com/docs/ko/example-full-integration-reliable-push.md) |
| 탭이나 링크에서 올바른 화면 열기 | 클릭 리스너, 딥 링크, Universal Links | [딥 링크 및 알림 클릭](https://documentation.onesignal.com/docs/ko/example-full-integration-deep-links.md) |
| 알림에서 바로 동작하게 하기 | 액션 버튼, 예약 전송 | [딥 링크 및 알림 클릭](https://documentation.onesignal.com/docs/ko/example-full-integration-deep-links.md) |
| 앱 안에서 안내하고 유도하기 | 트리거와 커스텀 HTML을 사용하는 인앱 메시지 | [인앱 메시지](https://documentation.onesignal.com/docs/ko/example-full-integration-in-app-messages.md) |
| 주간 요약 보내기 | `custom_data`를 사용하는 이메일 템플릿 | [custom\_data를 사용한 주간 이메일](https://documentation.onesignal.com/docs/ko/example-full-integration-weekly-email.md) |
| 전화번호가 사용자의 것인지 증명하기 | 전화번호로 직접 보내는 SMS, SMS 구독 | [SMS: 인증 코드와 초대](https://documentation.onesignal.com/docs/ko/example-full-integration-sms.md) |
| 앱이 없는 사람 초대하기 | 연락처로 직접 보내는 SMS와 이메일 | [SMS: 인증 코드와 초대](https://documentation.onesignal.com/docs/ko/example-full-integration-sms.md) |
| 잠금 화면에 카운트다운 표시 | Live Activities | [Live Activities](https://documentation.onesignal.com/docs/ko/example-full-integration-live-activities.md) |
| 앱에 알림 기록 보관 | Event Streams | [Event Streams를 사용한 알림 수신함](https://documentation.onesignal.com/docs/ko/example-full-integration-inbox.md) |
| 수신 거부와 앱 설정 동기화 | Event Streams(이메일 이벤트) | [Event Streams를 사용한 알림 수신함](https://documentation.onesignal.com/docs/ko/example-full-integration-inbox.md) |

## 필요한 것 \\

* iOS와 Android 푸시가 구성되어 있고 이메일과 SMS도 설정된 OneSignal 앱. [채널 설정](https://documentation.onesignal.com/docs/ko/channel-setup.md)을 참조하세요.
* EAS Build로 빌드한 Expo 앱. OneSignal SDK에는 네이티브 코드가 필요하므로 Expo Go로는 충분하지 않습니다. [Expo SDK 설정](https://documentation.onesignal.com/docs/ko/react-native-expo-sdk-setup.md)을 참조하세요.
* App ID와 App API key. [키 및 ID](https://documentation.onesignal.com/docs/ko/keys-and-ids.md)를 참조하세요.
* 일정에 따라, 그리고 요청에 응답해 코드를 실행할 수 있는 백엔드. Clean Beans는 Supabase Edge Functions와 `pg_cron`을 사용합니다. 같은 패턴은 어떤 백엔드에도 적용됩니다.

## 효과가 있었던 원칙 \\

* **External ID를 먼저 설정하세요.** 여기 나오는 거의 모든 기능이 External ID에 의존합니다. 백엔드가 이미 저장하고 있는 ID를 사용하세요.
* **각 작업을 알맞은 곳에 두세요.** 앱은 기기와 로그인한 사용자를 처리합니다. 백엔드는 일정과 데이터 변경을 처리합니다. 대시보드에는 릴리스 없이 바꾸고 싶은 모든 것을 둡니다.
* **보내기 전에 확인하세요.** 백엔드의 모든 전송은 사용자의 설정을 확인하고 전할 만한 내용이 있는지 확인합니다.
* **예약 전송을 반복 실행해도 안전하게 만드세요.** 유형, 수신자, 날짜로 만든 멱등성 키를 사용하면 재시도해도 아무 일도 일어나지 않습니다.
* **URL이 아니라 유형으로 라우팅하세요.** `data.type` 필드가 있으면 화면이 옮겨져도 이전 알림이 계속 올바르게 동작합니다.
* **호출자가 알려주는 내용을 검증하세요.** 메시지를 보내는 함수는 먼저 자체 데이터베이스에서 사실을 확인해야 합니다.

## 전체 기능 한눈에 보기 \\

| 기능 | 채널 | 트리거 | 실행 위치 | 주요 파일 |
| - | - | - | - | - |
| SDK 초기화 및 권한 | 푸시 | 앱 실행 | 앱 | `app/_layout.tsx` |
| 사용자 ID | 전체 | 로그인 및 로그아웃 | 앱 | `app/_layout.tsx` |
| 이메일 구독 | 이메일 | 로그인 | 앱 | `src/lib/onesignalSync.ts` |
| 옵트인 및 설정 | 푸시, 이메일 | 설정 화면 | 앱 및 데이터베이스 | `app/notification-settings.tsx` |
| 태그 | 전체 | 로그인, 세션, 프로필 수정 | 앱 | `src/lib/onesignalSync.ts` |
| 커스텀 이벤트 | 전체 | 세션 시작 및 종료 | 앱 | `src/lib/onesignalSync.ts` |
| Conversion Metrics | 전체 | 세션 종료 | 대시보드 | |
| 일일 요약 | 푸시 | 매시간 일정 | 백엔드 | `supabase/functions/send-daily-digest/` |
| 기한 초과 알림 | 푸시 | 매시간 일정 | 백엔드 | `supabase/functions/send-overdue-reminders/` |
| 청소 알림 | 푸시 | 매시간 일정 | 백엔드 | `supabase/functions/send-cleaning-reminder/` |
| 세션 완료 | 푸시 | 앱에서 호출 | 백엔드 | `supabase/functions/session-completed/` |
| Kudos | 푸시 | 앱에서 호출 | 백엔드 | `supabase/functions/send-kudos/` |
| 가입 승인 | 푸시 | 데이터베이스 트리거 | 백엔드 | `supabase/functions/join-approved/` |
| 멱등 전송 | 푸시, 이메일 | 모든 예약 전송 | 백엔드 | `supabase/functions/_shared/idempotency.ts` |
| 전송 프로필 | 푸시 | 모든 푸시 | 백엔드 | `supabase/functions/_shared/delivery.ts` |
| 배지 | 푸시 | 작업 푸시 | 백엔드 | `supabase/functions/send-daily-digest/` |
| 탭 라우팅 | 푸시 | 푸시 탭 | 앱 | `app/_layout.tsx` |
| 액션 버튼 | 푸시 | 푸시 버튼 탭 | 백엔드 및 앱 | `supabase/functions/_shared/buttons.ts`, `src/lib/pushActions.ts` |
| 다시 알림 | 푸시 | 다시 알림 버튼 | 백엔드 | `supabase/functions/snooze-reminder/` |
| 링크 재작성 | 링크 | URL로 앱 열기 | 앱 | `app/+native-intent.tsx` |
| Universal Links 및 App Links | 링크 | 웹 링크 탭 | 앱 및 웹사이트 | `app.json`, `website/.well-known/` |
| 도움말 오버레이 및 안내 | 인앱 | 도움말 버튼 | 앱 및 대시보드 | `src/components/HelpButton.tsx` |
| 푸시 권한 사전 안내 | 인앱 | 대시보드 대상 | 대시보드 | `docs/iam-html/push-permission-prompt.html` |
| 앱 업데이트 안내 | 인앱 | 오래된 앱 버전 | 대시보드 | `docs/iam-html/app-update-prompt.html` |
| 리뷰 요청 | 인앱 | 연속 기록 달성 | 앱 및 대시보드 | `src/lib/reviewPrompt.ts` |
| 주간 보고서 | 이메일 | 매주 일정 | 백엔드 및 대시보드 | `supabase/functions/weekly-report/` |
| SMS 구독 | SMS | 전화번호 인증, 로그인 | 앱 | `src/lib/phone.ts` |
| 전화번호 인증 코드 | SMS | 앱에서 호출 | 백엔드 | `supabase/functions/send-otp/`, `supabase/functions/verify-otp/` |
| 가구 초대 | SMS, 이메일 | 앱에서 호출 | 백엔드 | `supabase/functions/send-invite/` |
| 연속 기록 경고 | Live Activity | 매시간 일정 | 백엔드 및 위젯 | `supabase/functions/streak-warning/` |
| 청소 알림 | Live Activity | 매시간 일정 | 백엔드 및 위젯 | `supabase/functions/cleaning-activity/` |
| 알림 수신함 | Event Streams | 푸시 전송 또는 클릭마다 | 백엔드 및 앱 | `supabase/functions/inbox-webhook/` |
| 이메일 설정 동기화 | Event Streams | 이메일 수신 거부, 반송, 스팸 신고 | 백엔드 | `supabase/functions/inbox-webhook/` |

## 시크릿 \\

백엔드 함수는 이 값들을 환경 변수에서 읽습니다. 어떤 값도 앱에 포함되지 않습니다.

```bash theme={null}
supabase secrets set ONESIGNAL_APP_ID=YOUR_ONESIGNAL_APP_ID
supabase secrets set ONESIGNAL_REST_API_KEY=YOUR_APP_API_KEY
supabase secrets set ONESIGNAL_WEEKLY_TEMPLATE_ID=YOUR_EMAIL_TEMPLATE_ID
supabase secrets set INBOX_WEBHOOK_SECRET=YOUR_SHARED_SECRET
supabase secrets set OTP_HASH_SECRET=A_LONG_RANDOM_STRING    # key for hashing SMS verification codes

# Optional
supabase secrets set ONESIGNAL_SMS_FROM=YOUR_SMS_SENDER      # if no default sender is set in the dashboard
```

> [!WARNING]
>
> App API key는 모든 사용자에게 메시지를 보낼 수 있습니다. 백엔드에만 보관하세요. 앱 자체에는 App ID만 있으면 됩니다.


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