> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wisepilot.app/llms.txt
> Use this file to discover all available pages before exploring further.

# WordPress Plugin

> Install, activate, and configure the WisePilot WordPress plugin for attribution tracking and CTA event delivery.

The WisePilot WordPress plugin (v3.0+) is the recommended way to deploy attribution tracking and CTA event collection on your site. It replaces the previous GTM-dependent setup with a single plugin that handles everything.

## What the Plugin Does

| Feature                 | Description                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| **Attribution cookie**  | Generates and persists `cr_attrib` UUID (90-day expiry)                                    |
| **CTA link rewriting**  | Appends `cr_attrib` + UTMs to all CTA destination links                                    |
| **CTA view tracking**   | IntersectionObserver fires when CTA is 50% visible                                         |
| **CTA click tracking**  | Event delegation captures clicks on `[data-cta-id]` elements                               |
| **Event delivery**      | Posts events directly to WisePilot API (no GTM needed)                                     |
| **GA4 dual-write**      | Fires `cta_view`/`cta_click` as GA4 custom events if gtag is present                       |
| **GHL form injection**  | Injects hidden `cr_attrib` field into HighLevel forms                                      |
| **GHL iframe handling** | Appends `cr_attrib` to HighLevel iframe src URLs                                           |
| **RankMath SEO**        | Exposes `rank_math_title`, `rank_math_description`, `rank_math_focus_keyword` via REST API |
| **ACF CTA fields**      | Auto-creates missing CTA field groups on activation                                        |

## Installation

### Step 1: Download

1. In WisePilot, go to **Integrations -> WordPress**
2. Click **Download Plugin**
3. This generates a ZIP file with your site's configuration

<Note>A tracking token is automatically generated when you download the plugin. This token authenticates event delivery from your site.</Note>

### Step 2: Install

1. In WordPress admin, go to **Plugins -> Add New -> Upload Plugin**
2. Choose the downloaded ZIP file
3. Click **Install Now**, then **Activate**

### Step 3: Connect

When you connect your WordPress site in WisePilot, the app automatically configures the plugin by calling `POST /wp-json/cr/v1/configure` on your site. This sets:

* Website ID
* Events URL
* Tracking token

No manual configuration is needed.

### Step 4: Verify

1. Visit any page on your site
2. **View page source** — search for `crConfig`. You should see:
   ```javascript theme={null}
   var crConfig = {"websiteId":"your-uuid","eventsUrl":"https://...","trackingToken":"crtkn_..."};
   ```
3. **Check Network tab** — scroll to a CTA and verify a POST to `/api/integrations/cr/events` fires
4. **Console check** — run `window.getAttributionId()` to verify the attribution cookie exists

## CTA Requirements

For the plugin to track CTA views and clicks, your CTA elements need the `data-cta-id` attribute:

```html theme={null}
<div data-cta-id="your-cta-uuid"
     data-cta-position="abtf"
     data-asset-content-id="CNT-123">
  <a href="https://your-booking-page.com">Book a Call</a>
</div>
```

| Attribute               | Required | Description                                                      |
| ----------------------- | -------- | ---------------------------------------------------------------- |
| `data-cta-id`           | Yes      | Unique CTA identifier                                            |
| `data-cta-position`     | No       | Position code: `abtf`, `exit`, `footer`, `sidebar`, `in_content` |
| `data-asset-content-id` | No       | Content ID of the page (`CNT-xxx`)                               |

## Event Batching

* **CTA views** are batched with a 1-second debounce (up to 50 per batch)
* **CTA clicks** flush immediately (before navigation)
* Events are flushed on page unload (`visibilitychange` / `pagehide`)
* Delivery uses `navigator.sendBeacon()` with `fetch()` fallback

## View Deduplication

CTA view events are automatically deduplicated per browser session. If a user scrolls past the same CTA multiple times on the same page, or refreshes the page, only one view event is recorded per CTA per session.

Click events are **not** deduplicated — each click represents an intentional user action and is tracked individually.

## CTA ID Formats

The `data-cta-id` attribute supports two formats:

* **UUID** — The internal WisePilot CTA ID (used when CTAs are published from WisePilot)
* **ACF CTA ID** — WordPress ACF field IDs like `cta_footer_1558` (used when CTAs are managed via ACF)

Both formats are accepted. ACF CTA IDs are automatically resolved to the internal UUID on the server side.

## GA4 Integration

If GA4 is installed on your site (i.e., `window.gtag` is available), the plugin automatically fires custom events:

* `cta_view` with parameters: `cta_id`, `cta_position`, `page_path`, `attribution_id`
* `cta_click` with same parameters

No configuration needed. Events appear in GA4 DebugView immediately and in standard reports after 24-48 hours.

To see CTA data in GA4 reports, register these as Custom Definitions:

1. Go to GA4 -> Admin -> Custom Definitions
2. Add `cta_id` as an Event parameter
3. Add `cta_position` as an Event parameter

## Manual Configuration (Advanced)

If auto-configuration doesn't work (e.g., WordPress REST API is restricted), you can set config values manually:

### Option A: wp-config.php

```php theme={null}
define('CR_WEBSITE_ID', 'your-website-uuid');
define('CR_EVENTS_URL', 'https://app.contentregistry.com');
define('CR_TRACKING_TOKEN', 'crtkn_your_token');
```

### Option B: WP-CLI

```bash theme={null}
wp option update cr_website_id "your-website-uuid"
wp option update cr_events_url "https://app.contentregistry.com"
wp option update cr_tracking_token "crtkn_your_token"
```

## Plugin REST Endpoints

The plugin registers two REST endpoints:

| Endpoint                   | Method | Auth  | Description                                                |
| -------------------------- | ------ | ----- | ---------------------------------------------------------- |
| `/wp-json/cr/v1/configure` | POST   | Admin | Sets `cr_website_id`, `cr_events_url`, `cr_tracking_token` |
| `/wp-json/cr/v1/status`    | GET    | Admin | Returns plugin version, config status                      |

## Troubleshooting

### crConfig is empty

* Plugin is activated but not yet connected. Go to **Integrations -> WordPress** in WisePilot and connect your site.
* Or set values manually (see Manual Configuration above).

### Events not arriving

* Check browser Network tab for POST requests to the events URL
* Verify the tracking token is valid (matches `wordpress_config.tracking_token` in WisePilot)
* Check for CORS errors — the origin must match your `wordpress_config.site_url`

### Events arrive but CTA data shows zero

* If using ACF-managed CTAs, ensure your CTAs have been synced to WisePilot so the ACF CTA ID (e.g. `cta_footer_1558`) can be resolved to the internal UUID. Unmatched ACF IDs are stored with `cta_id: null`.

### Upgrading from v2.x

1. Deactivate and delete the old plugin
2. Download and install v3.0 from WisePilot
3. Connect your site to auto-configure
4. Remove any GTM CTA tracking tags (no longer needed)
5. Existing tracking data is preserved — new events use `cr_plugin` source