> For the complete documentation index, see [llms.txt](https://documentation.ajaxsearchpro.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ajaxsearchpro.com/analytics-integration.md).

# Google Analytics Integration (GA4)

### What is Analytics? <a href="#what-is-analytics" id="what-is-analytics"></a>

The **Analytics** menu lets you send **search interaction events to Google Analytics 4 (GA4)** or **Google Tag Manager (GTM)**.

Ajax Search Pro doesn't replace your analytics tool; it *feeds* it. You define **which moments** (triggers) you care about and **what event** to send for each, and the plugin fires those events on the frontend through your already-installed GA4/GTM tracker.

You'll find it under **Ajax Search Pro → Analytics** in the WordPress admin menu.

<figure><img src="/files/fwJRp9Ei8XhtHCJ0kFGt" alt=""><figcaption></figcaption></figure>

#### Requirements <a href="#requirements" id="requirements"></a>

* A **GA4 or GTM tracker must already be installed** on your site (via your theme, a plugin, or manually). Ajax Search Pro sends events through that tracker — it does not install one for you.
* Under the hood it uses the standard `gtag()` function when available (GA4), and otherwise falls back to pushing to the GTM `dataLayer`.

***

### Settings <a href="#settings" id="settings"></a>

#### Event tracking enabled <a href="#event-tracking-enabled" id="event-tracking-enabled"></a>

The master switch. Turn this **on** to start sending search events; when it's off, no events are sent and the event configuration is hidden.

<figure><img src="/files/jaI8z1NUlDy7oaMPEEKt" alt=""><figcaption></figcaption></figure>

#### Tracking ID (optional) <a href="#tracking-id-optional" id="tracking-id-optional"></a>

* **Leave empty** to send events through the **globally installed GA/GTM tracker** on your site (the usual setup).
* **Provide a `G-XXXXXXXX` ID** to send events to a **specific GA4 property**. The plugin adds this as the `send_to` target on each event, so you can route search events to a property that's different from your site-wide one.

<figure><img src="/files/JEXKQ3MCNlSrKaN5sLVu" alt=""><figcaption></figcaption></figure>

***

### Triggers <a href="#triggers" id="triggers"></a>

A **trigger** is a moment during a search when events can fire. Each trigger can have **one or more events** configured, and each event fires independently when that trigger occurs. The eight available triggers are:

| Trigger                      | Fires when…                                                |
| ---------------------------- | ---------------------------------------------------------- |
| **Input focus**              | the user clicks into the search input field.               |
| **Search start**             | the live search request begins.                            |
| **Search end**               | the live search results are displayed.                     |
| **Magnifier click**          | the user clicks the magnifier icon.                        |
| **Enter / Return key**       | the user presses Enter in the search input.                |
| **"Try this" keyword click** | the user clicks one of the "try this" keyword suggestions. |
| **Filter change**            | the user changes a frontend filter option.                 |
| **Result click**             | the user clicks on a search result.                        |

***

### Configuring an event <a href="#configuring-an-event" id="configuring-an-event"></a>

Under each trigger, click **Add event** to create an event. Each event has:

* **Active toggle** — enable or disable this individual event without deleting it.
* **Event name** — a label *for your own reference* in the admin (e.g. "Track search phrase"). This is required but is not sent to GA.
* **Event action** — **the GA4 event name that is actually sent** (e.g. `search_start`). Required. Must start with a letter and contain only letters, numbers and underscores — **no spaces**.
* **Parameters** — optional key/value pairs sent with the event (e.g. `event_category` → `site search`). Parameter names follow the same naming rule (letter first, then letters/numbers/ underscores). Parameter **values** can be literal text or **template variables** (see below), and must not be empty.

Expand an event row to edit its action and parameters; collapse it to keep the list tidy. Use the trash icon to remove an event (it asks for confirmation).

<figure><img src="/files/wgbif50eMLvmatXvwwx8" alt=""><figcaption></figcaption></figure>

#### Template variables <a href="#template-variables" id="template-variables"></a>

In parameter **values**, use template variables in curly braces — the plugin replaces them with live data at the moment the event fires. Some variables are available everywhere; others only make sense for certain triggers and are offered per trigger:

| Variable          | Available on  | Replaced with                          |
| ----------------- | ------------- | -------------------------------------- |
| `{phrase}`        | all triggers  | the current search phrase              |
| `{search_id}`     | all triggers  | the search instance ID                 |
| `{search_name}`   | all triggers  | the search instance name               |
| `{results_count}` | Search end    | the number of results displayed        |
| `{option_label}`  | Filter change | the label of the changed filter option |
| `{option_value}`  | Filter change | the value of the changed filter option |
| `{result_title}`  | Result click  | the title of the clicked result        |
| `{result_url}`    | Result click  | the URL of the clicked result          |

The variables you can use are listed right under the **Parameters** field for the trigger you're editing.

**Example** — on the **Search end** trigger, an event with action `view_search_results` and a parameter `search_term` → `{phrase}` plus `count` → `{results_count}` will send, when results appear:

```
gtag('event', 'view_search_results', { search_term: 'bluetooth speaker', count: '12' });
```

***

### How events are sent <a href="#how-events-are-sent" id="how-events-are-sent"></a>

When a configured trigger fires, for each **active** event on it, the plugin:

1. Builds the parameter set, substituting any `{variables}` with live values.
2. Sends it via **`gtag('event', <action>, <params>)`** if `gtag` is available (GA4). If a **Tracking ID** is set, the event is routed to that property via `send_to`.
3. If `gtag` isn't present but a GTM **`dataLayer`** is, it instead pushes `{ event: 'gaEvent', eventAction: <action>, ...params }` so you can pick it up with a GTM trigger.

If neither `gtag` nor `dataLayer` exists on the page, nothing is sent.

***

### Reset to defaults <a href="#reset-to-defaults" id="reset-to-defaults"></a>

The **Reset to defaults** button (next to Save) clears the analytics configuration back to its defaults — **all configured events are removed**. It asks for confirmation first.

<div><figure><img src="/files/3hcGDbxzHRnR69vL5sCG" alt="" width="375"><figcaption></figcaption></figure> <figure><img src="/files/z43l8RmjClaQIM8oVpoF" alt="" width="375"><figcaption></figcaption></figure></div>

***

### Tips & notes <a href="#tips--notes" id="tips--notes"></a>

* **Remember to Save.** Changes aren't applied until you click **Save** — the panel warns you if you try to leave with unsaved changes.
* **Keep event actions consistent.** Use the same `action` name (e.g. `search`) across triggers if you want them grouped together in GA4 reports, and distinguish them with parameters.
* **GTM users:** listen for the `gaEvent` dataLayer event and read `eventAction` plus your custom parameters in your GTM tags.
* For property setup and report building, refer to Google's own GA4 / GTM documentation; the plugin's job ends at sending the events.