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 :

// 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

# Ouvrir dans le navigateur
open examples/test-integration.html

Test complet

# Site externe d'exemple
open examples/external-site.html

🎨 Styles CSS

Les styles s'adaptent automatiquement :

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

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

🚀 Utilisation en production

1. Site autonome

<!-- 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

<!-- 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

// 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

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

📊 Monitoring

Logs de communication

// 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

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

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