# Intégration des Widgets avec OBS

Ce document explique comment utiliser les widgets avec OBS Studio.

## Vue d'ensemble

Le système permet de générer des liens uniques pour chaque widget configuré, qui peuvent être utilisés dans OBS Studio comme source "Navigateur". Les widgets réagissent automatiquement aux événements de votre stream (chat, follows, abonnements, etc.) sans modification de leur code.

## Architecture

### 1. Génération de tokens

Chaque widget configuré possède un token unique stocké dans la table `widget_tokens`. Ce token permet d'accéder au widget sans authentification.

### 2. Affichage du widget

L'endpoint `/src/pages/widget-view.php` affiche le widget avec sa configuration. Il :
- Charge le HTML, CSS et JavaScript du widget
- Injecte la configuration sauvegardée
- Simule l'événement `onWidgetLoad` au format Stream Elements
- Établit une connexion SSE pour recevoir les événements en temps réel

### 3. Transmission des événements

L'API `/src/api/widget-events-stream.php` transmet les événements en temps réel via Server-Sent Events (SSE) :
- **Alertes** : follows, abonnements, raids, cheers, etc. (via EventSub)
- **Chat** : messages du chat Twitch (via IRC, stockés dans un fichier temporaire)

### 4. Adaptation des événements

Le wrapper JavaScript dans `widget-view.php` adapte les événements au format Stream Elements :
- `onWidgetLoad` : initialise le widget avec la configuration
- `onEventReceived` : transmet les événements (chat, alertes) au format attendu

## Utilisation

### Pour l'utilisateur

1. **Configurer le widget** : Accédez à la page de configuration du widget (`/src/pages/widget-config.php`)
2. **Copier le lien OBS** : Dans la section "📺 Lien OBS", copiez le lien unique
3. **Ajouter dans OBS** :
   - Créez une nouvelle source "Navigateur" dans OBS Studio
   - Collez le lien dans le champ "URL"
   - Définissez la largeur et hauteur (généralement 1920x1080)
   - Activez "Actualiser le navigateur quand la scène devient active"

### Structure de la base de données

#### Table `widget_tokens`

```sql
CREATE TABLE IF NOT EXISTS `widget_tokens` (
    `token` VARCHAR(64) NOT NULL,
    `twitch_id` VARCHAR(255) NOT NULL,
    `widget_name` VARCHAR(255) NOT NULL,
    `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    `last_used_at` TIMESTAMP NULL DEFAULT NULL,
    `expires_at` TIMESTAMP NULL DEFAULT NULL,
    PRIMARY KEY (`token`),
    INDEX `idx_twitch_widget` (`twitch_id`, `widget_name`),
    CONSTRAINT `fk_widget_tokens_twitch_id` FOREIGN KEY (`twitch_id`) REFERENCES `users` (`twitch_id`) ON DELETE CASCADE
);
```

## Format des événements

### Événements de chat

Format envoyé au widget :
```javascript
{
    detail: {
        listener: 'message',
        event: {
            data: {
                text: 'Message du chat',
                message: 'Message du chat',
                userId: '123456',
                user_name: 'Username',
                user_login: 'username',
                tags: {
                    badges: 'subscriber/12,moderator/1',
                    mod: '1',
                    subscriber: '1',
                    'broadcaster/': '1'
                }
            }
        }
    }
}
```

### Événements d'alerte

Format envoyé au widget :
```javascript
{
    detail: {
        listener: 'follower-latest', // ou 'subscriber-latest', 'raid-latest', etc.
        event: {
            data: {
                user_id: '123456',
                user_name: 'Username',
                // ... autres données selon le type d'événement
            }
        }
    }
}
```

## Types d'événements supportés

- **Chat** : Messages du chat Twitch
- **Follow** : Nouveaux followers
- **Subscribe** : Abonnements
- **Raid** : Raids entrants
- **Cheer** : Bits/Cheermotes
- **Gift** : Cadeaux d'abonnements
- **Channel Points** : Utilisation de points de chaîne (nécessite une connexion PubSub séparée)

## Notes techniques

### Stockage des messages de chat

Les messages de chat sont stockés temporairement dans :
```
/tmp/twitch-chat-{twitch_id}.json
```

Ce fichier contient les 100 derniers messages et est mis à jour par `chat-stream.php`.

### Événements EventSub

Les événements d'alerte sont récupérés depuis le système EventSub existant, qui stocke les événements en mémoire dans :
```
/tmp/twitch-eventsub-events.json
```

### Sécurité

- Les tokens sont générés de manière sécurisée avec `random_bytes(32)`
- Les tokens peuvent être révoqués en les supprimant de la base de données
- Les tokens peuvent avoir une date d'expiration (optionnel, non implémenté par défaut)

## Dépannage

### Le widget ne réagit pas aux événements

1. Vérifiez que les événements sont bien détectés dans `/tests/stream-events-test.php`
2. Vérifiez la console du navigateur dans OBS pour les erreurs JavaScript
3. Vérifiez que la connexion SSE est établie (regardez les logs du serveur)

### Le widget ne se charge pas

1. Vérifiez que le token est valide
2. Vérifiez que le widget existe dans `/products/`
3. Vérifiez les permissions de lecture des fichiers

### Les événements de chat ne fonctionnent pas

1. Vérifiez que `chat-stream.php` est appelé (pour initialiser le stockage)
2. Vérifiez que le fichier temporaire `/tmp/twitch-chat-{twitch_id}.json` existe
3. Vérifiez les permissions d'écriture dans `/tmp/`