# Modal Integration (Overlay)
The modal (overlay) integration displays an AgeGO verification window on top of your website when age verification is required.
It allows you to protect age-restricted content without redirecting users away from your site or rebuilding your existing flow.
This approach is designed to be:
* Fast to implement
* Flexible
* Minimal impact on UX
Depending on your needs, you can choose between two integration paths.
## Option 1: Basic Web Integration (Quick Setup)
This option is recommended if you want a simple, plug-and-play integration with minimal configuration.
### How It Works
* The AgeGO modal is triggered when a user tries to access age-restricted content.
* AgeGO handles the full verification flow inside the modal.
* Once verification is completed, the user can continue browsing your site.
### Best For
* Standard implementations
* Fast go-live
* Minimal frontend customization
This option requires very little setup and is ideal if you don't need to deeply customize the user journey.
Place the snippet from Admin Panel inside the `` tag of any webpage you wish to protect:
**Example:**
```xml
```
## Option 2: Advanced Web Integration (More Control)
This option is recommended if you need more flexibility and tighter control over when and how the modal is triggered.
### How It Works
* You control when the AgeGO modal opens (for example, based on user actions, country detection, or specific pages).
* The verification still happens inside the modal, but the trigger logic is handled on your side.
* This allows you to better align age verification with your existing UX and business logic.
### Best For
* Custom user flows
* Country-based enforcement
* More advanced frontend logic
This option provides greater customization, including event handling, dynamic content, error messaging, and cookie management:
**Example:**
```xml
```
## Configuration Details
This section describes the configuration options available for the AgeGO modal.
These options apply to both Basic and Advanced integrations and allow you to control how the modal behaves, looks, and interacts with your site once it is triggered.
### General Configuration
`asi`: A unique identifier that links the AgeGO prompt to your website. You can find this value in the “My Sites” section of the AgeGO admin dashboard.
`userNonce`: A unique, single-use security value to prevent sharing of verification status between users. Defaults to `undefined`. When `undefined`, it will be generated by the prompt itself and stored in a first-party cookie.
`callbackToken`: This value is passed back to your site via the callback URL and can be used to match the verification result with your internal logic or session handling.
`autoBlur`: Controls whether the site content is automatically blurred when the modal is active.
* Defaults to `true`
* Set to `false` if you already use your own content-blocking or obfuscation method
`requireAgeVerification`: If you already use your own content-blocking or obfuscation mechanism, this option allows you to control whether AgeGO age verification is enabled. It determines whether the age-verification call to action (CTA) is displayed and whether the AgeGO verification flow is active.
* Defaults to `true`
* `true` → the age-verification CTA is shown and AgeGO verification is enabled
* `false` → the CTA is hidden and the AgeGO verification flow is disabled
### Redirect Behavior (Modal)
This section describes how users are redirected within the AgeGO modal flow.
These options control where the verification flow starts and where underage users are sent, without leaving the modal-based integration.
`underageRedirectTo`: A URL the visitor is redirected to when the I am not 18 years old CTA is pressed.
r`edirect`: The redirect parameter controls where users start their journey when the AgeGO flow begins.
* `myaccount`: When set to `myaccount`, the user is redirected to the My Account page after logging in.
* If the user is already logged in, they are taken directly to My Account.
* If the user is not logged in, they are first sent to the login page. After logging in, the flow proceeds to My Account.
* Verification logic remains unchanged:
* If the user is not verified, they are redirected to the Verification Methods page.
* If the user is verified, they proceed normally.
* `login`: When set to `login`, the user is redirected directly to the login page instead of the usual starting page of the flow. After logging in:
* If the user is not verified, they are sent to the Verification Methods page.
* If the user is verified, they continue through the standard flow.
* Default value
* If no value is provided, the user lands on the default starting page of the flow.
### Overlay Options
These options control the visual elements of the modal.
* Logo: Optional URL to a custom logo displayed inside the AgeGO modal. If not provided, the default AgeGO logo will be used.
* Theme: Controls the visual theme of the modal:
* `light`
* `dark`
* `auto` (matches the user’s system preference)
* Style: Allows you to customize the appearance of the modal, including layout and visual properties.
* Content: Lets you define custom text, such as:
* Headers
* CTA labels
* Informational text
* Messages: Custom error or system messages shown in specific edge cases, helping improve clarity for users.
### Cookie Options
ageVerifyState: A cookie used to store the user’s age-verification state.
* Default cookie name: `agego_aver`
* Stored for the duration of the user’s session
* Helps avoid repeated verification during the same visit
### Styling
You can further customize the modal using `overlay.style`. This allows you to:
* Adjust modal appearance
* Override themes
* Customize headers and CTA styles
All styling changes are purely visual and do **not** affect verification logic or security.
**Example:**
```css
{ modal: { background: '#ffffff', text: '#333333' }, header: { background: '#f8f8f8' }, ctaAgeVerify: { background: '#55a245', text: '#ffffff' }, ctaUnderageSkip: { text: '#666666' }}
```
### Prompt Content
Prompt content configuration object allows you to override labels and text content of the prompt.
**Example:**
```css
{ heading: 'Website for adults viewing only!', description: 'HTML content to display in the description box of the modal', ctaAgeVerify: { cta: 'Verify age', label: 'Continue with age verification' }, ctaUnderageSkip: { cta: 'I am not 18 years old' }}
```
### Prompt Messages
Prompt message configuration allows you to customize the messages shown to users during the age-verification flow.
These messages help explain what is happening and provide clear feedback when something goes wrong.
### Error Messages
Error messages are displayed when the verification flow cannot be completed successfully. Each message corresponds to a specific situation.
* `nonceInvalid`: Displayed when the verification session is no longer valid.
This usually happens when the security nonce used during the flow does not match the value received from AgeGO. For example, this can occur if the page is refreshed or the session is reused.
* `agegoError`: Displayed when an unexpected error occurs during the age-verification process that is not caused by the user.
This typically indicates a temporary system or service issue.
* `notVerified`: Displayed when the user has not completed age verification or is identified as underage.
This message informs the user that access cannot be granted.
* `expired`: Displayed when the age-verification callback has expired.
This is a technical error that usually occurs if the user takes too long to complete the flow or if the session times out.
* `internalError`: Displayed for other undefined technical errors.
This may include:
* Network timeouts
* Connectivity issues
* Other unexpected system errors
**Example:**
```rust
messages: { errors: { nonceInvalid: 'Internal error. Please, try again.', agegoError: 'Age verification failed. Please, try again later.', notVerified: 'Your age could not be verified. Please, try again.', expired: 'Your age verification has expired. Please, try again.', internalError: 'Failed to start age verification process - internal error. Please, try again.', }}
```
### Events
AgeGO exposes a set of events that allow you to hook into key moments of the age-verification flow.
These events can be used to update your UI, trigger analytics, or apply custom business logic.
* `onVerificationFlowEnd`: Triggered when the age-verification process is completed successfully. This event indicates that the user has been verified and can be granted access to age-restricted content.
* `onVerificationFlowFailed`: Triggered when the age-verification process does not complete successfully and the user is not verified. This can happen if the user abandons the flow or if the verification cannot be completed.
* `onAgeVerify`: Triggered when the user interacts with the age-verification call to action (CTA) to start the verification process.
* `onUnderageSkip`: Triggered when the user interacts with the “I am not 18” CTA.
* `onVerifiedBefore`: Triggered when a returning user has already been verified and no new verification is required.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.agego.com/integration/integration/modal-integration-overlay.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.