GamifyHost Widget

An embeddable React widget that brings gamification features to any website. Includes interactive games, leaderboards, and a complete reward system with style isolation via Shadow DOM.

Features

• 🎮 Multiple Games
  • Neon Wheel - Spin-to-win prize wheel
  • Cosmic Slots - Space-themed slot machine
  • Enigma Boxes - Mystery box game
• 🏆 Leaderboard System - Track and display top players
• ⚡ Energy Meter - Built-in game balance system
• 🎨 Theme Support - Light/Dark mode with customizable styling
• 🔒 Style Isolation - Shadow DOM prevents CSS conflicts
• 📱 Responsive Design - Works on all device sizes

Technology Stack

• React 19 - UI framework
• TypeScript - Type safety
• Vite - Build tool and dev server
• Tailwind CSS 4 - Styling
• Shadow DOM - Style encapsulation

Installation

Embed in Your Website

Add the widget script to your HTML:

<script
  src="https://cdn.gamifyhost.com/widget.js"
  data-public-key="your_public_key_here"
  data-user-id="unique_user_id"
  data-initial-balance="1000"
  data-api-url="https://api.gamifyhost.com"
  data-container="gamifyhost"
></script>

The widget will automatically initialize and render in the specified container.

Configuration Options

| Attribute | Required | Default | Description | |-----------|----------|---------|-------------| | data-public-key | ✅ Yes | - | Your GamifyHost public API key | | data-user-id | ❌ No | - | Unique identifier for the current user | | data-initial-balance | ❌ No | 0 | Starting balance for the user | | data-api-url | ❌ No | https://api.gamifyhost.com | API endpoint URL | | data-container | ❌ No | gamifyhost | ID of the container element |

Example Configurations

Basic Setup:

<script
  src="https://cdn.gamifyhost.com/widget.js"
  data-public-key="pk_live_abc123"
></script>

With User Session:

<script
  src="https://cdn.gamifyhost.com/widget.js"
  data-public-key="pk_live_abc123"
  data-user-id="user_xyz789"
  data-initial-balance="500"
></script>

Custom Container:

<div id="my-games-widget"></div>
<script
  src="https://cdn.gamifyhost.com/widget.js"
  data-public-key="pk_live_abc123"
  data-container="my-games-widget"
></script>

Development

Prerequisites

• Node.js 18+
• npm, yarn, or pnpm

Setup

1. Clone the repository:

git clone https://github.com/gamifyhost/gamifyhost-widget.git
cd gamifyhost-widget

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

4. Open test.html in your browser to see the widget in action.

Available Scripts

• npm run dev - Start Vite development server
• npm run build - Build for production
• npm run preview - Preview production build locally

Project Structure

gamifyhost-widget/
├── src/
│   ├── components/      # React components
│   │   └── EnergyMeter.tsx
│   ├── hooks/          # Custom React hooks
│   │   └── useGameSounds.ts
│   ├── lib/            # Core libraries
│   │   ├── api.ts      # API client
│   │   ├── config.ts   # SDK configuration
│   │   ├── context.tsx # React context
│   │   └── theme.tsx   # Theme management
│   ├── pages/          # Game pages
│   │   ├── HomePage.tsx
│   │   ├── NeonWheelPage.tsx
│   │   ├── CosmicSlotsPage.tsx
│   │   ├── EnigmaBoxesPage.tsx
│   │   └── LeaderboardPage.tsx
│   ├── App.tsx         # Main app component
│   ├── router.tsx      # Client-side routing
│   ├── widget.ts       # Widget initialization
│   ├── fonts.ts        # Font injection
│   └── globals.css     # Global styles
├── test.html           # Test page for development
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md

How It Works

Shadow DOM Isolation

The widget uses Shadow DOM to prevent CSS conflicts with the host page:

1. Widget script is loaded via <script> tag
2. Shadow root is attached to the container element
3. All styles and fonts are injected into the shadow root
4. React app renders inside the shadow DOM

This ensures the widget's styles won't affect your page and vice versa.

API Integration

The widget communicates with the GamifyHost API to:

• Authenticate users via public key
• Track game results and balances
• Update leaderboards
• Sync user progress

Theme System

Supports light and dark modes with automatic detection:

• Uses CSS custom properties for theming
• Theme styles injected into shadow root
• Persistent theme selection via localStorage

Customization

Styling

The widget uses Tailwind CSS with custom design tokens. To customize:

1. Modify src/globals.css for global theme variables
2. Update component styles in respective .tsx files
3. Rebuild the widget: npm run build

Games

To add new games:

1. Create a new page component in src/pages/
2. Add route in src/router.tsx
3. Update the navigation in src/pages/HomePage.tsx
4. Implement game logic with API integration

Browser Support

• Chrome/Edge 88+
• Firefox 85+
• Safari 14+
• All browsers with Shadow DOM support

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Commit with clear messages: git commit -m 'Add new game feature'
5. Push to your fork: git push origin feature/my-feature
6. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Maintain existing code style
• Test your changes thoroughly
• Update documentation as needed
• Keep commits focused and atomic

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions, issues, or feature requests:

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: docs.gamifyhost.com

Acknowledgments

• Built with React
• Styled with Tailwind CSS
• Bundled with Vite
• Fonts from Google Fonts

Made with ⚡ by the GamifyHost team