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

# Application d'exemple : codes de vérification et invitations par SMS

> Comment l'application d'exemple Clean Beans vérifie les numéros de téléphone avec des codes à usage unique et invite des personnes par SMS ou e-mail avec OneSignal.

Cette page fait partie de [Application d'exemple : une intégration OneSignal complète](https://documentation.onesignal.com/docs/fr/example-full-integration-overview.md), qui suit une application réelle de bout en bout. L'application s'appelle **Clean Beans**, un planning de ménage pour les logements partagés, construite avec Expo (React Native) et un backend Supabase.

Clean Beans utilise le SMS pour deux tâches que le push et l'e-mail ne font pas bien : prouver qu'un numéro de téléphone appartient à la personne qui l'a saisi, et joindre quelqu'un qui n'a pas encore l'application.

| Message | Envoyé à | Déclencheur |
| - | - | - |
| Code de vérification | Le numéro qu'un utilisateur connecté vient de saisir | Appel depuis l'application |
| Invitation au foyer | Un numéro de téléphone ou une adresse e-mail d'une personne sans compte | Appel depuis l'application |

Les deux sont envoyés à un **contact brut**, un numéro de téléphone ou une adresse e-mail, et non à un External ID. C'est la principale différence avec tous les autres envois de ce guide.

## Vérifier un numéro de téléphone avec un code à usage unique \\

Dans User Profile, un utilisateur peut ajouter un numéro de mobile. L'application demande au backend d'envoyer par SMS un code à 6 chiffres, l'utilisateur le saisit et le backend le vérifie. Ce n'est qu'alors que le numéro est considéré comme vérifié.

![La carte du numéro de téléphone dans trois états : saisie du numéro, saisie du code et vérifié](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-phone-verification.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=ae377258019c7454d600dc86bb722cce)

Ajouter un numéro de téléphone : saisir le numéro, saisir le code, vérifié.

OneSignal livre le SMS. Il ne crée ni ne vérifie le code. Tout le reste est du ressort de votre backend.

**1. Générer un code et le stocker haché**

Le code provient d'une source aléatoire cryptographique. Seul un hachage avec clé est stocké, lié à l'utilisateur et au numéro de téléphone, de sorte que la table seule ne permet pas de retrouver les codes. La clé est un secret dédié, `OTP_HASH_SECRET`, qui ne sert à rien d'autre. Les deux fonctions refusent de s'exécuter s'il n'est pas défini.

```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. L'envoyer par SMS via OneSignal**

`include_phone_numbers` cible directement le numéro. Si OneSignal ne l'a jamais vu, il crée un abonnement SMS pour ce numéro.

```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. Vérifier le code**

Le backend hache ce que l'utilisateur a saisi et le compare au hachage stocké. Chaque tentative erronée est comptabilisée. Au bout de cinq, le code n'est plus valide et il faut en demander un nouveau.

```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. Enregistrer le numéro comme abonnement SMS**

Une fois le code confirmé par le backend, l'application ajoute le numéro à l'utilisateur connecté.

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

L'application répète cette opération après chaque connexion, de sorte qu'un numéro vérifié suit l'utilisateur sur un nouvel appareil.

```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]
>
> Appelez `addSms()` après `login()`, comme pour l'e-mail. Un envoi vers un numéro de téléphone brut crée un abonnement qui n'appartient à personne. `addSms()` depuis une application connectée rattache cet abonnement à l'utilisateur. Jusque-là, il apparaît dans le tableau de bord comme un enregistrement utilisateur distinct.

## Protéger l'endpoint \\

Une fonction qui envoie un SMS à la demande coûte de l'argent à chaque exécution et constitue une cible d'abus. Clean Beans applique ces limites.

| Règle | Valeur |
| - | - |
| Durée de validité du code | 10 minutes |
| Tentatives erronées autorisées | 5 |
| Délai avant renvoi | 30 secondes |
| Codes par utilisateur | 3 toutes les 10 minutes |
| Utilisations par code | Une. Un nouveau code remplace tout code précédent |

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

