App Embed

Javascript

Overview

This guide provides step-by-step instructions to embed your application using a JavaScript snippet. Follow the steps below to integrate the UnifyApps SDK into your webpage.

Step-by-Step Instructions

Step 1 : Get Required Parameters

• HOST_NAME The host name is the URL where the platform application is hosted.
  Example: If the platform is hosted at https://platform.unifyapps.com, then the host is:

  https://platform.unifyapps.com

• Generate ACCESS_TOKEN (Session ID) Make an authentication request using Node.js:

  const URL = '<HOST_NAME>/auth/createUserExternalLoginSession';
  const AUTH_TOKEN = '<AUTH_TOKEN>'; 
  
  const data = {
    identityProviderId: '<IDP_ID>',
    formData: {
      username: '<USER_NAME>',
      name: '<NAME>',
      email: '<USER_EMAIL>',
    },
  };
  
  async function makeRequest() {
    try {
      const response = await fetch(URL, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${AUTH_TOKEN}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(data),
      });
  
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
  
      const responseData = await response.json();
      console.log('Success:', responseData);
      return responseData;
    } catch (error) {
      console.error('Error:', error);
    }
  }
  
  // Fetch session ID
  const { sessionId } = await makeRequest();

Step 2: Obtain Credentials

To obtain the required credentials, contact support@unifyapps.com for:

• HOST_NAME

• AUTH_TOKEN

• IDP_ID

Step 3: Copy the JavaScript Snippet

Copy the following JavaScript snippet and paste it into your HTML file:

<
script
>
    window.unifyAppsSettings = {
        host: '<HOST_NAME>',
        token: '<SESSION_ID>',
        identityProviderId: '<IDP_ID>',
        applicationId: '<APPLICATION_ID>',
        pageId: '<PAGE_ID>',
        pageInputs: '<PAGE_INPUTS>',
        containerEl: '<CONTAINER_ELEMENT>',
    };
    (function() {
        var w = window,
            ua = w.UnifyApps;
        if (typeof ua === 'function') {
            ua('update', w.unifyAppsSettings);
        } else {
            var d = document,
                u = function() {
                    u.c(arguments);
                };
            u.q = [];
            u.c = function(args) {
                u.q.push(args);
            };
            w.UnifyApps = u;
            w.UnifyApps('init');
            var l = function() {
                var s = d.createElement('script');
                s.type = 'text/javascript';
                s.async = true;
                s.src = window.unifyAppsSettings.host + '/lib/delta-matrix/ua-web-sdk.js';
                var x = d.getElementsByTagName('script')[0];
                x.parentNode.insertBefore(s, x);
            };
            if (document.readyState === 'complete') {
                l();
            } else if (w.attachEvent) {
                w.attachEvent('onload', l);
            } else {
                w.addEventListener('load', l, false);
            }
        }
    })();
</
script
>

Step 4: Configure the Required Parameters

Replace the placeholders in the script with the actual values.

• Required Parameters:

  • host – The base URL of the host application.

  • token – A temporary session ID used for authentication.

  • identityProviderId – The identity provider ID needed for authentication.

  • applicationId – The unique identifier of your application (retrievable from the UnifyApps platform overview page).

• Optional Parameters:

  • pageId – The unique identifier for a specific page within the application, used to designate the overview page. This can be retrieved from the application's page.
    Example: pageId: 'Homepage'

  • pageInputs – An object containing the necessary inputs required to render the application's page. Multiple page inputs can be passed at once.
    Example: pageInputs: ‘{ inputA: 1, inputB: 2, inputC: "abc" }’

  • containerEl – The HTML element where the application should be rendered (defaults to <body> if not provided).
    Eg. - document.getElementById("container");

Step 5: Verify the Integration

• Open the HTML file in a browser.

• Ensure that the application loads correctly inside the specified container.

• If any issues arise, check the browser console for errors.

UnifyApps SDK Methods

• UnifyApps ('update', updatedUnifyAppsSettings) - To update any of UnifyApps global settings

• UnifyApps ('goToPage', {pageId, pageInputs}) - To change pageId or pageInputs use this method. In case of copilot chat, if the chat is closed when the method is called, it will be opened first and then the corresponding navigation updates will be made.

• Copilot Chat specific methods:

  • UnifyApps('show') - Open the copilot chat

  • UnifyApps('hide') - Close the copilot chat, launcher will still be visible(if configured)

React SDK

Overview

This section provides instructions to embed your application using the UnifyApps SDK React package. This method is ideal for React applications and provides a more modular approach.

