React SDK

Overview

Application Embed is used to render specific, custom applications that you have built on the UnifyApps platform. This is ideal for displaying data-driven UIs, forms, or dashboards to your end-users within your product or a third-party platform.

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

Installing on restricted networks: If corporate network policies prevent dependency resolution from npm or JFrog (for example, access to registry.npmjs.org is blocked), standard installation fails. Ask support@unifyapps.com for a .tar package of the SDK, which you can install locally without external registry access.

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 SESSION_ENDPOINT = '<HOST_NAME>/auth/createUserExternalLoginSession';
  const AUTH_TOKEN = '<AUTH_TOKEN>';
  const data = {
    identityProviderId: '<IDP_ID>',
    formData: {
      username: '<USER_NAME>',
      name: '<NAME>',
      email: '<USER_EMAIL>',
    },
  };
  // Example data: {identityProviderId: '123456789', formData: {username: 'user', name: 'Full name', email: 'user@domain.com'}}
  // Make a POST request to create a user session
  async function makeRequest(applicationId: string) {
    try {
      const response = await fetch(SESSION_ENDPOINT, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${AUTH_TOKEN}`,
          'Content-Type': 'application/json',
          'x-ua-app': applicationId,
        },
        body: JSON.stringify(data),
      });
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      const responseData = await response.json();
      // Example responseData: {"sessionId":"<SESSION_ID>"}
      console.log('Success:', responseData);
      return responseData;
    } catch (error) {
      console.error('Error:', error);
    }
  }
  // Pass this sessionId to the UAProvider options in the token field
  const { sessionId: SESSION_ID } = await makeRequest(applicationId);

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>

For how AUTH_TOKEN, IDP_ID and the session ID fit together, see the Authentication overview.

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>',
  isApplicationPublic: false, // true for a Public application
  theme: '<THEME>'
};
// Example: {host: 'https://prod.unifyapps.com', token: '123456789', identityProviderId: '123456789'}
const webApplicationProps = {
  applicationId: '<APPLICATION_ID>',
  initialPageId: '<PAGE_ID>',
  initialPageInputs: { <INPUT_NAME>: '<INPUT_VALUE>' },
  onPageEvent: async ({eventType, eventPayload}) => { return Promise.resolve() },
};
// Example: {applicationId: 'my_app'}
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 - Takes an options object:

• host (required) - The base URL of the host application.

• token (optional) - The temporary session id to authenticate the user.

• identityProviderId (optional) - Identity provider, required for authentication.

• isApplicationPublic (optional) - Set to true if the application is public. Default is false (private application).

• theme (optional) - Theme to be set for the application. Available themes are light, dark, system. Default is light.

WebApplication - Renders application made via UnifyApps platform. Props:

• applicationId (required) - Application ID: The unique identifier of the application. Retrieve this from the application's overview page in UnifyApps platform.

• initialPageId (optional) - The page to open first. Use the page's Page Slug from the application's page settings.

• initialPageInputs (optional) - An object with the page inputs required to render the application's page, for example { inputA: 1, inputB: "abc" }.

• onPageEvent (optional) - Callback for page events, called with { eventType, eventPayload }. It should return a Promise; an async function does this.

• ref (optional) - A React ref that exposes goToPage({ pageId, pageInputs, mergeWithExistingPageInputs }) to navigate to another page of the application from your code.

pageId and pageInputs on WebApplication are deprecated. Use initialPageId and initialPageInputs instead.

Navigate from Your Code

To move the embedded application to another page after it renders, attach a ref to WebApplication and call goToPage:

import React, { useRef } from 'react';
import { UAProvider, WebApplication } from '@unifyapps/sdk-react';
const App = () => {
  const appRef = useRef(null);
  // Navigate the embedded application to another page
  const openDetails = () => {
    appRef.current?.goToPage({
      pageId: '<PAGE_ID>',
      pageInputs: { <INPUT_NAME>: '<INPUT_VALUE>' },
    });
  };
  return (
    <UAProvider options={options}>
      <button onClick={openDetails}>Open details</button>
      <WebApplication ref={appRef} applicationId="<APPLICATION_ID>" initialPageId="<PAGE_ID>" />
    </UAProvider>
  );
};

Set mergeWithExistingPageInputs: true to merge the new inputs with the current page inputs instead of replacing them.