> 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://documentation.ajaxsearchpro.com/analytics-integration.md?ask=<question>
```

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.