> ## 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やメールで人を招待する方法。

このページは、1つの実在アプリを最初から最後まで追う[サンプルアプリ：OneSignalの完全な統合](https://documentation.onesignal.com/docs/ja/example-full-integration-overview.md)の一部です。アプリは**Clean Beans**という共同生活の家のための掃除当番表アプリで、Expo（React Native）とSupabaseバックエンドで構築されています。

Clean Beansは、プッシュやメールでは難しい2つの用途にSMSを使います。電話番号が入力した本人のものであることの証明と、まだアプリを持っていない人への連絡です。

| メッセージ | 送信先 | トリガー |
| - | - | - |
| 認証コード | サインイン中のユーザーが入力したばかりの番号 | アプリからの呼び出し |
| 世帯への招待 | アカウントを持たない人の電話番号またはメールアドレス | アプリからの呼び出し |

どちらもExternal IDではなく、電話番号やメールアドレスといった**連絡先そのもの**に送信します。これが、このガイドのほかのすべての送信との主な違いです。

## ワンタイムコードで電話番号を認証する \\

User Profileで、ユーザーは携帯電話番号を追加できます。アプリはバックエンドに6桁のコードをSMSで送るよう依頼し、ユーザーがそれを入力し、バックエンドが確認します。それが済んで初めて、番号は認証済みとみなされます。

![番号の入力、コードの入力、認証済みの3つの状態の電話番号カード](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. コードを確認する**

バックエンドはユーザーが入力した値をハッシュ化し、保存済みのハッシュと比較します。誤入力は回数が記録されます。5回誤るとコードは無効になり、新しいコードをリクエストする必要があります。

```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()
);
```

## 番号を入力する場所で同意を得る \\

電話番号があるだけでは、SMSを送る許可にはなりません。認証コードの場合は、電話番号の入力欄の横に開示文を置けば十分です。開示文には、送信者、送信内容、料金が発生する場合があること、停止方法を記載する必要があります。

```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画面で、メンバーはSMSまたはメールで人を招待できます。招待される人にはアカウントも、登録済みのデバイスも、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またはメールで同居人を招待する画面と、相手が受け取るメッセージ。

同じエンドポイントで両方のチャネルを扱います。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,
    };
```

リンクは[通常のWebリンクからアプリを開く](https://documentation.onesignal.com/docs/ja/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links)で設定したUniversal Linkです。正しく機能させるための2つのポイントがあります。

* **メールのクリックトラッキングをオフにしています。** トラッキングはリンクをトラッキング用ドメイン経由に書き換えるため、書き換えられたリンクではアプリが開かなくなります。
* **SMSではトラッキング付きの短縮リンクを使いません**。理由は同じです。

招待された人がアプリをインストールしてサインインすると、アプリの`login()`と`addEmail()`または`addSms()`の呼び出しにより、招待で作成されたサブスクリプションがその新しいユーザーに紐付きます。

> [!WARNING]
>
> 招待された人は、あなたのアプリからの連絡に同意していません。迷惑SMSやメールに関する規則は国によって異なり、厳しい場合もあります。Clean Beansは連絡先への直接送信の仕組みを示すためにこのフローを含めており、各メンバーの招待数を1日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/ja/sms-setup.md)を完了し、ユーザーのいる国に届くデフォルトの送信者を選んでください。

> [card] [ワンタイムパスワード](https://documentation.onesignal.com/docs/ja/sms-verify.md)
>
> OneSignal Verifyと独自実装。

> [card] [SMSのオプトインと収集](https://documentation.onesignal.com/docs/ja/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.