둘 다 External ID가 아니라 전화번호나 이메일 주소 같은 연락처 자체로 보냅니다. 이것이 이 가이드의 다른 모든 전송과 가장 큰 차이점입니다.
일회용 코드로 전화번호 인증하기 \
User Profile에서 사용자는 휴대전화 번호를 추가할 수 있습니다. 앱은 백엔드에 6자리 코드를 문자로 보내달라고 요청하고, 사용자가 코드를 입력하면 백엔드가 확인합니다. 그때서야 번호가 인증된 것으로 간주됩니다.
전화번호 추가: 번호 입력, 코드 입력, 인증 완료.
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도 없습니다. 백엔드는 앱의 가입 화면을 여는 링크와 함께 연락처로 직접 보냅니다.
문자나 이메일로 하우스메이트를 초대하는 화면과 받는 메시지.
include_phone_numbers를 사용합니다. 이메일은 email_to를 사용하며, 제목과 HTML 본문을 요청에 직접 담습니다.
supabase/functions/send-invite/index.ts
- 이메일 클릭 추적이 꺼져 있습니다. 추적은 링크가 추적 도메인을 거치도록 재작성하며, 재작성된 링크는 더 이상 앱을 열지 않습니다.
- SMS는 추적용 단축 링크를 사용하지 않습니다. 같은 이유입니다.
login()과 addEmail() 또는 addSms() 호출이 초대로 생성된 구독을 새 사용자에게 연결합니다.
알아두어야 할 사항 \
- 발신자가 필요합니다. Settings > SMS에서 기본 발신자를 선택하거나 요청마다
sms_from을 전달하세요. 둘 다 없으면 요청이 “A valid number is required for ‘From’ field”로 거부됩니다. 200응답이 항상 메시지가 전송되었다는 뜻은 아닙니다. 상태 코드만 보지 말고 응답에 메시지id가 있는지 확인하세요.- 번호는 E.164 형식으로 저장하세요. 더하기 기호 뒤에 국가 코드와 번호가 오는 형식이며, 그 밖의 형식은 API를 호출하기 전에 거부하세요.
- OneSignal Verify는 관리형 대안입니다. 코드를 대신 생성하고 확인합니다. Clean Beans는 전체 흐름을 보여주기 위해 직접 구현합니다.
일회용 비밀번호
OneSignal Verify와 직접 구현.
SMS 옵트인 및 수집
동의 및 고지 요구 사항.
SMS API 레퍼런스
모든 SMS 매개변수.