> For the complete documentation index, see [llms.txt](https://eraya.gitbook.io/eraya-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eraya.gitbook.io/eraya-docs/split-url-test/how-to-setup.md).

# How to Setup

A Split URL test sends visitors who land on a given page to one of several **different URLs** — for example, a completely redesigned product page hosted at a separate URL — and measures which one converts better. Unlike a Content or Theme test, Eraya doesn't swap content in place; it **redirects** the visitor.

### Wizard Overview

The creation flow is a 7-step wizard (`ProgressBar` in the header tracks progress):

1. Name & Description
2. Test Variations
3. Trigger Condition
4. URL Test (Configure URLs)
5. Audience
6. Product Targeting
7. Review & Launch

The **Next** button is disabled until the current step passes validation (`utils/validationHelpers.ts`). On the final step, the button reads **Create Preview** (or **Save as Draft** / **Save Changes**), and the test always launches into **preview mode** first — nothing goes live to real traffic until the merchant explicitly activates it from the test's detail page.

***

### Step 1 — Name & Description

Component: `components/steps/NameDescriptionStep.tsx` (wraps the shared `NameDescriptionStepSimple`)

| Field       | Rules                                       |
| ----------- | ------------------------------------------- |
| Test name   | Required, 3–100 characters                  |
| Description | Optional, up to 500 characters              |
| Goal        | Optional — shown because `showGoals={true}` |

Validation (`validateStep(0, …)`):

* Name must be at least 3 characters (trimmed) and no more than 100.
* Description capped at 500 characters.

***

### Step 2 — Test Variations

Component: `components/steps/ConfigureTestVariationsStep.tsx` (wraps the shared `VariationsStepSimple`)

* Each test always has one **Control** variation (removable is disabled — `allowControlRemoval={false}`) plus 1–3 additional variants.
* **Traffic Limit** control (`TrafficLimitControl`) sits above the variation list — caps what % of total eligible traffic is entered into the test at all.
* Each variation has a **name** and a **traffic percentage**; percentages must sum to 100%.
* Variation count: **2 minimum, 4 maximum** (Control + up to 3 variants), from `constants.ts`:
  * `MIN_SPLIT_URL_VARIATIONS = 2`
  * `MAX_SPLIT_URL_VARIATIONS = 4`

{% hint style="warning" %}
**Plan gating:** adding more than 2 variations (i.e., A/B/C/D testing) requires a paid plan (`canUseMultipleVariants` from `useFeatureGuard`). Free-plan users seeing the locked "Add variation" control get an upgrade prompt: *"Testing more than two variations (A/B/C/D) is available on the Pro plan."*
{% endhint %}

Validation (`validateStep(1, …)`):

* At least 2 variations, at most `MAX_SPLIT_URL_VARIATIONS`.
* Traffic percentages must total 100% (±0.01 tolerance).
* Every variation must have a non-empty name.

***

### Step 3 — Trigger Condition

Defines **which page** the test fires on ("When visitors come to:") and **how redirects behave**.

#### URL matching type

A dropdown next to the URL field selects how the trigger URL is matched:

| Matching type   | Meaning                             | Placeholder example                      |
| --------------- | ----------------------------------- | ---------------------------------------- |
| Matches exactly | Full URL must match exactly         | `https://yourstore.com/products/example` |
| Contains        | URL contains this substring         | `products`                               |
| Starts with     | URL path starts with this prefix    | `/products`                              |
| Regex match     | URL matches this regular expression | `/product/\d+`                           |

{% hint style="warning" %}
**Plan gating:** Contains / Starts with / Regex match are **Growth plan and above**. Free-tier stores (and any legacy sub-Growth plan) only get "Matches exactly" — selecting a locked option opens an upgrade prompt instead of changing the setting.
{% endhint %}

* For "Matches exactly", the URL field has a live autocomplete dropdown backed by the store's Shopify catalogue (Home, Products, Collections, Pages, Blogs, Articles, Cart, Search), grouped by category and lazily loaded per category (250 items/page), plus a debounced (350 ms) server-side type-ahead search across all types once the merchant starts typing.
* Picking a suggestion, or typing a full `https://` URL, auto-populates the Control variation's destination URL in Step 4 and triggers an automatic **screenshot preview** of that page (probed against S3 first via `takeUrlScreenshot`; only re-captured if missing, retina 4:3 thumbnail with a hover "Refresh screenshot" action).
* A manually typed value that isn't a full `https://` URL shows an inline warning once the field loses focus: *"Enter the complete URL (including https\://) or select a page from the dropdown."*

#### Redirect behavior

Two mutually exclusive options:

* **Redirect every time** (default/recommended) — visitors are always redirected to their assigned variant; they can't reach the other URL directly.
* **Redirect once** — visitors are redirected only on their first visit; afterward they can browse both URLs directly.

Validation:

* `baseUrl` is required.
* If matching type is "Matches exactly": must start with `http://`/`https://` and be a parseable URL.
* If "Regex match": must be a valid `RegExp`.
* If "Contains"/"Starts with": at least 2 characters.

***

### Step 4 — Configure URLs (URL Test)

For **each variation** (Control + variants), the merchant sets the destination URL it redirects to. Cards are laid out side-by-side (2 columns), color-coded to match the variation's color from Step 2, each showing:

* A URL input with the same autocomplete/type-ahead behavior as Step 3 (grouped Shopify catalogue + server-side search).
* An automatic screenshot preview of that destination (same probe → capture → cache-bust pattern as Step 3), or an empty-state placeholder ("Enter a URL to see a preview") reserving the same 4:3 space so cards stay aligned.
* Inline warning if a manually typed URL isn't a full `https://` URL.

#### Cross-store tracking (Pro plan)

Shown only when the account is on a plan with `canUseCrossStore` **and** has 2+ linked stores. A toggle lets a variation's destination URL point at a *different* Eraya-connected store, and Eraya will attribute that store's orders back to this test. When enabled, the UI shows the exact query parameters to append to each variation's destination URL:

```
?eId=<test id>&eV=<variation>&eStore=<platformId>
```

* `eId` — this test's ID (only known after the test is first saved)
* `eV` — the variation letter (a, b, c, …)
* `eStore` — the originating store's Shopify platform ID

#### Redirect Options (advanced settings, applied to all variations)

* **Preserve query parameters** — keep existing URL params when redirecting (default: on).
* **Use `location.replace()`** — replaces the current history entry instead of pushing a new one, which disables the browser Back button (default: on).

Validation:

* Every variation must have a `redirectVariations` entry with a non-empty URL.
* Each URL must start with `http://`/`https://` and be a valid, parseable URL — a bare path is rejected with a message naming the specific variation.

***

### Step 5 — Audience

Lets the merchant restrict the test to a specific audience segment instead of all visitors. Optional — `null` means all visitors. No hard validation; any selection (including none) passes.

***

### Step 6 — Product Targeting

By default, orders from any visitor who saw the test count toward results. Restricting to specific products is useful for tests where unrelated purchases would skew results (e.g. quantity discounts, bundles, product-specific promos).

* Toggle: **Track all products** vs. a specific product list.
* Gated to Growth plan and above (per the step's own description text).

Validation: passes if `trackAllProducts` is true, or at least one product is selected.

***

### Step 7 — Review & Launch

Component: `components/steps/ReviewAndLaunchStep.tsx`

Read-only summary before launch, showing:

* **Test Details** — name, type ("Split URL Test"), description.
* **Variations & URLs** — each variation card (color-coded, Control/Variant badge, traffic %) with its destination URL and a screenshot thumbnail (falls back to "No preview available" if the S3 image 404s).
* **Trigger Configuration** — base URL and redirect behavior label ("Redirect every time" / "Redirect once per user").
* **Audience** — selected audience name/description/rules, or "All Visitors".
* **Pre-launch Checklist** — pass/fail indicators for:
  * Test name is set
  * At least 2 variations configured
  * All variations have destination URLs
  * Trigger URL is set

{% hint style="warning" %}
**Before you preview**

* Verify all destination URLs are live and accessible
* The test starts in preview — only your preview link redirects until you take it live
* You can pause or stop the test at any time from the dashboard
  {% endhint %}

### Plan Gating Summary

{% hint style="info" %}
This table summarizes every plan restriction called out above, in one place.
{% endhint %}

| Feature                                                | Minimum plan                                        |
| ------------------------------------------------------ | --------------------------------------------------- |
| More than 2 variations (A/B/C/D)                       | Paid (Pro)                                          |
| Advanced URL matching (Contains / Starts with / Regex) | Growth                                              |
| Product targeting (restrict to specific products)      | Growth                                              |
| Cross-store tracking                                   | Pro (+ 2 linked stores)                             |
| More than 1 active test at a time                      | Paid (any) — Free is capped at 1 active/paused test |