# 4NK Pairing Integration Example

This example demonstrates how to integrate the 4NK pairing system into an external website using an iframe with channel_message communication.

## Architecture

```
┌─────────────────────────────────────┐
│ External Website (Parent)           │
│ ├── Header with site branding        │
│ ├── Main content area               │
│ └── Iframe (4NK App)                │
│     ├── No header (removed)         │
│     ├── Menu buttons in content     │
│     ├── Pairing interface           │
│     └── Communication with parent   │
└─────────────────────────────────────┘
```

## Features

### External Site (Parent)
- **Header**: Site branding and navigation
- **Iframe Container**: Hosts the 4NK application
- **Status Panel**: Shows communication status
- **Log System**: Displays real-time communication
- **Controls**: Test communication and refresh

### 4NK Application (Iframe)
- **No Header**: Clean interface without site header
- **Integrated Menu**: Menu buttons within content area
- **Pairing System**: 4-word authentication system
- **Communication**: Bidirectional message passing

## Communication Protocol

### Messages from Parent to Iframe
- `TEST_MESSAGE`: Test communication
- `PAIRING_4WORDS_CREATE`: Request pairing creation
- `PAIRING_4WORDS_JOIN`: Request pairing join with words

### Messages from Iframe to Parent
- `IFRAME_READY`: Iframe initialization complete
- `MENU_NAVIGATION`: Menu button clicked
- `PAIRING_4WORDS_WORDS_GENERATED`: 4 words generated
- `PAIRING_4WORDS_STATUS_UPDATE`: Status update
- `PAIRING_4WORDS_SUCCESS`: Pairing successful
- `PAIRING_4WORDS_ERROR`: Pairing error
- `TEST_RESPONSE`: Response to test message

## Usage

1. **Start the 4NK application**:
   ```bash
   cd /home/ank/dev/ihm_client_dev3
   npm run start
   ```

2. **Open the external site**:
   ```bash
   # Open examples/external-site.html in a browser
   # Or serve it via a web server
   ```

3. **Test the integration**:
   - The iframe loads the 4NK application
   - Use the "Send Test Message" button to test communication
   - Click menu buttons to see navigation messages
   - Use the pairing interface to test 4-word authentication

## Security Considerations

- **Origin Verification**: In production, verify `event.origin` in message handlers
- **Sandbox Attributes**: Iframe uses `sandbox` for security
- **CSP Headers**: Consider Content Security Policy headers
- **HTTPS**: Use HTTPS in production for secure communication

## Customization

### Styling the Iframe
```css
.iframe-container {
  width: 100%;
  height: 600px;
  border: 2px solid #e0e0e0;
  border-radius: 8px;
  overflow: hidden;
}
```

### Adding Custom Messages
```javascript
// Send custom message to iframe
iframe.contentWindow.postMessage({
  type: 'CUSTOM_ACTION',
  data: { parameter: 'value' }
}, 'http://localhost:3004');
```

### Handling Custom Events
```javascript
window.addEventListener('message', function(event) {
  if (event.origin !== 'http://localhost:3004') return;

  const { type, data } = event.data;

  switch (type) {
    case 'CUSTOM_EVENT':
      // Handle custom event
      break;
  }
});
```

## Troubleshooting

### Common Issues

1. **Iframe not loading**: Check CORS settings and iframe src URL
2. **Messages not received**: Verify origin checking and message format
3. **Styling issues**: Check iframe container dimensions and CSS
4. **Communication errors**: Check browser console for error messages

### Debug Mode

Enable debug logging by adding to the iframe:
```javascript
window.DEBUG_IFRAME = true;
```

## Production Deployment

1. **Update Origins**: Change localhost URLs to production domains
2. **Security Headers**: Add appropriate CSP and security headers
3. **Error Handling**: Implement proper error handling and fallbacks
4. **Monitoring**: Add logging and monitoring for communication events
5. **Testing**: Test across different browsers and devices

## API Reference

### Parent Window API
- `sendTestMessage()`: Send test message to iframe
- `clearLog()`: Clear communication log
- `refreshIframe()`: Refresh iframe content

### Iframe API
- `initIframeCommunication()`: Initialize communication
- `initContentMenu()`: Initialize menu buttons
- `createPairingViaIframe()`: Create pairing process
- `joinPairingViaIframe(words)`: Join pairing with words