Le numéro vérifié est conservé dans sa propre table. Seul le backend peut y écrire, l'application ne peut donc pas marquer un numéro comme vérifié, et les autres membres d'un foyer ne peuvent pas le lire.

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

## Demander le consentement là où le numéro est saisi \\

Un numéro de téléphone ne constitue pas à lui seul une autorisation d'envoyer des SMS. Pour les codes de vérification, une mention à côté du champ de téléphone suffit. Elle doit indiquer qui envoie, ce qui sera envoyé, que des frais peuvent s'appliquer et comment se désinscrire.

```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>
```

## Inviter une personne qui n'est pas encore utilisatrice \\

Sur l'écran Household, un membre peut inviter quelqu'un par SMS ou par e-mail. La personne invitée n'a ni compte, ni appareil enregistré, ni External ID. Le backend envoie au contact brut, avec un lien qui ouvre l'écran d'adhésion de l'application.

![La boîte de dialogue d'invitation et le SMS d'invitation qu'elle envoie](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-invitation.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=78d087c22898bc9876dbdd1f90c56033)

Inviter un colocataire par SMS ou e-mail, et le message qu'il reçoit.

Le même endpoint gère les deux canaux. Le SMS utilise `include_phone_numbers`. L'e-mail utilise `email_to`, avec l'objet et le corps HTML transmis directement dans la requête.

```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,
    };
```

Le lien est un Universal Link, configuré dans [Ouvrir l'application depuis des liens web ordinaires](https://documentation.onesignal.com/docs/fr/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links). Deux détails lui permettent de fonctionner :

* **Le suivi des clics dans l'e-mail est désactivé.** Le suivi réécrit les liens pour les faire passer par un domaine de suivi, et un lien réécrit n'ouvre plus l'application.
* **Le SMS n'utilise pas de lien court suivi**, pour la même raison.

Lorsque la personne invitée installe l'application et se connecte, les appels `login()` et `addEmail()` ou `addSms()` de l'application rattachent à son nouvel utilisateur l'abonnement créé par l'invitation.

> [!WARNING]
>
> La personne invitée n'a pas accepté de recevoir des messages de votre application. Les règles concernant les SMS et e-mails non sollicités varient selon les pays et peuvent être strictes. Clean Beans inclut ce parcours pour montrer comment fonctionne l'envoi à un contact brut, et limite chaque membre à dix invitations par jour. Avant d'utiliser ce modèle en production, vérifiez les règles des pays vers lesquels vous envoyez, et envisagez de faire envoyer le message par la personne qui invite depuis son propre téléphone.

## À savoir \\

* **Un expéditeur est obligatoire.** Choisissez un expéditeur par défaut dans **Settings > SMS**, ou transmettez `sms_from` avec chaque requête. Sans l'un ni l'autre, la requête est rejetée avec « A valid number is required for 'From' field ».
* **Une réponse `200` ne signifie pas toujours qu'un message a été envoyé.** Vérifiez la présence d'un `id` de message dans la réponse, et pas seulement le code de statut.
* **Stockez les numéros au format E.164**, un signe plus suivi de l'indicatif du pays et du numéro, et rejetez tout autre format avant d'appeler l'API.
* **OneSignal Verify est l'alternative gérée.** Il génère et vérifie les codes pour vous. Clean Beans crée les siens pour montrer le parcours complet.

**Configuration du tableau de bord.** Effectuez la [configuration SMS](https://documentation.onesignal.com/docs/fr/sms-setup.md) et choisissez un expéditeur par défaut capable d'atteindre les pays de vos utilisateurs.

> [card] [Mots de passe à usage unique](https://documentation.onesignal.com/docs/fr/sms-verify.md)
>
> OneSignal Verify et créer votre propre solution.

> [card] [Opt-in et collecte SMS](https://documentation.onesignal.com/docs/fr/sms-opt-in-and-collection.md)
>
> Exigences de consentement et de mentions.

> [card] [Référence de l'API SMS](https://documentation.onesignal.com/reference/sms.md)
>
> Tous les paramètres SMS.


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