Platform iFrame

Overview

Use an iFrame to embed a UnifyApps platform module, such as the Automation Manager, Connection Manager, Application Manager or Connectors, in your own web page without installing an SDK. The frame signs the visitor in with a session ID and then opens the module.

To embed a page of an application you built in UnifyApps, see Application iFrame. For a component that manages the frame for you, use the Platform JavaScript SDK or React based Embed.

Step-by-Step Instructions

Step 1: Get Required Parameters

• HOST_NAME – your UnifyApps environment's domain, the address you sign in to. For example, https://platform.unifyapps.com.

• AUTH_TOKEN and IDP_ID – request these from support@unifyapps.com. Keep AUTH_TOKEN on your server.

For how these values fit together, see the Authentication overview.

Step 2: Create a Session on Your Server

For each visitor, call the session endpoint from your server. It needs your AUTH_TOKEN, so never call it from the browser.

// Run this on your server, never in the browser
const response = await fetch('<HOST_NAME>/auth/createUserExternalLoginSession', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <AUTH_TOKEN>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    identityProviderId: '<IDP_ID>',
    formData: {
      username: '<USER_NAME>', // a stable ID for this visitor
      name: '<NAME>', // optional
      email: '<USER_EMAIL>', // optional
    },
  }),
});
// Response: { "sessionId": "<SESSION_ID>", "redirectUrl": "..." }
const { sessionId } = await response.json();

The session ID works once and expires about 2 minutes after it's created, unless your identity provider is set to a longer time. Create it when your page loads and use it straight away.

Step 3: Build the Frame URL

The frame opens a sign-in address that exchanges the session ID for a signed-in session, then redirects to the module path you pass in returnTo:

<HOST_NAME>/auth/external/login/<IDP_ID>/<SESSION_ID>?returnTo=<MODULE_PATH>

Step 4: Add the iFrame to Your Page

Put the frame URL from Step 3 in src:

<iframe
  id="unifyapps-embed"
  title="UnifyApps"
  src="<FRAME_URL>"
  style="border: none; width: 100%; height: 800px;"
></iframe>

Change the height to fit your layout.

Your website's origin must be allowed to embed your UnifyApps environment. If the frame stays blank, or the browser console says framing was refused, contact support@unifyapps.com to have your origin allowed.

Step 5: Verify the Integration

1. Open your page. The module loads, already signed in as the visitor.

2. If the UnifyApps sign-in page appears instead, the session ID was already used or has expired. Create a new one and reload.

3. If the frame is blank, check the browser console for a framing (frame-ancestors) error.

Keep Navigation in Sync

The embedded module tells your page when its route changes, and your page can send it to another route. Both directions use postMessage:

• Navigation events: on each route change, the module posts { source: 'unifyapps', type: 'UNIFYAPPS__EMBEDDED_EVENT', data: '<path and query string>' } to your page.

• Router commands: post { source: 'unifyapps', type: 'router', data: { path, method } } to the frame. method is push, replace or back.

Store the module's route in your page's URL, and accept messages only from your UnifyApps host:

const UA_ORIGIN = new URL('<HOST_NAME>').origin;
window.addEventListener('message', (event) => {
  if (event.origin !== UA_ORIGIN) return; // ignore messages from other windows
  if (event.data?.source === 'unifyapps' && event.data.type === 'UNIFYAPPS__EMBEDDED_EVENT') {
    const url = new URL(window.location.href);
    url.searchParams.set('uaPath', event.data.data);
    history.replaceState({}, '', url);
  }
});

When your page loads again, read the saved uaPath and use it as returnTo in Step 3, so the frame reopens on the same route. To move the module from your own code, for example from a button, send a router command:

document.getElementById('unifyapps-embed').contentWindow.postMessage(
  { source: 'unifyapps', type: 'router', data: { path: '/p/0/connections', method: 'push' } },
  UA_ORIGIN,
);