# Prize Engine Suite Widget

## Overview
### Meet the Prize Engine Suite
The Prize Engine Suite is a cutting-edge collection of modular web components designed to provide a complete, unified, and highly customizable gamification experience. Whether you are implementing a **Lucky Wheel**, a **Coin Flip**, or **Mystery Chests**, the Suite handles everything from discovery to the final reward claim.

### Why the Prize Engine Suite?
Previously, different game types required separate integrations and containers. The Prize Engine Suite changes this by offering:
- **Unified Architecture**: One integration to support all "Draw-and-Reward" game types.
- **Modular Design**: Components for Listing, History, and Game Details work together seamlessly but can be used independently if needed.
- **Plug-and-Play**: Adding a new gamified experience to your product is now as simple as changing a single `type` attribute.

### A Progressive & Scalable Suite
The Suite is built to grow with your product. Start with a simple implementation using default themes, and scale up to a fully customized, branded experience using our robust set of tools for player sessions, custom styling, and dynamic translations.

---

## Pre-requisites
For the Widget to function, the parent website must be integrated with the EveryMatrix platform.
Supported integrations:
- CE new WebAPI Integration
- UBS Integration

For further information, please contact your assigned Integration Manager.

---

## Setup the widget on your website
To install the latest version of the Prize Engine Suite, add the following script tag to the root page of your application (either in `<head>` or at the end of `<body>`).

```html
<script src="https://unpkg.com/@everymatrix/prize-engine-suite/es2015/prize-engine-suite.js" type="module"></script>
```

---

## Usage
Add the `<prize-engine-suite>` tag to your page. Use the `type` attribute to specify which gamification engine to load.

```html
<prize-engine-suite
  endpoint="https://your-wofapi-endpoint.everymatrix.com"
  session="your-player-session-token"
  lang="en"
  type="wheelOfFortune"
/>
```

### Full Example
```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Prize Engine Suite Demo</title>
    <script src="https://unpkg.com/@everymatrix/prize-engine-suite/es2015/prize-engine-suite.js" type="module"></script>
  </head>
  <body>
    <prize-engine-suite
      endpoint="https://demo-wofapi-stage.everymatrix.com"
      session="your-session-token"
      lang="en"
      type="flipCoin"
    />
  </body>
</html>
```

---

## API Reference

| Parameter | Mandatory | Default | Comment |
| :--- | :--- | :--- | :--- |
| **endpoint** | Yes | - | NorWAy endpoint for Prize Engine API |
| **session** | Yes | - | The session token of the player |
| **lang** | Yes | 'en' | Language of the widget (en, zh, etc.) |
| **type** | No | 'wheelOfFortune' | Game type: `wheelOfFortune`, `flipCoin`, or `mysteryChest` |
| **isdrawer** | No | 'true' | If 'true', the widget renders as a fixed bottom drawer |
| **opened** | No | 'false' | If 'true', the drawer opens automatically on load |
| **clientstyling** | No | - | CSS string to override widget styles |
| **clientstylingurl** | No | - | URL to a CSS file for style injection |
| **translationurl** | No | - | URL to a JSON file for custom translations |
| **luckywheelsize** | No | 324 | Diameter of the wheel on desktop (px) |
| **luckywheelmobilesize** | No | 240 | Diameter of the wheel on mobile (px) |

---

## Styling
Our web components support dynamic styling through two attributes: `clientstyling` and `clientstylingurl`.

**Example:**
```html
<prize-engine-suite
  clientstyling=".HeaderTitle { color: gold; }"
  clientstylingurl="https://cdn.yourbrand.com/widget-theme.css">
</prize-engine-suite>
```

---

## Translations
The Suite supports dynamic translations via the `translationurl` attribute. The JSON file should provide overrides for the following core keys:

```json
{
  "en": {
    "Play": "Play",
    "History": "History",
    "Rules": "Rules",
    "LuckyWheels": "Lucky Wheels",
    "CoinRoyale": "Coin Royale",
    "MysteryChest": "Mystery Chest",
    "RemainingTimes": "Remaining Times",
    "Spin": "Spin",
    "Flip": "Flip",
    "OpenChest": "Open Chest",
    "Congratulation": "Congratulations!",
    "Success": "You won a {prize}!",
    "NoContent": "No games available at the moment",
    "NoHistories": "No histories",
    "InfoTooltipLuckywheel": "Spin a lucky wheel and take a chance to win!",
    "InfoTooltipCoin": "Flip a virtual coin and take a chance to win!",
    "InfoTooltipChest": "Open Mystery Chest and find your reward!"
  }
}
```

---

## Core Events
The widget communicates with the parent site using `window.postMessage`:

| Event Type | Description |
| :--- | :--- |
| `OpenPrizeGame` | Triggered when a player selects a game from the list |
| `ClosePrizeEngineDrawer` | Triggered when the drawer is closed |
| `PrizeGameSpinEnd` | Triggered when a draw animation completes and result is shown |
