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

# 예제 앱: SMS 인증 코드와 초대

> 예제 앱 Clean Beans가 OneSignal로 일회용 코드를 보내 전화번호를 인증하고 SMS나 이메일로 사람을 초대하는 방법입니다.

이 페이지는 실제 앱 하나를 처음부터 끝까지 따라가는 [예제 앱: OneSignal 전체 통합](https://documentation.onesignal.com/docs/ko/example-full-integration-overview.md)의 일부입니다. 앱은 공유 주택을 위한 청소 당번표 앱인 **Clean Beans**이며, Expo(React Native)와 Supabase 백엔드로 만들어졌습니다.

Clean Beans는 푸시와 이메일이 잘하지 못하는 두 가지 작업에 SMS를 사용합니다. 전화번호가 이를 입력한 사람의 것인지 증명하는 일과, 아직 앱이 없는 사람에게 연락하는 일입니다.

| 메시지 | 받는 사람 | 트리거 |
| - | - | - |
| 인증 코드 | 로그인한 사용자가 방금 입력한 번호 | 앱에서 호출 |
| 가구 초대 | 계정이 없는 사람의 전화번호 또는 이메일 주소 | 앱에서 호출 |

둘 다 External ID가 아니라 전화번호나 이메일 주소 같은 **연락처 자체**로 보냅니다. 이것이 이 가이드의 다른 모든 전송과 가장 큰 차이점입니다.

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

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

![번호 입력, 코드 입력, 인증 완료의 세 가지 상태를 보여주는 전화번호 카드](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-phone-verification.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=ae377258019c7454d600dc86bb722cce)

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

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

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

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

```typescript supabase/functions/_shared/otp.ts theme={null}
export function generateCode(): string {
  const limit = 4_000_000_000; // a multiple of 1,000,000 below 2^32, so no code is more likely than another
  const buf = new Uint32Array(1);
  do {
    crypto.getRandomValues(buf);
  } while (buf[0] >= limit);
  return String(buf[0] % 1_000_000).padStart(6, '0');
}

export async function hashCode(secret: string, userId: string, phone: string, code: string): Promise<string> {
  const key = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign'],
  );
  const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${userId}:${phone}:${code}`));
  return Array.from(new Uint8Array(sig), (b) => b.toString(16).padStart(2, '0')).join('');
}
```

```typescript supabase/functions/send-otp/index.ts theme={null}
const { data: inserted, error: insertErr } = await supabase
  .from('phone_otp_codes')
  .insert({
    user_id: user.id,
    phone,
    code_hash: codeHash,
    expires_at: new Date(now.getTime() + OTP_TTL_MINUTES * 60_000).toISOString(),
  })
  .select('id')
  .single();
```

**2. OneSignal을 통해 SMS로 보내기**

`include_phone_numbers`는 번호를 직접 지정합니다. OneSignal이 처음 보는 번호라면 SMS 구독을 만듭니다.

```typescript supabase/functions/send-otp/index.ts theme={null}
const onesignalPayload = {
  app_id: ONESIGNAL_APP_ID,
  target_channel: 'sms',
  // Targets a raw phone number. OneSignal creates an SMS subscription
  // for it if one does not exist yet.
  include_phone_numbers: [phone],
  ...(ONESIGNAL_SMS_FROM ? { sms_from: ONESIGNAL_SMS_FROM } : {}),
  name: 'Phone verification code',
  contents: {
    en: `Your Clean Beans verification code is ${code}. It expires in ${OTP_TTL_MINUTES} minutes.`,
  },
};
```

**3. 코드 확인하기**

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

```typescript supabase/functions/verify-otp/index.ts theme={null}
const submittedHash = await hashCode(OTP_HASH_SECRET, user.id, phone, code);

