ihm_client/examples/README.md

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:

   cd /home/ank/dev/ihm_client_dev3
   npm run start
   

2. Open the external site:

   # 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

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

Adding Custom Messages

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

Handling Custom Events

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:

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