Introduction

This guide provides developers with two methods to embed Orthogramic Insights into a web application:

iframe Integration (Simple & Universal)
JavaScript SDK Integration (Flexible & Interactive with WebSockets)

Authentication Requirements

Both methods require an API token for authentication. See: Adding an API token
The token should be retrieved securely and never exposed in frontend code.
Tokens can be passed via query parameters (for iframe) or function arguments (for SDK).

Using an `<iframe>`

This method allows embedding Orthogramic Insights via an <iframe>, making it easy to integrate on any website.

Basic Embed

<iframe
  src="https://orthogramic.com/embed/mindmap?id=YOUR_MAP_ID&token=YOUR_AUTH_TOKEN"
  width="100%"
  height="600px"
  style="border:none;"
  allowfullscreen>
</iframe>

Key Parameters

Parameter	Type	Required	Description
`id`	`string`	✅	The unique mindmap ID
`token`	`string`	✅	Authentication token
`theme`	`"light"	"dark"`	❌
`zoom`	`number`	❌	Zoom level (e.g., `1.2`)

Example with Customization

<iframe
  src="https://orthogramic.com/embed/mindmap?id=12345&token=abc123&theme=dark&zoom=1.5"
  width="100%"
  height="600px"
  style="border:none;"
  allowfullscreen>
</iframe>

Making the `<iframe>` Responsive

By default, iframes do not resize automatically. To make the mindmap responsive, you can:

Use CSS for flexible sizing.
Use JavaScript to adjust height dynamically.

Option 1: CSS for Responsiveness

.mindmap-container {
  width: 100%;
  height: 80vh; /* Adjust based on needs */
  min-height: 500px;
  border: none;
  overflow: auto; /* Enable scrolling if necessary */
}

<iframe class="mindmap-container"
  src="https://orthogramic.com/embed/mindmap?id=12345&token=abc123"
></iframe>

Using the JavaScript SDK

For developers who need greater flexibility, our JavaScript SDK allows embedding dynamic, interactive Orthogramic Insights with real-time updates via WebSockets.

Installing the SDK

<script src="https://orthogramic.com/sdk/mindmap.js"></script>

Embedding with WebSockets

<div id="mindmap-container"></div>

<script>
  const socket = new WebSocket("wss://orthogramic.com/ws/mindmap");

  socket.onopen = function() {
    socket.send(JSON.stringify({
      action: "subscribe",
      mindmapId: "12345",
      token: "abc123"
    }));
  };

  socket.onmessage = function(event) {
    const data = JSON.parse(event.data);
    if (data.update) {
      OrthogramicMindmap.render({
        container: "mindmap-container",
        mindmapId: data.mindmapId,
        token: "abc123",
        theme: "dark"
      });
    }
  };

  socket.onerror = function(error) {
    console.error("WebSocket Error: ", error);
  };

  socket.onclose = function() {
    console.log("WebSocket connection closed. Reconnecting...");
    setTimeout(() => {
      location.reload(); // Simple reconnection strategy
    }, 5000);
  };
</script>

Available Options

Parameter	Type	Default	Description
`container`	`string`	Required	The HTML element ID where the mindmap will be loaded
`mindmapId`	`string`	Required	The unique ID of the mindmap
`token`	`string`	Required	Authentication token
`width`	`string`	`"100%"`	Width of the container (supports `%` or `px`)
`height`	`string`	`"600px"`	Height of the container
`zoom`	`number`	`1`	Zoom level (`1.0` = default, `1.5` = 150%)

WebSocket Reconnection Strategy

If the WebSocket connection drops, implement an exponential backoff reconnection strategy:

<script>
  let retryCount = 0;

  function connectWebSocket() {
    const socket = new WebSocket("wss://orthogramic.com/ws/mindmap");

    socket.onopen = function() {
      retryCount = 0;
      socket.send(JSON.stringify({
        action: "subscribe",
        mindmapId: "12345",
        token: "abc123"
      }));
    };

    socket.onmessage = function(event) {
      const data = JSON.parse(event.data);
      if (data.update) {
        OrthogramicMindmap.render({
          container: "mindmap-container",
          mindmapId: data.mindmapId,
          token: "abc123",
          theme: "dark"
        });
      }
    };

    socket.onclose = function() {
      console.log("WebSocket closed. Reconnecting...");
      retryCount++;
      setTimeout(connectWebSocket, Math.min(1000 * 2 ** retryCount, 30000)); // Exponential backoff
    };
  }

  connectWebSocket();
</script>

Choosing the right method

Feature	`<iframe>`	JavaScript SDK
Easy to integrate	✅ Yes	❌ Requires JavaScript
Dynamic updates	❌ No	✅ Yes
Custom styling	❌ Limited	✅ Full control
Real-time support	❌ No	✅ Yes
Secure authentication	❌ Token in URL	✅ Backend token retrieval

Use <iframe> if you need a quick embed with minimal setup.
Use the SDK if you need dynamic content, real-time updates, and full control.

Support & troubleshooting

For issues, contact support@orthogramic.com