Step-by-Step Instructions

Step 1: Install the Package

Run the following command to install the UnifyApps React SDK:

npm install @unifyapps/sdk-react

Step 2: Get Required Parameters

• HOST_NAME The host name is the URL where the platform application is hosted.
  Example: If the platform is hosted at https://platform.unifyapps.com, then the host is:
  

  https://platform.unifyapps.com

• Generate ACCESS_TOKEN (Session ID) Make an authentication request using Node.js:
  

  const URL = '<HOST_NAME>/auth/createUserExternalLoginSession';
  const AUTH_TOKEN = '<AUTH_TOKEN>'; 
  
  const data = {
    identityProviderId: '<IDP_ID>',
    formData: {
      username: '<USER_NAME>',
      name: '<NAME>',
      email: '<USER_EMAIL>',
    },
  };
  
  async function makeRequest() {
    try {
      const response = await fetch(URL, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${AUTH_TOKEN}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(data),
      });
  
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
  
      const responseData = await response.json();
      console.log('Success:', responseData);
      return responseData;
    } catch (error) {
      console.error('Error:', error);
    }
  }
  
  // Fetch session ID
  const { sessionId } = await makeRequest();

Step 3: Obtain Credentials

To obtain the required credentials, contact support@unifyapps.com for:

• HOST_NAME

• AUTH_TOKEN

• IDP_ID

• NPM Access Details - A token will be provided to enable you to download the NPM package.

  • Create a .npmrc  file and add this code, and replace <TOKEN> with given token from unifyapps team

@unifyapps:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=<TOKEN>

Step 4: Import and Configure the SDK

Create a React component that renders the application using UAProvider and WebApplication.

import React from 'react';
import ReactDOM from 'react-dom';
import { UAProvider, WebApplication } from '@unifyapps/sdk-react';

const options = {
  host: '<HOST_NAME>',
  token: '<SESSION_ID>',
  identityProviderId: '<IDP_ID>',
};

const webApplicationProps = {
  applicationId: '<APPLICATION_ID>',
  pageId: '<PAGE_ID>',
  pageInputs: '<PAGE_INPUTS>',
};

const App = () => (
  <
UAProvider
 options={options}>
    <
WebApplication
 {...webApplicationProps} />
  </
UAProvider
>
);

ReactDOM.render(<
App
 />, document.getElementById('root'));

Step 5: Configure Required Parameters

Replace the placeholders with actual values:

• UAProvider Props:

  • host – The base URL of the host application.

  • token – A temporary session ID for authentication.

  • identityProviderId – The identity provider ID needed for authentication.

• WebApplication Props:

  • applicationId – The unique identifier of the application.
    This can be retrieved from the application's overview page.
    Eg.- applicationId: 'App-xyz',

  • pageId (optional) – The unique identifier for a specific page within the application, used to designate the overview page. This can be retrieved from the application's page.
    Example: pageId: 'Homepage'

  • pageInputs – An object containing the necessary inputs required to render the application's page. Multiple page inputs can be passed at once.
    Example: pageInputs: ‘{ inputA: 1, inputB: 2, inputC: "abc" }’

iFrame

Overview

The iFrame embedding method allows you to integrate your UnifyApps      application into any external website by inserting an <iframe> tag.

Step-by-Step Instructions

Step 1: Get Required Parameters

• HOST_NAME The host name is the URL where the platform application is hosted.
  Example: If the platform is hosted at https://platform.unifyapps.com, then the host is:

  https://platform.unifyapps.com

• Generate ACCESS_TOKEN (Session ID) Make an authentication request using Node.js:

Step 2: Obtain Credentials

To obtain the required credentials, contact support@unifyapps.com for:

• HOST_NAME

• AUTH_TOKEN

• IDP_ID

Step 2: Copy the iFrame Snippet

Copy the following iFrame snippet and paste it into your HTML file:

<
iframe
 id="unifyapps-embed" src="URL" 
width="100%" height="1000" scrolling="no" frameborder="0" style="border:none;"></
iframe
>

Step 3: Embed in Your Website

Paste the modified iFrame code into any webpage where you want to embed the UnifyApps application.

Step 4: Verify the Integration

• Open the webpage and check if the embedded page loads correctly.

• Inspect the browser console for any errors if issues arise.

Best Practices

1. Generate a session ID by creating an authentication token for UnifyApps on the server side, behind your local authentication system

2. Maintain separate environments for production and development, and configure them to point to their respective UnifyApps environments.