# Floating Widget

The Floating Widget is the **embeddable UI component** that appears on your website or app to surface streaks, challenges, and rewards to your end users. You configure its position, branding, and styling here.

:::tip
All text fields (`eudTitle`) in the Floating Widget are **localisable**. Pass `?languageCode=es` (or any locale) when fetching to receive translated values. Guest users can read the widget config without authentication.
:::

---

## How it works

1. **Create a floating widget** — set the `name`, `description`, and configure the EUD fields (position, icon, colours, typography).
2. **Embed the snippet** — add the Gamopanda embed script to your site. The widget launcher button appears at the configured `alignment` position.
3. **Widget opens** — when a visitor clicks the launcher, the full loyalty panel slides in showing streaks, challenges, and rewards.
4. **Logged-in vs logged-out** — the panel content adapts based on whether the user is authenticated. The launcher itself is always visible.
5. **Live updates** — any `PATCH` to the floating widget record takes effect on the next page load without a code deployment.

---

## Fields

### Basic information

| Field | Type | Required | Max length | Description |
|---|---|---|---|---|
| `name` | string | ✅ | 256 | Internal name for this floating widget |
| `description` | string | ✅ | 1 024 | Internal description for this floating widget |

---

## End-user display (EUD)

### Launcher appearance

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `eudTitle` | string | ❌ | — | Label text shown next to (or beneath) the launcher icon. Max 48 chars. Localisable. |
| `eudIcon` | image URL | ❌ | *(default widget icon)* | Icon displayed on the launcher button. Allowed: PNG, JPEG, JPG, GIF, SVG · Max size: 100 KB |

### Position

| Field | Type | Default | Description |
|---|---|---|---|
| `alignment` | enum | `bottom_right` | Where on the screen the launcher is anchored. See [alignment options](#alignment-options) below. |
| `alignmentPositionX` | integer (px) | `20` | Horizontal offset from the aligned edge. E.g. `20` means 20 px from the right when alignment is `bottom_right`. |
| `alignmentPositionY` | integer (px) | `20` | Vertical offset from the aligned edge. E.g. `20` means 20 px from the bottom when alignment is `bottom_right`. |

#### Alignment options

| Value | Description |
|---|---|
| `bottom_right` | *(default)* Anchored to the bottom-right corner of the viewport |
| `bottom_left` | Anchored to the bottom-left corner of the viewport |
| `top_right` | Anchored to the top-right corner of the viewport |
| `top_left` | Anchored to the top-left corner of the viewport |

### Colours

All colour fields must be in **RGBA format**: `rgba(r, g, b, a)`.

| Field | Type | Default | Description |
|---|---|---|---|
| `backgroundColor` | rgba string | `rgba(255, 255, 255, 1)` | Launcher button background fill colour |
| `borderColor` | rgba string | `rgba(226, 232, 240, 1)` | Launcher button border colour |
| `textColor` | rgba string | `rgba(26, 28, 30, 1)` | Launcher label text colour |

### Border & shadow

| Field | Type | Default | Description |
|---|---|---|---|
| `borderWidth` | integer (px) | `1` | Launcher button border width |
| `borderRadius` | integer (px) | `8` | Launcher button corner radius |
| `boxShadow` | string | `0px 2px 1px -1px rgba(0,0,0,0.2), 0px 1px 1px 0px rgba(0,0,0,0.14), 0px 1px 3px 0px rgba(0,0,0,0.12)` | CSS `box-shadow` applied to the launcher button. Max 256 chars. |

### Typography

| Field | Type | Default | Description |
|---|---|---|---|
| `fontSize` | integer (px) | `18` | Font size of the launcher label text |

---

## Real-world examples

**🛍️ E-commerce — bottom-right launcher, white pill**

```json
{
  "name": "Shop Loyalty Widget",
  "description": "Main floating widget for the loyalty programme",
  "eudTitle": "My Rewards",
  "alignment": "bottom_right",
  "alignmentPositionX": 24,
  "alignmentPositionY": 24,
  "backgroundColor": "rgba(255, 255, 255, 1)",
  "borderColor": "rgba(226, 232, 240, 1)",
  "borderWidth": 1,
  "borderRadius": 32,
  "boxShadow": "0px 4px 12px rgba(0, 0, 0, 0.12)",
  "textColor": "rgba(26, 28, 30, 1)",
  "fontSize": 14
}
```

---

**☕ Food & Beverage — bottom-left launcher, branded amber**

```json
{
  "name": "Café Loyalty Widget",
  "description": "Floating widget for the café rewards programme",
  "eudTitle": "Earn Rewards",
  "alignment": "bottom_left",
  "alignmentPositionX": 20,
  "alignmentPositionY": 20,
  "backgroundColor": "rgba(217, 119, 6, 1)",
  "borderColor": "rgba(180, 83, 9, 1)",
  "borderWidth": 0,
  "borderRadius": 50,
  "boxShadow": "0px 4px 16px rgba(217, 119, 6, 0.4)",
  "textColor": "rgba(255, 255, 255, 1)",
  "fontSize": 14
}
```

---

**🏋️ Fitness — no label, icon only, top-right**

```json
{
  "name": "Fitness App Widget",
  "description": "Compact icon-only launcher for the fitness app",
  "alignment": "top_right",
  "alignmentPositionX": 16,
  "alignmentPositionY": 80,
  "backgroundColor": "rgba(16, 185, 129, 1)",
  "borderColor": "rgba(16, 185, 129, 1)",
  "borderWidth": 0,
  "borderRadius": 50,
  "boxShadow": "0px 2px 8px rgba(16, 185, 129, 0.5)"
}
```

> `eudTitle` is omitted — the launcher renders icon-only. Set `alignmentPositionY: 80` to clear any top navigation bar.

---

## Fetching the floating widget

**As a guest (no authentication required):**

```http
GET /api/v1.0/schema/floating_widget/record/{id}
```

**With localisation:**

```http
GET /api/v1.0/schema/floating_widget/record/{id}?languageCode=es
```

**As a logged in end user:**

```http
GET /api/v1.0/schema/floating_widget/record/{id}
x-enduser-access-token: <token>
x-account-id: <account-id>
```

---

## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | CREATE · GET · LIST · UPDATE · DELETE | Full control |
| End user | GET | Read-only |
| Guest user | GET | Publicly readable — widget config loads before login |

---

## Related resources

| Resource | Description |
|---|---|
| [Theme](/theme) | Global design tokens (colours, typography, card styles) consumed by the full widget panel |
| [Template](/template) | All copy and labels shown inside the widget panel |
| [Streak](/streak) | Streaks surfaced inside the widget panel |
| [Challenge](/challenge) | Challenges surfaced inside the widget panel |
| [Reward Log](/reward_log) | Rewards displayed in the widget's rewards section |

---

## API reference

See the [API Reference](/api/floating_widget) for full request/response schemas and interactive examples for:

- `GET /schema/floating_widget/record` — get the floating widget config
- `POST /schema/floating_widget/record` — create a floating widget
- `PATCH /schema/floating_widget/record/{id}` — update a floating widget
- `DELETE /schema/floating_widget/record/{id}` — delete a floating widget