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

# Using The Journey Builder

> Build and publish visual user journey flows using a drag-and-drop node editor — track every step from awareness to conversion.

## Overview

The Journey Builder is a visual, node-based editor for mapping the exact steps you want visitors to take through your product. Each step is a **node** (a page view, click, scroll, form submit, or integration action). Nodes connect in sequence to form a flow, and GTM Suite tracks how many real sessions progress through each one.

Journeys require a **Desktop** screen to build and edit. Mobile access is not supported in the builder.

***

## Builder Layout

* **Canvas** — Drag-and-drop workspace; pan with click-drag, zoom with scroll
* **Toolbar** — Row of node types along the bottom; drag any onto the canvas to add a step
* **Node Config Panel** — Right sidebar; opens when a node is selected
* **MiniMap** — Small canvas overview in the top-right corner of the canvas
* **Header** — Version selector, save status, and publish/unpublish controls

***

## AIDA Stages

Every node is tagged with a **Journey Stage** that maps to the AIDA marketing framework. This classifies each step by where it falls in the buyer's progression:

| Stage         | Intent                                           |
| ------------- | ------------------------------------------------ |
| **Awareness** | Visitor discovers or views key content           |
| **Interest**  | Visitor engages — scrolls, hovers, clicks around |
| **Desire**    | Visitor shows strong buying intent               |
| **Action**    | Visitor converts — submits, signs up, purchases  |
| **Retention** | Post-conversion engagement                       |

Stage is set per-node in the configuration panel and is used for analytics segmentation.

***

## Node Types

The toolbar provides 7 node types. Drag any onto the canvas to add it as a step.

### Page View

Fires when a visitor navigates to a specific URL.

| Field        | Description                                                                          |
| ------------ | ------------------------------------------------------------------------------------ |
| **Page URL** | The URL to match. Use the URL combobox to select from known pages or type a new one. |
| **HTML ID**  | Optional precise element ID for targeted matching.                                   |

**Default AIDA stage:** Awareness

***

### Click

Fires when a visitor clicks any element matching a CSS selector.

| Field            | Description                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| **CSS Selector** | Target element selector (e.g. `.cta-button`, `#signup-link`). Use the element picker to select visually. |
| **HTML ID**      | Optional precise element ID.                                                                             |

**Default AIDA stage:** Interest

***

### Button Click

Fires when a visitor clicks a button element. A specialized version of the Click node for cleaner analytics segmentation.

| Field            | Description                                     |
| ---------------- | ----------------------------------------------- |
| **CSS Selector** | Target button selector. Use the element picker. |
| **HTML ID**      | Optional precise element ID.                    |

**Default AIDA stage:** Action

***

### Scroll

Fires when a visitor scrolls to a specified depth on the page.

| Field                | Description                                         |
| -------------------- | --------------------------------------------------- |
| **Scroll Depth (%)** | Numeric percentage (e.g. `50` for 50% of the page). |

**Default AIDA stage:** Interest

***

### Hover

Fires when a visitor hovers over an element for a sustained duration.

| Field            | Description                                      |
| ---------------- | ------------------------------------------------ |
| **CSS Selector** | Target element selector. Use the element picker. |
| **HTML ID**      | Optional precise element ID.                     |

<Note>
  Hover tracking must be enabled on the tracker snippet. It is disabled by default. See [Tracker Install](/tracker-install) for configuration.
</Note>

**Default AIDA stage:** Interest

***

### Form Submit

Fires when a visitor submits a form matching a given ID.

| Field       | Description                                                                           |
| ----------- | ------------------------------------------------------------------------------------- |
| **Form ID** | The `id` attribute of the form element. Use the element picker to select it visually. |
| **HTML ID** | Optional precise element ID.                                                          |

**Default AIDA stage:** Action

***

### Custom Event (Integration Action)

Triggers an action in a connected third-party tool when a session reaches this step. Requires an active integration.

| Field              | Description                                    |
| ------------------ | ---------------------------------------------- |
| **Provider**       | The integration to act on (see table below)    |
| **Action Type**    | The operation to perform within that provider  |
| **Field Mappings** | Map session/page data to the provider's fields |

**Supported providers and actions:**

| Provider       | Actions                                     |
| -------------- | ------------------------------------------- |
| **HubSpot**    | Create Contact, Update Contact, Create Lead |
| **Salesforce** | Create Contact, Update Contact, Create Lead |
| **Mailchimp**  | Create Contact, Send Email                  |
| **SendGrid**   | Send Email                                  |
| **Slack**      | Sync Data                                   |
| **Google Ads** | Create Campaign, Create Ad Group, Create Ad |
| **LinkedIn**   | Social Post                                 |
| **Facebook**   | Social Post, Create Ad                      |

