메인 콘텐츠로 건너뛰기
이 페이지는 실제 앱 하나를 처음부터 끝까지 따라가는 예제 앱: OneSignal 전체 통합의 일부입니다. 앱은 공유 주택을 위한 청소 당번표 앱인 Clean Beans이며, Expo(React Native)와 Supabase 백엔드로 만들어졌습니다. Clean Beans는 푸시와 이메일이 잘하지 못하는 두 가지 작업에 SMS를 사용합니다. 전화번호가 이를 입력한 사람의 것인지 증명하는 일과, 아직 앱이 없는 사람에게 연락하는 일입니다. 둘 다 External ID가 아니라 전화번호나 이메일 주소 같은 연락처 자체로 보냅니다. 이것이 이 가이드의 다른 모든 전송과 가장 큰 차이점입니다.

일회용 코드로 전화번호 인증하기 \

User Profile에서 사용자는 휴대전화 번호를 추가할 수 있습니다. 앱은 백엔드에 6자리 코드를 문자로 보내달라고 요청하고, 사용자가 코드를 입력하면 백엔드가 확인합니다. 그때서야 번호가 인증된 것으로 간주됩니다.
번호 입력, 코드 입력, 인증 완료의 세 가지 상태를 보여주는 전화번호 카드

전화번호 추가: 번호 입력, 코드 입력, 인증 완료.

OneSignal은 문자 메시지를 전달합니다. 코드를 만들거나 확인하지는 않습니다. 나머지는 모두 백엔드의 일입니다.
1

코드를 생성하고 해시로 저장하기

코드는 암호학적 난수 소스에서 생성됩니다. 사용자와 전화번호에 묶인 키 해시만 저장하므로 테이블만으로는 코드를 복원할 수 없습니다. 키는 다른 용도로 쓰지 않는 전용 시크릿 OTP_HASH_SECRET입니다. 이 값이 설정되지 않으면 두 함수 모두 실행을 거부합니다.
supabase/functions/_shared/otp.ts
supabase/functions/send-otp/index.ts
2

OneSignal을 통해 SMS로 보내기

include_phone_numbers는 번호를 직접 지정합니다. OneSignal이 처음 보는 번호라면 SMS 구독을 만듭니다.
supabase/functions/send-otp/index.ts
3

코드 확인하기

백엔드는 사용자가 입력한 값을 해시해 저장된 해시와 비교합니다. 틀린 시도는 횟수가 기록됩니다. 다섯 번 틀리면 코드가 무효가 되고 새 코드를 요청해야 합니다.
supabase/functions/verify-otp/index.ts
4

번호를 SMS 구독으로 등록하기

백엔드가 코드를 확인하면 앱이 로그인한 사용자에게 번호를 추가합니다.
src/lib/phone.ts
앱은 로그인할 때마다 이를 반복하므로, 인증된 번호가 새 기기에서도 사용자를 따라갑니다.
src/lib/phone.ts
이메일과 마찬가지로 addSms()는 login() 이후에 호출하세요. 전화번호로 직접 보내면 누구에게도 속하지 않은 구독이 만들어집니다. 로그인한 앱에서 addSms()를 호출하면 그 구독이 사용자에게 연결됩니다. 그 전까지는 대시보드에 별도의 사용자 레코드로 표시됩니다.

엔드포인트 보호하기 \

요청에 따라 문자 메시지를 보내는 함수는 실행할 때마다 비용이 들고, 악용의 대상이 됩니다. Clean Beans는 다음 제한을 적용합니다.
supabase/functions/send-otp/index.ts
인증된 번호는 별도 테이블에 저장됩니다. 백엔드만 쓸 수 있으므로 앱이 번호를 인증된 것으로 표시할 수 없고, 가구의 다른 구성원도 읽을 수 없습니다.
supabase/migrations/028_phone_verification_and_invites.sql
전화번호만으로는 문자를 보내도 된다는 허락이 되지 않습니다. 인증 코드의 경우 전화번호 입력란 옆에 안내 문구를 두면 충분하며, 누가 보내는지, 무엇을 보내는지, 요금이 부과될 수 있다는 점, 수신을 중단하는 방법을 밝혀야 합니다.
src/components/PhoneVerificationCard.tsx

아직 사용자가 아닌 사람 초대하기 \

Household 화면에서 구성원은 문자나 이메일로 누군가를 초대할 수 있습니다. 초대받는 사람에게는 계정도, 등록된 기기도, External ID도 없습니다. 백엔드는 앱의 가입 화면을 여는 링크와 함께 연락처로 직접 보냅니다.
초대 대화상자와 이를 통해 보내지는 초대 문자 메시지

문자나 이메일로 하우스메이트를 초대하는 화면과 받는 메시지.

같은 엔드포인트가 두 채널을 모두 처리합니다. SMS는 include_phone_numbers를 사용합니다. 이메일은 email_to를 사용하며, 제목과 HTML 본문을 요청에 직접 담습니다.
supabase/functions/send-invite/index.ts
링크는 일반 웹 링크로 앱 열기에서 설정한 Universal Link입니다. 두 가지 세부 사항 덕분에 링크가 계속 동작합니다.
  • 이메일 클릭 추적이 꺼져 있습니다. 추적은 링크가 추적 도메인을 거치도록 재작성하며, 재작성된 링크는 더 이상 앱을 열지 않습니다.
  • SMS는 추적용 단축 링크를 사용하지 않습니다. 같은 이유입니다.
초대받은 사람이 앱을 설치하고 로그인하면, 앱의 login()과 addEmail() 또는 addSms() 호출이 초대로 생성된 구독을 새 사용자에게 연결합니다.
초대받은 사람은 앱으로부터 연락받는 데 동의하지 않았습니다. 원치 않는 문자와 이메일에 관한 규정은 국가마다 다르고 엄격할 수 있습니다. Clean Beans는 연락처로 직접 보내는 방식을 보여주기 위해 이 흐름을 포함했으며, 구성원마다 하루 초대를 10건으로 제한합니다. 이 패턴을 프로덕션에서 사용하기 전에 보내는 지역의 규정을 확인하고, 초대하는 사람이 자신의 휴대폰에서 메시지를 보내도록 하는 방법도 고려하세요.

알아두어야 할 사항 \

  • 발신자가 필요합니다. Settings > SMS에서 기본 발신자를 선택하거나 요청마다 sms_from을 전달하세요. 둘 다 없으면 요청이 “A valid number is required for ‘From’ field”로 거부됩니다.
  • 200 응답이 항상 메시지가 전송되었다는 뜻은 아닙니다. 상태 코드만 보지 말고 응답에 메시지 id가 있는지 확인하세요.
  • 번호는 E.164 형식으로 저장하세요. 더하기 기호 뒤에 국가 코드와 번호가 오는 형식이며, 그 밖의 형식은 API를 호출하기 전에 거부하세요.
  • OneSignal Verify는 관리형 대안입니다. 코드를 대신 생성하고 확인합니다. Clean Beans는 전체 흐름을 보여주기 위해 직접 구현합니다.
대시보드 설정. SMS 설정을 완료하고 사용자가 있는 국가에 도달할 수 있는 기본 발신자를 선택하세요.

일회용 비밀번호

OneSignal Verify와 직접 구현.

SMS 옵트인 및 수집

동의 및 고지 요구 사항.

SMS API 레퍼런스

모든 SMS 매개변수.