How to: Integrate App with Console UI using React.JS
The Console UI SDK enables developers to incorporate Console UI components into their applications, enabling features like authentication, headers, sidebars, modals, and more to offer a seamless app access and navigation experience to their end users.
For more information about the benefits of Console UI, see Console UI Overview.
This guide walks through the integration of Console UI SDK with your application using React.JS library.
To get started, developers need to install the console-ui-react package. This package contains all the necessary components and utilities for the integration.
To install the package, navigate to your project directory in your terminal and run the following command:
This command adds the Console UI SDK to your project’s dependencies, allowing developers to import and use it within their application.
📘 Update Console Version
You can also run the npm install @os1-platform/console-ui-react command to update Console to the latest version.
To begin the integration process, developers need to import the OS1Provider function from the library. OS1Provider is a context provider that allows child components to access the Console UI features.
📘 Retrieve credentials
Refer to the Getting Started with OS1 Platform for documentation for retrieving your credentials.
This code block does several things:
- It imports the OS1Provider function which provides the SDK functionality.
- It enables authentication by setting the clientID, loginRedirectPath, and logoutRedirectPath.
- It uses the Initiate function to set the Console UI Instance.
After importing the OS1Provider, you’ll need to pass a function as a prop to your application with a setState method. The Console UI context enables developers to use the Console UI’s state in their client application. This state is essential to manage user sessions, permissions, navigation, and other UI elements.
To use the Console UI context, create a component that uses the ConsoleUIContext and sets its state.
See the example below to create a component:
In this component:
- The ConsoleUIContext is accessed during the React.useContext` hook.
- If a Console UI instance is present, it’s set as the state of the component, allowing it to use the Console UI.
For an application to communicate with the backend services, developers need to establish a network client. The Console UI SDK provides the OS1HttpClient API for this purpose. This helps to create an instance of the network client with the necessary configurations and authentications.
In the code snippet above, the OS1HttpClient function accepts the base URL for your API endpoints as well as an instance name. This setup allows your application to handle all API interactions via the instance object.
Developers can use toast notifications to show transient, non-disruptive messages to their end users. This enables apps to quickly notify users of successful operations, pending tasks, or potential errors. Developers can use the OS1Toast function from the SDK to use this feature in their web application.
Each toast element should have a unique elementID. This allows developers to manage multiple toast notifications effectively and ensures that they can control each notification individually when required. ConsoleInstance is the instance of Console UI that is being used in the client app to use Console UI features.
Developers can use modals for obtaining user confirmation, providing important information, or capturing user input. To integrate a modal component in your application, use the OS1Modal function from the SDK. See the example code below:
Listen for the event when a button is clicked; event.details will contain the modal element ID.
You can include up to three injectable controls, but each must have a unique ID.
Developers can listen for events emitted by injectable controls using the ConsoleUIContext state variable. This enables your application to respond to user actions and deliver interactive experiences.
Customizing Console Settings can help developers integrate their applications effectively and ensure a streamlined interaction with the Console UI.
To securely communicate with the Console UI, the TheNetworkClient automatically configures the following headers for requests:
- x-coreos-access (Access token)
- x-coreos-tid (Tenant ID)
- x-coreos-userinfo (User info)
- x-coreos-auth (Auth token)
These headers act as work with the Console UI’s backend, passing essential authentication information with each API request. To manage these headers, the OS1 SDK provides the following options.
Request headers are an integral part of securing and identifying requests made to the API. By default, all headers are active (true). To exclude a specific header, set its value to false.
Remember that the x-coreos-access token is checked and refreshed (if expired) for each aPI request. The x-coreos-userinfo and x-coresos-auth headers contain the USER ID and ID token respectively.
Use REST API methods, on the instance created for OS1HttpClient
See the sample code below for configuring request headers:
- convertTime: Converts the time in your application to your desired format.
- currentTimeZone: Returns the current timezone stored in the browser.