if (!safeEqual(submittedHash, row.code_hash)) {
  const attempts = row.attempts + 1;
  await supabase.from('phone_otp_codes').update({ attempts }).eq('id', row.id);

  const left = OTP_MAX_ATTEMPTS - attempts;
  return jsonResponse({
    error: 'invalid_code',
    message: left > 0
      ? `That code is not right. ${left} ${left === 1 ? 'attempt' : 'attempts'} left.`
      : 'Too many wrong attempts. Request a new code.',
    attemptsLeft: Math.max(left, 0),
  }, 400);
}
```

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

백엔드가 코드를 확인하면 앱이 로그인한 사용자에게 번호를 추가합니다.

```typescript src/lib/phone.ts theme={null}
export async function confirmPhoneCode(phone: string, code: string): Promise<void> {
  await callFunction('verify-otp', { body: { phone, code } });
  OneSignal.User.addSms(phone);
}
```

앱은 로그인할 때마다 이를 반복하므로, 인증된 번호가 새 기기에서도 사용자를 따라갑니다.

```typescript src/lib/phone.ts theme={null}
export async function syncOneSignalSms(): Promise<void> {
  try {
    const phone = await loadVerifiedPhone();
    if (phone) {
      OneSignal.User.addSms(phone);
      console.log('[phone] SMS subscription synced');
    }
  } catch (e) {
    console.warn('[phone] syncOneSignalSms error:', e);
  }
}
```

> [!NOTE]
>
> 이메일과 마찬가지로 `addSms()`는 `login()` 이후에 호출하세요. 전화번호로 직접 보내면 누구에게도 속하지 않은 구독이 만들어집니다. 로그인한 앱에서 `addSms()`를 호출하면 그 구독이 사용자에게 연결됩니다. 그 전까지는 대시보드에 별도의 사용자 레코드로 표시됩니다.

## 엔드포인트 보호하기 \\

요청에 따라 문자 메시지를 보내는 함수는 실행할 때마다 비용이 들고, 악용의 대상이 됩니다. Clean Beans는 다음 제한을 적용합니다.

| 규칙 | 값 |
| - | - |
| 코드 유효 시간 | 10분 |
| 허용되는 틀린 시도 | 5회 |
| 재전송 전 대기 시간 | 30초 |
| 사용자당 코드 수 | 10분마다 3개 |
| 코드당 사용 횟수 | 1회. 새 코드는 이전 코드를 대체합니다 |

```typescript supabase/functions/send-otp/index.ts theme={null}
const MAX_CODES_PER_WINDOW = 3;
const WINDOW_MINUTES = 10;
const RESEND_COOLDOWN_SECONDS = 30;
```

인증된 번호는 별도 테이블에 저장됩니다. 백엔드만 쓸 수 있으므로 앱이 번호를 인증된 것으로 표시할 수 없고, 가구의 다른 구성원도 읽을 수 없습니다.

```sql supabase/migrations/028_phone_verification_and_invites.sql theme={null}
create table if not exists public.user_phones (
  user_id     uuid primary key references public.profiles(id) on delete cascade,
  phone       text not null,                       -- E.164, e.g. +14155551234
  verified_at timestamptz not null default now()
);
```

## 번호를 입력하는 곳에서 동의 받기 \\

전화번호만으로는 문자를 보내도 된다는 허락이 되지 않습니다. 인증 코드의 경우 전화번호 입력란 옆에 안내 문구를 두면 충분하며, 누가 보내는지, 무엇을 보내는지, 요금이 부과될 수 있다는 점, 수신을 중단하는 방법을 밝혀야 합니다.

```tsx src/components/PhoneVerificationCard.tsx theme={null}
{/* Consent disclosure: must sit next to the phone field */}
<Text style={styles.disclosure}>
  Enter your mobile number to receive verification codes by text message from Clean Beans.
  Msg & data rates may apply. Reply STOP to opt out.
</Text>
```

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

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

![초대 대화상자와 이를 통해 보내지는 초대 문자 메시지](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-invitation.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=78d087c22898bc9876dbdd1f90c56033)

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

같은 엔드포인트가 두 채널을 모두 처리합니다. SMS는 `include_phone_numbers`를 사용합니다. 이메일은 `email_to`를 사용하며, 제목과 HTML 본문을 요청에 직접 담습니다.

```typescript supabase/functions/send-invite/index.ts theme={null}
const joinUrl = `${JOIN_URL}?code=${encodeURIComponent(household.invite_code)}`;

const onesignalPayload: Record<string, unknown> = channel === 'sms'
  ? {
      app_id: ONESIGNAL_APP_ID,
      target_channel: 'sms',
      // Raw phone number: OneSignal creates an SMS subscription if needed
      include_phone_numbers: [contact],
      ...(ONESIGNAL_SMS_FROM ? { sms_from: ONESIGNAL_SMS_FROM } : {}),
      name: 'Household invitation (SMS)',
      contents: {
        en: `${inviterName} invited you to join "${householdName}" on Clean Beans, the cleaning rota app. Join: ${joinUrl} Reply STOP to opt out.`,
      },
    }
  : {
      app_id: ONESIGNAL_APP_ID,
      target_channel: 'email',
      // Raw email address: OneSignal creates an email subscription if needed
      email_to: [contact],
      name: 'Household invitation (email)',
      email_subject: `${inviterName} invited you to Clean Beans`,
      email_preheader: `Join "${householdName}" and share the cleaning.`,
      email_body: buildInviteEmail(inviterName, householdName, joinUrl, household.invite_code),
      // Keep the join link exactly as written. Click tracking would wrap
      // it in a redirect, and it would stop opening the app directly.
      disable_email_click_tracking: true,
    };
```

링크는 [일반 웹 링크로 앱 열기](https://documentation.onesignal.com/docs/ko/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links)에서 설정한 Universal Link입니다. 두 가지 세부 사항 덕분에 링크가 계속 동작합니다.

* **이메일 클릭 추적이 꺼져 있습니다.** 추적은 링크가 추적 도메인을 거치도록 재작성하며, 재작성된 링크는 더 이상 앱을 열지 않습니다.
* **SMS는 추적용 단축 링크를 사용하지 않습니다.** 같은 이유입니다.

초대받은 사람이 앱을 설치하고 로그인하면, 앱의 `login()`과 `addEmail()` 또는 `addSms()` 호출이 초대로 생성된 구독을 새 사용자에게 연결합니다.

> [!WARNING]
>
> 초대받은 사람은 앱으로부터 연락받는 데 동의하지 않았습니다. 원치 않는 문자와 이메일에 관한 규정은 국가마다 다르고 엄격할 수 있습니다. 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 설정](https://documentation.onesignal.com/docs/ko/sms-setup.md)을 완료하고 사용자가 있는 국가에 도달할 수 있는 기본 발신자를 선택하세요.

> [card] [일회용 비밀번호](https://documentation.onesignal.com/docs/ko/sms-verify.md)
>
> OneSignal Verify와 직접 구현.

> [card] [SMS 옵트인 및 수집](https://documentation.onesignal.com/docs/ko/sms-opt-in-and-collection.md)
>
> 동의 및 고지 요구 사항.

> [card] [SMS API 레퍼런스](https://documentation.onesignal.com/reference/sms.md)
>
> 모든 SMS 매개변수.


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