How to Set Up reCAPTCHA v2 for XFile Ultra
reCAPTCHA v2 shows the classic Google “I'm not a robot” checkbox (and sometimes an image challenge) on the forms you protect. You create a key pair in Google’s admin console, then paste both keys into XFile Ultra.
Use v2 when you want a visible challenge. For a mostly invisible score-based check, use reCAPTCHA v3 instead (different key type — do not mix).
Where to find it in XFile Ultra
Admin → Settings → Settings (first / Main tab) → Captcha & abuse
1. Set Provider to reCAPTCHA v2
2. Paste reCAPTCHA v2 site key and reCAPTCHA v2 secret key
3. Under Captcha on forms, turn on the surfaces you want (contact, register, login, tickets, and so on)
4. Save settings
5. Optional: under Users & limits, enable Download captcha per tier if you also want captcha on the download page (same provider)
Fields in XFile Ultra
| Field in admin | Setting key | From Google |
|---|---|---|
| reCAPTCHA v2 site key | recaptcha_pub_key |
Site key (public) |
| reCAPTCHA v2 secret key | recaptcha_pri_key |
Secret key (server only) |
Leave the secret blank on later saves to keep the stored value. You can also set env fallbacks NEXT_PUBLIC_RECAPTCHA_SITE_KEY and RECAPTCHA_SECRET_KEY instead of (or as backup for) the admin fields.
Step 1 — Create a v2 key in Google
1. Open the Google reCAPTCHA admin
2. Sign in with a Google account
3. Click + (or Create) to register a new site
4. Label: something you will recognize (example: example.com — v2)
5. reCAPTCHA type: choose reCAPTCHA v2 → “I'm not a robot” Checkbox
- Do not pick Invisible v2 or v3 for this guide
6. Domains: add your live hostname without https:// or paths
- Example: example.com
- If you also serve www.example.com, add www.example.com (or rely on subdomain rules — safer to list both if unsure)
- For local testing, add localhost
7. Accept the terms and submit
8. Copy the Site key and Secret key
Keep the secret key private. Never put it in theme HTML or public JS.
Step 2 — Paste keys into XFile Ultra
1. Go to Admin → Settings → Settings (first / Main tab) → Captcha & abuse
2. Provider → reCAPTCHA v2
3. Paste Site key → reCAPTCHA v2 site key
4. Paste Secret key → reCAPTCHA v2 secret key
5. Enable at least one surface under Captcha on forms (example: Contact or Register)
6. Click Save settings
Step 3 — Verify it works
1. Open a private/incognito window (or log out)
2. Visit a protected form (example: /contact or /register)
3. Confirm the Google checkbox widget appears
4. Complete the checkbox and submit
5. Success → keys and domain match
6. Failure → see Common problems below
Also try submit without checking the box — the form should reject the attempt.
Domains checklist
| Add in Google | When |
|---|---|
example.com |
Apex / bare domain |
www.example.com |
If visitors use www |
| Staging host | If you test on a separate hostname |
localhost |
Local development only |
Domain list changes can take a few minutes to apply.
Common problems
Invalid site key / widget does not load
Wrong key type (v3 key used in v2 mode), typo, or domain not listed on the key. Create a new v2 checkbox key if needed.
Widget loads but every submit fails
Site key and secret are swapped, or the secret belongs to a different key. Paste again carefully.
Works on apex but not on www (or reverse)
Add the missing hostname in the Google reCAPTCHA admin for that key.
Forms still use Text / Image captcha
Provider is not set to reCAPTCHA v2, or the form toggle under Captcha on forms is off. Download-page captcha is separate under Users & limits.
Secret “disappears” after save
Normal. The password field stays empty; the server keeps the saved secret unless you type a new one.