Theme App Extension Setup

This guide explains how to enable and configure each VerifyHuman widget through the Shopify theme editor. No code editing is required — everything is managed through the theme editor UI.

Overview: App Embeds vs App Blocks

Shopify theme extensions come in two forms:

Understanding this distinction is important:

• App Embeds appear in the theme editor sidebar under "App embeds" and work across your entire store when enabled.
• App Blocks do not appear in the App Embeds panel. You add them by clicking + Add block inside a section on the page where you want them.

Enabling App Embeds

How to Access App Embeds

1. From your Shopify admin, go to Online Store > Themes.
2. Click Customize on your active theme.
3. In the theme editor, look at the left sidebar.
4. Scroll down and click App embeds (it may appear at the bottom of the sidebar, or under a gear/settings icon depending on your theme).
5. You will see the available VerifyHuman embeds listed. Toggle each one on or off.
6. Click Save after making changes.

Age Gate (App Embed)

Name in theme editor: VerifyHuman — Age Gate

This embed adds a full-page age verification overlay to your store. Visitors must confirm their age (and optionally complete selfie verification) before accessing content.

Settings

Trigger Modes

The Apply Age Gate To setting controls where the age gate appears:

• Entire Store (All Pages) — Every page on your store shows the age gate.
• Products with Specific Tag — Only product pages where the product has the configured tag (default: age-restricted). Tags are case-insensitive.
• Collections with Specific Tag — Collection pages and product pages within tagged collections.
• Specific Page Handles — Only pages whose handle matches the comma-separated list (e.g., about-us, contact).

Human Check (App Embed)

Name in theme editor: VerifyHuman — Human Check

This embed adds bot detection to forms across your store. It loads the verification widget on pages that contain forms you want to protect.

Settings

At least one form protection option must be enabled for the widget to load.

Advanced: Custom Form Selectors

If your theme uses custom form IDs or classes that differ from standard Shopify themes, you can override the default CSS selectors:

Only change these if the widget is not detecting your theme's forms. Use comma-separated CSS selectors.

Checkout ID (App Embed)

Name in theme editor: VerifyHuman — Checkout ID

This embed intercepts the checkout process and requires identity verification before customers can complete their purchase. It works with standard checkout as well as accelerated checkout methods (Shop Pay, Apple Pay, Google Pay) when combined with the cart checkout validation function extension.

Settings

How It Detects Restricted Products

The checkout guard checks each item in the cart using two methods:

1. Product metafield: verifyhuman.requires_idv set to true
2. Product tag: The tag configured in settings (default: vh_requires_idv)

If any item in the cart matches either condition (or if "Require for All Checkouts" is enabled), the verification dialog appears.

Returning Customer Verification

For logged-in customers, the widget checks:

• customer.metafields.verifyhuman.identity_verified — whether the customer has been verified
• customer.metafields.verifyhuman.identity_expires_at — when the verification expires

If a customer is already verified and the verification has not expired, they can proceed to checkout without re-verifying.

Adding App Blocks

Identity Verification (App Block)

Name in theme editor: Identity Verification

This block renders a verification button that customers click to start the identity verification flow. Unlike app embeds, you place this block exactly where you want it to appear — on a product page, a custom page, or any section that supports app blocks.

How to Add the Block

1. From your Shopify admin, go to Online Store > Themes > Customize.
2. In the theme editor, navigate to the page template where you want the verification button (e.g., a product page).
3. Find the section where you want to place the button.
4. Click + Add block within that section.
5. In the block picker, look under Apps for Identity Verification.
6. Click it to add it to the section.
7. Configure the block settings as needed.
8. Click Save.

Settings

Common Placement Scenarios

• Product pages: Add the block to the product information section so customers verify before purchasing.
• Cart page: Add the block above or below the cart contents.
• Custom landing page: Add the block to any section on a custom page template.

Verifying Your Setup

After enabling widgets:

1. Open your storefront in a private/incognito browser window (to avoid cached states).
2. Check that the enabled features appear as expected:
   • Age Gate: A full-page overlay should block access until age is confirmed.
   • Human Check: Forms should show verification before submission.
   • Identity Verification block: The verification button should appear where you placed it.
   • Checkout ID: The verification dialog should appear when proceeding to checkout with restricted items.
3. Open your browser's developer console (F12) and check for any [VerifyHuman] messages.

Common Issues

"App URL metafield not set" warning in console

The shop metafield verifyhuman.app_url has not been configured. This is set automatically when the app is installed and settings are saved. Try saving your settings from the VerifyHuman dashboard, or reinstall the app.

Widgets not appearing in theme editor

• Ensure the Theme App Extension is deployed. Contact VerifyHuman support if the extension does not appear.
• Remember that Identity Verification is an App Block, not an App Embed. It will not appear in the App Embeds panel. Navigate to a page template and click + Add block to find it under Apps.

Age gate not triggering on specific products

• Confirm the trigger mode is set to "Products with Specific Tag" (not "Entire Store").
• Verify the product has the exact tag specified in the settings (default: age-restricted).
• Tags are case-insensitive, but must otherwise match exactly.

Human Check not detecting forms

• Enable Debug Mode in the Human Check settings to see console logs about form detection.
• If your theme uses non-standard form markup, enter custom CSS selectors in the Advanced section.

Next Steps

• Installation Guide — Full installation walkthrough
• Age Gate — Detailed age verification configuration
• Identity Verification — KYC and checkout guard details
• Human Verification — Bot protection configuration
• Settings Reference — Complete list of all settings
• Testing Your Setup — Step-by-step validation
• Troubleshooting — Common issues and solutions