@gamifyhost/gamifyhost-widget

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

• Clone the repository:

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

• Install dependencies:

npm install

• Start the development server:

npm run dev

• 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:

• Widget script is loaded via <script> tag
• Shadow root is attached to the container element
• All styles and fonts are injected into the shadow root
• 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:

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

Games

To add new games:

• Create a new page component in src/pages/
• Add route in src/router.tsx
• Update the navigation in src/pages/HomePage.tsx
• 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:

• Fork the repository
• Create a feature branch: git checkout -b feature/my-feature
• Make your changes
• Commit with clear messages: git commit -m 'Add new game feature'
• Push to your fork: git push origin feature/my-feature
• 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: [e-mail]
• 🐛 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