db25bec3e5
- sentry - variables in manifest - some dynamic pages - breadcrumbs - dynamic page resolver
127 lines
4.8 KiB
Markdown
127 lines
4.8 KiB
Markdown
# Documentation du `RecaptchaProvider`
|
||
|
||
Le `RecaptchaProvider` est un composant React qui encapsule la logique d’intégration de Google reCAPTCHA avec gestion des cookies et état du formulaire. Il fonctionne avec **Inertia.js** et **React**, et simplifie l’activation du reCAPTCHA dans n’importe quel formulaire.
|
||
|
||
---
|
||
|
||
## 1. Installation et import
|
||
|
||
```tsx
|
||
import { RecaptchaProvider, useRecaptcha } from "@/front/providers/RecaptchaProvider";
|
||
// Ensuite, enveloppe ton formulaire avec le provider :
|
||
<RecaptchaProvider>
|
||
<MonFormulaire />
|
||
</RecaptchaProvider>
|
||
|
||
// Tu peux être plus propre et entourer tout ton Applayout, ce qui évite d'encapsuler chaque formulaire
|
||
<RecaptchaProvider>
|
||
{children}
|
||
</RecaptchaProvider>
|
||
```
|
||
|
||
## 2. Fonctionnement général
|
||
|
||
Le provider expose :
|
||
|
||
- `enabled` : `boolean` indiquant si le reCAPTCHA est activé (cookie accepté).
|
||
- `getToken()` : fonction pour récupérer le token généré par Google reCAPTCHA.
|
||
- `formRef` : référence vers le `<form>` HTML, utilisée pour injecter le conteneur reCAPTCHA et désactiver le formulaire si nécessaire.
|
||
|
||
### 2.1 Gestion automatique des cookies
|
||
|
||
Le provider utilise le hook `useCookieNotice` pour vérifier si l’utilisateur a accepté le service RECAPTCHA.
|
||
|
||
- Si accepté → le reCAPTCHA est initialisé sur le formulaire.
|
||
- Si non accepté → le formulaire reste inert, empêchant toute interaction jusqu’à ce que l’utilisateur donne son consentement.
|
||
|
||
### 2.2 Injection du formulaire
|
||
|
||
Le provider utilise `InitRecaptcha([formRef.current])` pour :
|
||
|
||
- Créer un `<div class="g-recaptcha">` dans le formulaire.
|
||
- Charger le script Google reCAPTCHA de manière asynchrone.
|
||
- Gérer le reset du reCAPTCHA si nécessaire.
|
||
|
||
### 2.3 Désactivation du formulaire
|
||
|
||
Le formulaire est automatiquement rendu `inert` tant que le reCAPTCHA n’est pas actif. Cela empêche les utilisateurs d’envoyer le formulaire avant d’avoir accepté les cookies.
|
||
|
||
## 3. Utilisation du hook useRecaptcha
|
||
|
||
Dans un composant enfant du provider, tu peux accéder au contexte avec :
|
||
|
||
```tsx
|
||
const { enabled, getToken, formRef } = useRecaptcha();
|
||
```
|
||
|
||
Exemples :
|
||
|
||
- Vérifier si le reCAPTCHA est activé :
|
||
|
||
```tsx
|
||
if (!enabled) {
|
||
console.log("Le reCAPTCHA n'est pas actif");
|
||
}
|
||
```
|
||
|
||
- Récupérer le token au moment du submit :
|
||
|
||
```tsx
|
||
const token = getToken();
|
||
data["g-recaptcha-response"] = token;
|
||
post(route('contact.submit'), { data });
|
||
```
|
||
|
||
- Associer formRef à un `<form>` :
|
||
|
||
```tsx
|
||
<form ref={formRef} data-recaptcha-key={recaptchaKey}>
|
||
...
|
||
</form>
|
||
```
|
||
|
||
## 4. Exemple complet avec Inertia
|
||
|
||
```tsx
|
||
<RecaptchaProvider>
|
||
<RecaptchaForm
|
||
data={formData}
|
||
onSubmit={(e) => post(route("contact.submit"), { data: formData })}
|
||
>
|
||
<input name="email" value={formData.email} onChange={e => setFormData("email", e.target.value)} />
|
||
<textarea name="message" value={formData.message} onChange={e => setFormData("message", e.target.value)} />
|
||
<button type="submit">Envoyer</button>
|
||
</RecaptchaForm>
|
||
</RecaptchaProvider>
|
||
```
|
||
- Le formulaire est désactivé automatiquement si l’utilisateur n’a pas accepté le reCAPTCHA.
|
||
- Le token reCAPTCHA est injecté automatiquement au moment du submit.
|
||
- La logique de cookie consent est gérée sans code supplémentaire.
|
||
|
||
## 5. RecaptchaForm : comment ça fonctionne
|
||
|
||
Le composant `RecaptchaForm` est un wrapper de formulaire qui gère le reCAPTCHA et l’état inert.
|
||
|
||
- `onSubmit` : callback déclenché lorsque le formulaire est soumis et que le reCAPTCHA est actif.
|
||
- `data` : objet contenant les données du formulaire, incluant `g-recaptcha-response`.
|
||
- `children` : champs du formulaire.
|
||
- `banner` : optionnel, permet d’afficher un message si le reCAPTCHA n’est pas encore activé.
|
||
|
||
#### Fonctionnalités clés
|
||
|
||
- Inert automatiquement : le formulaire est bloqué tant que le consentement n’est pas donné.
|
||
- Token automatique : le token reCAPTCHA est récupéré et injecté dans `data["g-recaptcha-response"]`.
|
||
- Notification de cookie : un banner s’affiche pour informer l’utilisateur et lui permettre d’accepter le service.
|
||
|
||
## 6. Avantages du `RecaptchaProvider`
|
||
|
||
- Séparation claire des responsabilités : le provider gère uniquement l’état du reCAPTCHA et des cookies.
|
||
- Réutilisable : peut encapsuler plusieurs formulaires ou pages sans dupliquer le code.
|
||
- Sécurité : empêche toute soumission tant que le consentement n’est pas donné.
|
||
- Intégration simple avec Inertia.js : compatible avec `useForm()` et `usePage()`.
|
||
- Flexible : expose `formRef` pour un contrôle direct du `<form>`.
|
||
|
||
## 7. Bonnes pratiques
|
||
- Toujours placer les formulaires à l’intérieur du `RecaptchaProvider`.
|
||
- Ne pas appeler `getToken()` en dehors du submit pour éviter des tokens invalides.
|
||
- Utiliser le champ `data-recaptcha-key` sur le `<form>` pour que InitRecaptcha puisse initialiser correctement le reCAPTCHA.
|