# Game API Integration Guide

## Overview
VIRTUSPLAY supports integration with external game provider APIs. The system is designed to work with or without an API connection by using fallback sample data.

## Current Status
✅ **Sample Data Mode**: Currently using 50 sample games stored in database  
⚠️ **API Mode**: Not configured (requires valid API credentials)

## Configuration

### 1. Environment Variables
Edit `.env` file in the project root:

```env
# Game API Configuration
GAME_API_URL=https://api.gamesprovider.com/v1
GAME_API_SECRET=your_secret_key_here
GAME_API_TIMEOUT=30

# Cache Configuration
CACHE_PATH=storage/cache
GAME_CACHE_TTL=3600
```

### 2. API Requirements
Your game provider API should support these endpoints:

- `GET /getGamesList` - Fetch all available games
- `POST /openGame` - Open game session for player
- `POST /closeGame` - Close game session

### 3. Expected API Response Format

**Get Games List Response:**
```json
{
  "success": true,
  "data": [
    {
      "game_id": "unique_game_id",
      "name": "Game Name",
      "provider": "Provider Name",
      "category": "slots|live_dealers|sports|arcade",
      "image_url": "https://example.com/image.jpg",
      "status": "active"
    }
  ]
}
```

## Syncing Games

### Automatic Sync (When API is Configured)
Run the sync script:
```bash
php sync_games.php
```

The script will:
1. Check if API is configured
2. Fetch games from API
3. Save to database
4. Show statistics

### Manual Sync (Sample Data)
If API is not configured, the script automatically uses sample data:
```bash
php sync_games.php
```

Output:
```
⚠️  WARNING: Game API not configured!
   Using sample/dummy data instead.

Loading sample game data...
✓ Added 50 sample games to database

📊 Database Statistics:
   Total Games: 50
   By Category:
     - slots: 30 games
     - live_dealers: 20 games
```

## Database Schema

Games are stored in the `games` table:

```sql
CREATE TABLE games (
    id INT AUTO_INCREMENT PRIMARY KEY,
    provider_game_id VARCHAR(50) NOT NULL UNIQUE,
    name VARCHAR(255) NOT NULL,
    provider VARCHAR(100) NOT NULL,
    category VARCHAR(50) DEFAULT 'slots',
    image_url VARCHAR(500),
    status ENUM('active','inactive') DEFAULT 'active',
    is_featured TINYINT(1) DEFAULT 0,
    sort_order INT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

## Game Categories

Supported categories:
- `slots` - Slot machine games
- `live_dealers` - Live casino games
- `sports` - Sports betting (coming soon)
- `arcade` - Arcade games (coming soon)
- `poker` - Poker games (coming soon)

## Sample Providers

Currently configured sample providers:
- **Pragmatic Play** - 17 games
- **Evolution Gaming** - 15 games
- **PG Soft** - 10 games
- **Pragmatic Play Live** - 5 games
- **Play'n GO** - 3 games

## Caching

Game list is cached to reduce API calls:
- Cache location: `storage/cache/games_list.json`
- Default TTL: 3600 seconds (1 hour)
- Configure via `GAME_CACHE_TTL` in `.env`

## Troubleshooting

### Games Not Showing
1. Check database has games:
   ```bash
   php sync_games.php
   ```

2. Verify database connection in `app/config/database.php`

3. Check game status is 'active':
   ```sql
   SELECT * FROM games WHERE status = 'active';
   ```

### API Connection Issues
1. Verify `.env` file exists and has correct values
2. Test API endpoint manually
3. Check logs in `storage/logs/`
4. Ensure firewall allows outbound connections

### Clear Cache
Delete cache file to force fresh API fetch:
```bash
rm storage/cache/games_list.json
```

## Adding Real API Integration

To integrate with a real game provider:

1. **Update .env:**
   ```env
   GAME_API_URL=https://api.yourprovider.com/v1
   GAME_API_SECRET=real_secret_key
   ```

2. **Test API Connection:**
   ```bash
   php sync_games.php
   ```

3. **Verify Games Imported:**
   Check output shows games received from API

4. **Schedule Regular Sync:**
   Set up cron job to sync periodically:
   ```cron
   0 */6 * * * cd /path/to/virtusplay && php sync_games.php
   ```

## Security Notes

- Never commit `.env` file to version control
- Keep API secrets secure
- Use HTTPS for API connections
- Implement IP whitelisting if required by provider
- Monitor API usage and rate limits

## Support

For API integration issues:
1. Check provider documentation
2. Verify API credentials
3. Test endpoints with tools like Postman
4. Review error logs