Hyvä reCAPTCHA v3 (Enterprise) Extension

Towering Media — reCAPTCHA Enterprise (Hyvä Forms) User Guide

This guide shows how to configure and confirm protection for the forms supported by our module.

Module: Toweringmedia_HyvaRecaptchaV3
Composer package: toweringmedia/hyva-recaptcha-v3
Magento Admin path: Stores → Configuration → Security → Towering Media reCAPTCHA (Enterprise)

What this module does

• Generates a reCAPTCHA Enterprise v3 token when a user submits a protected form

• Sends the token to Google’s Enterprise Assessments API server-side

• Blocks spam based on:

  • Expected Action

  • Minimum Score Threshold

  • Optional Strict Hostname Match

Quick start checklist

1. In Google Cloud: enable reCAPTCHA Enterprise API and create an Enterprise Site Key

2. In Magento Admin: set Project ID, Site Key, API Key

3. Enable the form toggles (Contact / Newsletter / Customer forms)

4. Verify the token field + Enterprise script is present in the page source

5. Run the “safe enforcement test” (submit without token)

1) Prerequisites (Google Cloud)

You’ll need three values to paste into Magento Admin:

1. Google Cloud Project ID
   Example: my-project-123 (this is the project id, not a key id)

2. reCAPTCHA Enterprise Site Key
   Often starts with 6L... (used in the browser)

3. Google Cloud API Key
   Used server-side to call the reCAPTCHA Enterprise Assessments API

In Google Cloud, ensure:

• ✅ reCAPTCHA Enterprise API is enabled

• ✅ Your Site Key is configured to allow the store domain(s)

• ⚠️ If you plan to enable Strict Hostname Match in Magento:

  • The token hostname must match the store hostname

  • Staging/dev hostnames must also be allowed (or disable strict matching there)

2) Magento Admin configuration (source of truth)

Go to:
Stores → Configuration → Security → Towering Media reCAPTCHA (Enterprise)

A) Enterprise / Essentials Settings

Fill in:

• Google Cloud Project ID

• reCAPTCHA Enterprise Site Key

• Google Cloud API Key

Recommended:

• Minimum Score Threshold: start at 0.5

• Strict Hostname Match

  • Yes for production

  • No for dev/staging unless every hostname is configured in Google Cloud

B) Protected Forms (Enablement)

Enable whichever forms you want protected:

• Enable Contact Form

• Enable Newsletter Subscribe

• Enable Customer Login

• Enable Customer Create Account

• Enable Customer Forgot Password

Each form includes an Action Name (defaults are typically correct):

• contact

• newsletter

• customer_login

• customer_create

• customer_forgot_password

3) Which forms on ToweringMedia.com are covered

Contact forms (form code: contact)

Protected endpoint:

• POST /contact/index/post/

Common protected implementations:

• Contact page (/contact)

• Homepage “Tell us about your ecommerce goals” form (submits to the same contact endpoint)

• Homepage hero/project form widget (if present)

• Header contact form (if enabled in the theme)

Newsletter subscribe (form code: newsletter)

Protected endpoint:

• POST /newsletter/subscriber/new/

Your newsletter form must include:

• id="newsletter-validate-detail"

• action="/newsletter/subscriber/new/"

• Email field: name="email"

• Hidden input: form_key

Customer forms

Protected pages:

• Login: /customer/account/login/

• Create Account: /customer/account/create/

• Forgot Password: /customer/account/forgotpassword/

4) How to verify protection is active (quick checklist)

Open the page and View Page Source (or inspect the form element). Confirm:

A) Token field is present

You should see a hidden input like:

• input name="g-recaptcha-response"

• data-tm-recaptcha-v3="1"

• data-tm-recaptcha-provider="enterprise"

• data-tm-recaptcha-action="contact" (or newsletter, etc.)

If the token field is missing, the form submits without a token and will be blocked.

B) Enterprise script is loaded

• recaptcha/enterprise.js

C) Runtime object exists

• window.tmHyvaRecaptchaV3

5) “It says enabled, but the form still fails” (common fixes)

A) Cache / stale output

If templates are being served from var/view_preprocessed, flush relevant caches after changes:

B) Domain mismatch / hostname problems

Symptoms:

• Browser console: “invalid domain for site key”

• Backend rejects tokens (hostname mismatch)

Fix options:

• Add the hostname/domain to the Site Key settings in Google Cloud
  or

• Disable Strict Hostname Match for that environment

C) Wrong field names in custom forms

If you built a custom form, ensure field names match what the controller expects.

Contact endpoint expects:

• name

• email

• telephone (not phone)

• comment

• form_key

Newsletter expects:

• email

• form_key

D) Duplicate / legacy reCAPTCHA is still running

If legacy KO/RequireJS or older v3 scripts are also injecting g-recaptcha-response:

• Keep only the Towering Media Enterprise integration

• Remove/disable old scripts that add or overwrite the token field

6) Safe validation test (proves enforcement)

Submit the form without g-recaptcha-response.

Expected result:

• Magento shows: “reCAPTCHA could not be verified. Please try again.”

That message confirms the backend enforcement is active.

7) Theme integration files (ToweringMedia.com)

Key theme files affecting these forms:

• Homepage hero contact form:
  app/design/frontend/Hyva/Toweringmedia/Magento_Cms/templates/cms-hero.phtml

• Footer newsletter form:
  app/design/frontend/Hyva/Toweringmedia/Magento_Theme/templates/html/footer.phtml

• Header contact form:
  app/design/frontend/Hyva/Toweringmedia/Magento_Contact/templates/form-header.phtml

• Contact page form:
  app/design/frontend/Hyva/Toweringmedia/Magento_Contact/templates/form.phtml

8) Adding a NEW form in the future

If your new form posts to a protected endpoint, make sure it:

• Renders the TM token field (g-recaptcha-response) for the correct form code/action

• Includes form_key

• Uses the correct parameter names expected by the endpoint

• Includes the legal notice (recommended)

If you share the URL of the new form (and which endpoint it posts to), I can provide the exact snippet to paste into the .phtml.