**Available source fields for mappings:**

`user.email` · `user.name` · `form.email` · `form.firstName` · `form.lastName` · `form.phone` · `form.company` · `page.url` · `page.title` · `session.id`

**Default AIDA stage:** Action

***

## Node Configuration Panel

Selecting any node opens the config panel on the right. All nodes share these common fields:

| Field                    | Description                                               |
| ------------------------ | --------------------------------------------------------- |
| **Step Name**            | Required. Displayed on the canvas and in analytics.       |
| **Description**          | Optional. Internal notes about this step's purpose.       |
| **Journey Stage**        | AIDA stage for this step (Awareness → Retention).         |
| **Type-specific fields** | URL, selector, scroll depth, provider config (see above). |
| **Delete Step**          | Removes the node and any connected edges.                 |

***

## Element Picker

For nodes that require a CSS selector or form ID, a **crosshair icon** button opens the Element Picker. This loads an interactive overlay of your target URL where you can click directly on the element you want to target — the selector and HTML ID are filled in automatically.

<Tip>
  Use the Element Picker whenever possible. Manually written selectors can break if your site's markup changes; visually selected ones tend to be more stable.
</Tip>

***

## Connecting Nodes

Click and drag from the **output handle** of one node to the **input handle** of another to create a connection (edge). Edges define the progression order — a session advances to the next node only after the previous one fires.

* Hover over any edge to reveal a **delete button** (trash icon) at its midpoint
* Edges can have an optional **label** to annotate the connection (e.g. "Yes path", "Skip")

**Minimum to publish:** A journey must have at least **2 connected nodes** before it can be published.

***

## Saving

The builder auto-saves when you deselect a node with pending changes. You can also save manually using the **Save** button in the header.

The save status indicator shows the current state:

| Indicator     | Meaning                           |
| ------------- | --------------------------------- |
| **Saved ✓**   | All changes written to the server |
| **Saving...** | Write in progress                 |
| **Unsaved**   | Pending changes not yet persisted |

The entire graph (all nodes + edges) is saved as a single atomic operation.

***

## Publishing a Journey

Publishing makes a version **Active** — GTM Suite begins matching live sessions against it immediately.

1. Build your flow with at least 2 connected nodes
2. Click **Publish** in the header
3. Review the confirmation dialog:
   * Node and edge count summary
   * Warning if another version is currently active (it will be archived)
4. Click **Confirm** to go live

<Warning>
  Publishing replaces the currently active version. The previous active version is archived but its historical analytics are preserved.
</Warning>

### Unpublishing

Click **Unpublish** to stop tracking against the active version. The flow is deactivated immediately — sessions in progress are not retroactively affected.

***

## Version Management

| Action                 | How                                                                             |
| ---------------------- | ------------------------------------------------------------------------------- |
| **Create new version** | Click **New Version** in the header — copies the current version as a new draft |
| **Switch versions**    | Use the version dropdown in the header                                          |
| **Delete a version**   | Click **Delete Version** — only available on inactive (draft/archived) versions |
| **Publish a version**  | Click **Publish** while viewing the version you want to go live                 |

A journey always has at least one version. The active version cannot be deleted while it is live — unpublish it first.

***

## Troubleshooting

**"Publish" button is disabled**

* Ensure the journey has at least 2 nodes connected by an edge
* Check that the current version is in Draft status

**Node events are not firing in analytics**

* Confirm the UX Brite tracker is **Verified** on the associated Digital Experience
* For click/selector nodes: verify the CSS selector matches the live element (use browser DevTools → Elements to confirm)
* For custom events: confirm your site calls `uxbrite.track('custom_event', { action: 'EVENT_NAME' })` with the exact event name
* Scroll depth nodes only fire if the tracker has `trackScroll: true` (enabled by default)

**Element Picker shows a blank page**

* The target URL must be publicly accessible. Pages behind authentication or VPN cannot be loaded in the picker.

**I can't edit a journey on mobile**

* The builder is desktop-only. Open GTM Suite on a laptop or desktop to access the canvas editor.

<CardGroup cols={2}>
  <Card icon="git-branch" href="/user-journeys" title="User Journeys Overview">
    Manage and organize all journeys across your workspace.
  </Card>

  <Card icon="play" href="/session-recordings" title="Session Recordings">
    Watch individual sessions to debug drop-off steps.
  </Card>
</CardGroup>