# Geolocation Targeting

Convert Plus integrates MaxMind GeoLite2 to enable country-based targeting for campaigns. This allows styles to be shown (or hidden) based on the visitor's country.

## How It Works

1. The site admin provides a MaxMind license key in the plugin settings
2. The GeoLite2-Country database (`.mmdb`) is downloaded to the WordPress uploads folder
3. When a visitor loads a page, their IP address is looked up in the local database
4. The resolved country code is used to evaluate targeting rules set on each style

## Class: `Convert_Plug_Maxmind_Geolocation`

**File:** `classes/class-convert-plug-maxmind-geolocation.php`

Handles database path management and configuration.

### Constants

| Constant | Value |
|----------|-------|
| `DATABASE` | `GeoLite2-Country` |
| `DATABASE_EXTENSION` | `.mmdb` |

### Key Methods

#### `get_cplus_database_path()`
Returns the full path to the GeoLite2 database file:

```
{wp_uploads}/convertplus_uploads/{prefix}GeoLite2-Country.mmdb
```

The `{prefix}` is a random 32-character string generated on first activation and stored in `convertplus_maxmind_geolocation_settings['database_prefix']`.

### WordPress Option: `convertplus_maxmind_geolocation_settings`

| Key | Description |
|-----|-------------|
| `database_prefix` | Randomly generated 32-char string used in the database filename (security through obscurity) |
| `license_key` | MaxMind account license key (entered by site admin) |

## Database Storage Location

```
{wp-content}/uploads/convertplus_uploads/{prefix}GeoLite2-Country.mmdb
```

The directory is created/verified on plugin activation and on version upgrade by `create_cplus_maxmind_folder_on_activation()`.

## Downloading / Updating the Database

The MaxMind database is downloaded via the admin panel.

**AJAX action:** `cplus_maxmind`
**Handler:** `cplus_maxmind()` in `admin/ajax-actions.php`

This downloads the latest GeoLite2-Country database from MaxMind using the stored license key and saves it to the uploads directory. The download URL requires a valid MaxMind license key.

## Integration Class: `Convert_Plug_Geolite_Integration_Target`

**File:** `framework/class-cp-geolite-integration-target.php`

Handles the lookup logic — accepts a visitor IP address and queries the local `.mmdb` database to return the ISO country code.

## Targeting Class: `Convert_Plug_Geolocation_Target`

**File:** `framework/class-cp-geolocation-target.php`

Evaluates whether a visitor's country matches the targeting rules configured for a style (include/exclude country lists).

## Setting Up Geolocation

1. Obtain a free MaxMind license key from [maxmind.com](https://www.maxmind.com/en/geolite2/signup)
2. Go to **WP Admin > Convert Plus > Settings**
3. Enter the MaxMind license key
4. Click "Download Database" (triggers the `cplus_maxmind` AJAX action)
5. Verify the database file exists at `wp-content/uploads/convertplus_uploads/`

## Using Country Targeting in a Style

When editing a style (modal/slide-in/info bar) in the customizer:

1. Open the **Targeting** settings
2. Under "Geolocation", select countries to include or exclude
3. Save the style

Country targeting is evaluated server-side on page load before the style's JS payload is rendered.

## PharData Dependency

MaxMind database downloads come as `.tar.gz` archives. Convert Plus uses PHP's `PharData` extension to extract them. If `PharData` is not available on the server, an admin notice is shown.

The notice is controlled by the `cp_show_phardata_notice` option and can be dismissed by the `cp_dismiss_phardata_notice` AJAX action.

## Related Pages

- [Module System](Module-System)
- [Environment Configuration](Environment-Configuration)
- [Troubleshooting FAQ](Troubleshooting-FAQ)