@everymatrix/prize-engine-suite 0.0.1

package/README.md

@@ -0,0 +1,138 @@
+# 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 |