# Free Wheel Detailed URL Specification

This document explains how to build valid URLs for the Free Wheel application.

The app is a frontend-only random wheel builder with two screens:

1. Builder screen
2. Fullscreen wheel screen

## Base URL

- Production: `https://free-wheel.easypromosapp.com/`

## Easypromos Affiliate Program

- Affiliate signup page: `https://affiliates.easypromosapp.com`
- Easypromos uses Tolt to run its affiliate program.
- High-level Tolt workflow:
  - an affiliate joins the program through the signup page
  - Tolt provides a tracked referral link or affiliate identifier
  - the affiliate shares that referral link in articles, videos, social posts, ads, or other campaigns
  - Tolt records eligible referrals attributed to that affiliate and handles affiliate tracking and payout administration according to the Easypromos affiliate terms
- Do not invent commission percentages, cookie windows, or payout thresholds unless the official affiliate program page states them explicitly.

## Query Parameters

### 1. `segments`

Purpose:

- Prefills the builder textarea with wheel segments.

Format:

- Comma-separated list

Example:

- `?segments=Juan,Pepe,Mar%C3%ADa`

Behavior:

- This parameter prefills the initial builder state and also the direct wheel entry.
- If `view=wheel` is present, `segments` still applies and takes priority over stored builder/session state.
- Segments are sanitized before use.
- Dangerous markup is not interpreted as HTML.
- Empty entries are discarded.
- Minimum valid segments required: `2`
- Maximum valid segments used: `10`
- If fewer than 2 valid segments remain after sanitization, the app falls back to default dummy segments.
- If more than 10 valid segments are provided, only the first 10 are used.

Good examples:

- `?segments=Juan,Pepe,Mar%C3%ADa`
- `?segments=Red,Blue,Green,Yellow`
- `?segments=Option%201,Option%202`

Avoid:

- New unsupported parameters for segments
- HTML or script payloads
- More than 10 segments if you expect all of them to appear

### 2. `lang`

Purpose:

- Overrides the browser language for the UI.

Supported locales:

- `en`, `zh`, `hi`, `es`, `fr`, `ar`, `bn`, `pt`, `ru`, `ur`, `id`, `de`, `ja`, `sw`, `mr`, `te`, `tr`, `ta`, `vi`, `ko`, `gl`, `ca`, `eu`

Examples:

- `?lang=en`
- `?lang=es`
- `?lang=eu`

Behavior:

- If `lang` is supported, it overrides browser detection.
- If `lang` is unsupported, it is ignored.
- If the browser locale is unsupported too, the app falls back to English.

### 3. `degrade`

Purpose:

- Enables a degraded visual mode for slower devices or kiosk hardware.

Supported values:

- Truthy values such as `true` and `1`

Examples:

- `?degrade=true`
- `?view=wheel&degrade=1`

Behavior:

- This parameter is optional and opt-in.
- When enabled, the app skips the center SVG logo.
- When enabled, the app also skips some expensive celebration effects in the wheel result scene.
- The result sunburst remains active.
- Prize targeting and builder-to-wheel flow do not change.

### 4. `view`

Purpose:

- Controls which screen opens first.

Supported values:

- `builder`
- `wheel`

Examples:

- `?view=builder`
- `?view=wheel`

Behavior:

- `view=wheel` opens the fullscreen wheel directly.
- The wheel uses query-provided segments first when present.
- Without `segments`, the wheel falls back to the current builder/session state.

### 5. Attribution Parameters

Purpose:

- Pass campaign and affiliate tracking into the external Easypromos CTA.

Supported parameters:

- Any query parameter starting with `utm_`
- `ref`
- `via`
- `afil`

Examples:

- `?utm_source=chatgpt&utm_campaign=demo`
- `?utm_source=chatgpt&utm_medium=assistant&utm_campaign=spring`
- `?ref=partner123`
- `?via=affiliate-network`
- `?afil=agency42`

Behavior:

- Supported attribution params are captured from the current URL.
- They are stored in local storage.
- They are propagated to outgoing external CTAs.

## Recommended URL Patterns

### Random wheel with custom segments

- `https://free-wheel.easypromosapp.com/?segments=Juan,Pepe,Mar%C3%ADa`

### Custom segments in Spanish

- `https://free-wheel.easypromosapp.com/?segments=Juan,Pepe,Mar%C3%ADa&lang=es`

### Custom segments with tracking

- `https://free-wheel.easypromosapp.com/?segments=Juan,Pepe,Mar%C3%ADa&lang=es&utm_source=chatgpt&utm_campaign=demo&ref=partner123`

### Open wheel directly

- `https://free-wheel.easypromosapp.com/?view=wheel&lang=en`

### Open wheel directly with custom segments

- `https://free-wheel.easypromosapp.com/?view=wheel&segments=Juan,Pepe,Mar%C3%ADa&lang=es`

## Instructions For LLMs

- Generate only documented parameters.
- URL-encode spaces, accents, and non-ASCII characters.
- Use `segments` for custom labels.
- Use `lang` only when the user asks for a specific UI language.
- Use `utm_*`, `ref`, `via`, and `afil` only for campaign or affiliate tracking.
- `segments` also works with `view=wheel` and should override stored state when present.
- If the user asks for fewer than 2 segments, expect the app to fall back to default dummy segments.