ihm_client/docs/INTEGRATION.md

# 4NK Integration Guide

## 🎯 Modes d'utilisation

Le site 4NK peut être utilisé de deux façons :

### 1. **Mode Normal** (Site autonome)
- **URL** : http://localhost:3004
- **Interface** : Header complet + navigation normale
- **Utilisation** : Application standalone
- **Fonctionnalités** : Toutes les fonctionnalités disponibles

### 2. **Mode Iframe** (Intégration externe)
- **URL** : http://localhost:3004 (détection automatique)
- **Interface** : Header masqué + menu intégré dans le contenu
- **Utilisation** : Intégration dans un site externe
- **Fonctionnalités** : Communication bidirectionnelle avec le parent

## 🔧 Détection automatique

Le site détecte automatiquement s'il est chargé dans une iframe :

```javascript
// Détection iframe
if (window.parent !== window) {
  // Mode iframe activé
  document.body.classList.add('iframe-mode');
  // Header masqué automatiquement
}
```

## 📱 Interface adaptative

### Mode Normal
```
┌─────────────────────────────────────┐
│ Header (Navigation, Logo, etc.)     │
├─────────────────────────────────────┤
│ Contenu principal                    │
│ ├── Titre et description            │
│ ├── Interface de pairing            │
│ └── Boutons d'action                │
└─────────────────────────────────────┘
```

### Mode Iframe
```
┌─────────────────────────────────────┐
│ Contenu principal (sans header)     │
│ ├── Titre et description            │
│ ├── Menu intégré (Home, Account...) │
│ ├── Interface de pairing            │
│ └── Boutons d'action                │
└─────────────────────────────────────┘
```

## 🔄 Communication iframe

### Messages envoyés au parent
- `IFRAME_READY` : Iframe initialisé
- `MENU_NAVIGATION` : Navigation du menu
- `PAIRING_4WORDS_WORDS_GENERATED` : 4 mots générés
- `PAIRING_4WORDS_STATUS_UPDATE` : Mise à jour du statut
- `PAIRING_4WORDS_SUCCESS` : Pairing réussi
- `PAIRING_4WORDS_ERROR` : Erreur de pairing
- `TEST_RESPONSE` : Réponse à un message de test
- `LISTENING` : Notification que l'iframe écoute les messages

### Messages reçus du parent
- `TEST_MESSAGE` : Test de communication
- `PAIRING_4WORDS_CREATE` : Créer un pairing
- `PAIRING_4WORDS_JOIN` : Rejoindre avec 4 mots
- `LISTENING` : Notification que le parent écoute les messages
- `IFRAME_READY` : Notification que l'iframe est prête (envoyée par l'iframe elle-même)

## 🧪 Tests d'intégration

### Test rapide
```bash
# Ouvrir dans le navigateur
open examples/test-integration.html
```

### Test complet
```bash
# Site externe d'exemple
open examples/external-site.html
```

## 🎨 Styles CSS

Les styles s'adaptent automatiquement :

```css
/* Styles normaux */
.title-container { /* ... */ }

/* Styles iframe */
.iframe-mode .content-menu { /* ... */ }
.iframe-mode .menu-btn { /* ... */ }
```

## 🚀 Utilisation en production

### 1. Site autonome
```html
<!-- Utilisation normale -->
<iframe src="https://your-4nk-site.com" width="100%" height="600px"></iframe>
```

### 1.1 Relai WebSocket
- Relai principal exposé en `wss://relay235.4nkweb.com/ws/`
- Terminaison TLS gérée par `nginx.relay235.conf` (reverse proxy vers le service local sur `127.0.0.1:8091`)
- Variables d’environnement cliente à utiliser : `VITE_BOOTSTRAPURL=wss://relay235.4nkweb.com/ws/`

### 2. Intégration personnalisée
```html
<!-- Site externe -->
<div id="4nk-container">
  <iframe
    src="https://your-4nk-site.com"
    sandbox="allow-scripts allow-same-origin allow-forms"
    onload="init4NKIntegration(this)">
  </iframe>
</div>

<script>
function init4NKIntegration(iframe) {
  // Écouter les messages de l'iframe
  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://your-4nk-site.com') return;

    const { type, data } = event.data;
    switch (type) {
      case 'IFRAME_READY':
        console.log('4NK iframe ready');
        break;
      case 'PAIRING_4WORDS_SUCCESS':
        console.log('Pairing successful:', data.message);
        break;
    }
  });

  // Envoyer des commandes à l'iframe
  function createPairing() {
    iframe.contentWindow.postMessage({
      type: 'PAIRING_4WORDS_CREATE',
      data: {}
    }, 'https://your-4nk-site.com');
  }
}
</script>
```

## 🔒 Sécurité

### Vérification d'origine
```javascript
// Toujours vérifier l'origine des messages
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://trusted-4nk-site.com') {
    return; // Ignorer les messages non autorisés
  }
  // Traiter le message
});
```

### Sandbox iframe
```html
<iframe
  src="https://your-4nk-site.com"
  sandbox="allow-scripts allow-same-origin allow-forms"
  allow="clipboard-write">
</iframe>
```

## 📊 Monitoring

### Logs de communication
```javascript
// Activer les logs détaillés
window.DEBUG_IFRAME = true;

// Écouter tous les messages
window.addEventListener('message', (event) => {
  console.log('📨 Message received:', {
    origin: event.origin,
    type: event.data.type,
    data: event.data.data
  });
});
```

## 🐛 Dépannage

### Problèmes courants

1. **Iframe ne se charge pas**
   - Vérifier les paramètres CORS
   - Vérifier l'URL de l'iframe
   - Vérifier les paramètres sandbox

2. **Messages non reçus**
   - Vérifier la vérification d'origine
   - Vérifier le format des messages
   - Vérifier la console pour les erreurs

3. **Styles cassés**
   - Vérifier la classe `iframe-mode`
   - Vérifier les styles CSS conditionnels
   - Vérifier la détection d'iframe

### Debug mode
```javascript
// Activer le mode debug
localStorage.setItem('4nk-debug', 'true');

// Voir les logs détaillés
console.log('4NK Debug Mode:', localStorage.getItem('4nk-debug'));
```