Advanced Settings

This guide covers advanced configuration options for VerifyHuman, including custom form selectors, verification thresholds, the diagnostics panel, and cart-value-based identity triggers.

Custom Form Selectors (Human Check)

When the Human Check embed cannot find your theme's forms automatically, you can supply custom CSS selectors in the Theme Editor.

Where to Configure

Go to Online Store > Themes > Customize.
Open App embeds in the left sidebar.
Click VerifyHuman - Human Check.
Scroll to Advanced: Custom Form Selectors.

How Selectors Work

Each selector field accepts one or more comma-separated CSS selectors. The widget queries the DOM for matching elements and attaches verification to the first matching form.

Field	Purpose	Example Custom Value
Signup Form Selector	Targets your theme's registration form	`#my-signup-form, .custom-register`
Reviews Form Selector	Targets product review forms (including third-party apps)	`.yotpo-form, #loox-review-form`
Contact Form Selector	Targets contact/support forms	`#custom-contact, .support-form`

When a field is left empty, the built-in default selectors are used:

Signup: #create_customer, form[action*="/account"], .customer-form, [data-customer-form]
Reviews: .product-review-form, #review-form, .spr-form, .stamped-form, .jdgm-form, [data-review-form]
Contact: #contact-form, .contact-form, form[action*="/contact"], [data-contact-form]

Tips for Finding Selectors

Open your storefront in a browser.
Right-click on the form you want to protect and choose Inspect.
Look for the form's id attribute (use #id-value) or a distinctive class (use .class-name).
Test your selector in the browser console: document.querySelector('.your-selector') should return the form element.

Debug Mode

Enable Debug Mode in the Human Check embed settings to see console logs that show:

Which selectors the widget tried
Which forms were found (or not found)
Verification attachment status

Open the browser developer console (F12) to view these logs.

Verification Level Thresholds

VerifyHuman uses a three-tier verification system. In Simple Mode, a single "Minimum Required Level" setting controls which tier is enforced.

Levels

Level	Name	What It Does
L1	Human Check	Camera-based liveness detection. Blocks bots and automated attacks.
L2	Age Verification	Verifies the customer meets the configured age threshold (18+, 21+, or 25+).
L3	Identity Verification	Full KYC: government-issued ID document + selfie facial comparison.

Level Priority

Higher levels include the security guarantees of lower levels. If a customer passes L3, they implicitly satisfy L2 and L1 as well.

How the Level Is Computed

In Simple Mode, the computation follows this logic:

Start with the configured Minimum Required Level.
If a High-Value Cart Threshold is set and the cart total meets or exceeds it, upgrade to L3 (if not already L3).
Return the final level along with the age threshold.

In Advanced Mode, the level is determined per-product based on which features are enabled and whether products carry the appropriate tags or metafields:

If Identity Verification is enabled and the cart contains identity-restricted items, require L3.
Otherwise, if Age Verification is enabled and the cart contains age-restricted items, require L2.
Otherwise, if Human Verification is enabled, require L1.

High-Value Cart Threshold

The cart threshold is an automatic upgrade mechanism that requires L3 Identity Verification for large orders, even if the products themselves are not individually restricted.

Configuration

Dashboard location: Settings > Verification Mode > Simple Mode > High-Value Cart Threshold
Field type: Currency amount (USD)
Default: Disabled (empty)

Behavior

Cart Total	Threshold Setting	Result
$150	$500	No upgrade; normal minimum level applies
$600	$500	Automatically requires L3 Identity Verification
$500	$500	Triggers at exactly the threshold

Use Cases

Luxury goods: Set a threshold (e.g., $1,000) to require identity verification for high-value purchases, reducing fraud and chargebacks.
Wholesale prevention: Prevent bulk purchasing by requiring identity verification above a certain cart total.
Regulatory compliance: Some jurisdictions require enhanced verification for transactions above certain amounts.

Restricted Product Detection

VerifyHuman detects restricted products using two methods, configured to work together or independently.

Detection Methods

Method	How to Apply	Checked By
Product Tag	Add the tag `vh_requires_idv` to any product in Shopify Admin	Theme extension Liquid templates and checkout validation
Product Metafield	Set `verifyhuman.requires_idv` = `true` on the product	Theme extension Liquid templates and server-side logic
Collection Metafield	Set `verifyhuman.requires_idv` = `true` on a collection	Server-side detection when collection data is available

Detection Mode

The server-side detection supports three modes:

