# XYZ Age Verification — Installation Guide

Everything you need to go from plugin download to a working age gate on your WordPress site.

## Before You Begin

Make sure you have the following ready:

- **WordPress 5.6 or higher** running on your server
- **PHP 7.4 or higher**
- **HTTPS enabled** on your site (required for secure cookies and the verification API)
- **Cloudflare proxying** enabled for your domain (free plan or higher) — this provides the geo detection headers the plugin depends on. See the [Cloudflare Setup Guide](02-cloudflare-setup.md) if you haven't configured Cloudflare yet.
- **FTP or file manager access** to your WordPress installation (needed for the MU plugin step)

## Step 1: Install the Plugin

### Option A: Upload via WordPress Admin

1. Download the `xyz-age-verification-free.zip` file.
2. In your WordPress admin, go to **Plugins > Add New > Upload Plugin**.
3. Choose the ZIP file and click **Install Now**.
4. Click **Activate Plugin**.

### Option B: Manual Upload

1. Unzip `xyz-age-verification-free.zip` to get the `xyz-age-verification-free` folder.
2. Upload the entire folder to `/wp-content/plugins/` on your server.
3. In your WordPress admin, go to **Plugins** and activate **XYZ Age Verification**.

## Step 2: Get Your API Key

You have two options:

### Option A: Register from the Plugin (Recommended)

1. Go to **Settings > Age Verification**.
2. Under "Get Started with a Free Plan," enter your email address.
3. Click **Start Free Plan**.
4. Check your email for a confirmation link — click it to activate your key.
5. **Important:** Your API key is shown only once on the confirmation page. Copy it immediately and save it somewhere safe. It cannot be retrieved later.
6. Enter the API key in the **API Key** field on the settings page.

### Option B: Sign Up at xyzinc.com

1. Visit [xyzinc.com/wordpress-plugin](https://www.xyzinc.com/wordpress-plugin) to register.
2. Enter the API key you receive in the settings page.

## Step 3: Configure the Cookie Signing Key

1. On the **Settings > Age Verification** page, find the **Cookie Signing Key** field.
2. Click **Fetch from API**.
3. The key will be automatically retrieved and saved. This key is used to cryptographically sign the verification cookie so visitors cannot forge it.

## Step 4: Create the Age Gate Page

1. In your WordPress admin, go to **Pages > Add New**.
2. Set the page title to anything you like (e.g., "Age Verification").
3. **Critical:** Set the page slug to `age-gate`. This is the URL path the MU plugin redirects to.
4. In the page content, add the shortcode: `[xyzav_age_verify]`
5. Publish the page.

To set the slug: in the block editor, open the page settings panel on the right, expand "URL" or "Permalink," and type `age-gate`.

## Step 5: Install the Must-Use Plugin

This is the most important step. The MU plugin runs on every page load before other plugins, checking whether the visitor needs to be age-verified.

1. Navigate to your plugin folder: `/wp-content/plugins/xyz-age-verification-free/mu-plugin/`
2. Copy the file `xyz-age-gate-redirect.php` to `/wp-content/mu-plugins/`
3. If the `mu-plugins` directory does not exist, create it first.

**How to do this depends on your hosting:**

- **cPanel File Manager:** Navigate to `wp-content`, create a folder named `mu-plugins` if needed, then copy the file.
- **FTP client (FileZilla, etc.):** Upload the file to `/wp-content/mu-plugins/`.
- **SSH/command line:** `cp wp-content/plugins/xyz-age-verification-free/mu-plugin/xyz-age-gate-redirect.php wp-content/mu-plugins/`
- **Plesk File Manager:** Navigate to the site's document root, then `wp-content`, create `mu-plugins` if needed, and upload.

## Step 6: Configure Your Regions

1. Go to **Settings > Free Plan** in your WordPress admin.
2. On the **Regions** tab, click **Add Region**.
3. Enter the country code (e.g., `US`, `DE`, `GB`) and optionally a state code (e.g., `TX`, `CA`).
4. Set the action to **Verify** to require age verification for visitors from that region.
5. Set the minimum age (default is 18). If you set a minimum age other than 18, Tier 2 (ID verification) will be automatically required.
6. Save the region.

See [Understanding Regions and Geographic Rules](04-regions.md) for details on how region matching works.

## Step 7: Verify Your Setup

Go back to **Settings > Age Verification** and check the **Setup Checklist**:

- **API Key:** Green checkmark if a valid key is entered
- **Cookie Signing Key:** Green checkmark if fetched successfully
- **Age-Gate Page:** Green checkmark if a page with the slug `age-gate` exists
- **MU Plugin:** Green checkmark if `xyz-age-gate-redirect.php` is installed in `mu-plugins`
- **API Status:** Green checkmark if the API is reachable

All items should show green checkmarks. If any show a red X, review the corresponding step above.

## Step 8: Test the Age Gate

1. Enable **Test Mode** in the settings.
2. Open an incognito/private browsing window (so you're not logged into WordPress).
3. Visit any page on your site with `?reg=` followed by a region you configured. For example: `https://yoursite.com/?reg=US-TX`
4. You should be redirected to the age gate page with the verification interface.
5. Complete the verification and confirm you're redirected back to the original page.

See [Test Mode — How to Test Your Age Gate](07-test-mode.md) for more testing scenarios.

## Step 9: Page Cache Configuration

If you use a page cache plugin (W3 Total Cache, WP Super Cache, etc.), exclude the `/age-gate/` page from caching. Cached pages bypass PHP execution, which would skip the age verification check on the gate page itself.

**Important:** WP Rocket is not compatible with this plugin. See [Caching Compatibility](10-caching-compatibility.md) for details.

## You're Done

Your site is now age-gated for the regions you configured. Visitors from those regions will see the verification interface before accessing your content. Logged-in WordPress users bypass the gate automatically.

Next steps:
- [Configure welcome content](06-configuring-regions.md) shown before verification
- [Understand verification tiers](03-how-verification-works.md) and when each is used
- [Monitor your credit usage](05-credits.md) on the Free Plan page