Mode	Behavior
`both` (default)	Checks both metafields and tags
`metafields_only`	Only checks product/collection metafields
`tags_only`	Only checks product tags

Accepted Metafield Values

The following values are treated as "restricted": true, 1, yes (case-insensitive).

Age Gate Trigger Modes (Theme Editor)

The age gate embed supports four trigger modes, configured in the Theme Editor:

Mode	Setting Value	Behavior
Entire Store	`all_pages`	Every page shows the age gate overlay.
Product Tag	`product_tag`	Only product pages where the product has the configured tag (default: `age-restricted`).
Collection Tag	`collection_tag`	Collection pages and product pages where the product belongs to a tagged collection.
Specific Pages	`specific_pages`	Only pages matching the comma-separated list of page handles.

Tag Matching

All tag comparisons are case-insensitive. The tag Age-Restricted matches the setting value age-restricted.

System Diagnostics

The diagnostics panel on the Settings page provides a real-time health check of your VerifyHuman installation.

Checks Performed

Check	Pass Condition	Common Failure Cause
App Installation	Shop record exists and `isActive = true`	App was uninstalled or database record is missing
API Key	An encrypted API key is stored	No API key entered in Settings or onboarding
Theme Metafield	Shop metafield `verifyhuman.app_url` is set and points to the correct app URL	App URL changed (e.g., after redeployment) or metafield was never created
Feature Settings	At least one verification feature (age gate, identity, or human check) is enabled	All features are disabled

Repair Metafield

If the Theme Metafield check shows a failure or warning, use the Repair Metafield button. This sends a request to the server that:

Determines the current app URL from the environment.
Creates or updates the verifyhuman.app_url shop metafield via the Shopify Admin API.
Re-runs diagnostics to confirm the fix.

After repair, all theme extension widgets will be able to reach the app backend.

When to Run Diagnostics

After initial installation
After changing the app's hosting URL or domain
If widgets stop loading on the storefront
After re-enabling the app following an uninstall/reinstall

Session and Verification Persistence

Age Gate Sessions

Mode	Storage	Duration	Scope
Guest	Browser session (cookie/localStorage)	Configurable: 1 hour to 1 week	Per browser
Profile	Customer metafield	Until cleared or customer re-verifies	Per customer account

Identity Verification Reuse

Successful identity verifications can be reused for a configurable period (1-365 days, default 30). This is stored as:

Logged-in customers: Customer metafield verifyhuman.identity_verified with expiration in verifyhuman.identity_expires_at
Guest customers: Cart attributes with a verification token

Verification Token Flow

For guest customers who verify their identity:

Customer completes verification on the cart page.
A verification token is stored in cart attributes.
The Shopify Checkout Validation function reads the token and validates it server-side.
If valid, checkout proceeds. If invalid or missing, checkout is blocked with an error.

Express Checkout Button Handling

When identity verification is required and Hide Express Checkout Buttons is enabled (default), the checkout identity widget:

Hides Shop Pay, Apple Pay, and Google Pay buttons on the cart page.
Shows a verification CTA in their place.
After successful verification, restores the express checkout buttons and shows a verified badge.

This prevents customers from bypassing identity verification through accelerated checkout flows.

Privacy and Compliance Settings

Privacy Policy URL

Set during onboarding (Step 4) or directly in the database. When configured, verification overlays link to your store's privacy policy instead of the default VerifyHuman privacy page.

Privacy Disclosures

All verification widgets display a privacy micro-notice:

"Your privacy is protected. We use your image and ID only to complete this verification and do not store personal identity data."

The full privacy notice (accessible via "Learn more") covers:

Purpose of verification
Real-time processing of images and documents
Data retention: images are not stored; only the verification result is retained
Consent acknowledgment

Data Retention Summary

Data Type	Retention
Images / Selfies	Processed in real-time, not stored
ID Documents	Processed for verification only, not retained
Verification Result	Stored for the configured reuse duration

Environment Variables (Server)

These environment variables affect advanced behavior and are typically only relevant for development or Shopify app review:

Variable	Description
`VERIFYHUMAN_TEST_MODE`	Set to `true` to enable test mode for the reviewer shop.
`TEST_SHOP_DOMAIN`	The `myshopify.com` domain of the Shopify reviewer's test store.
`VERIFYHUMAN_TEST_API_KEY`	A test API key used when test mode is active.

When test mode is active for the configured shop domain, the app uses the test API key instead of the shop's stored key, and responses include test_mode: true metadata.

See Reviewer Test Mode for details.