@bigid/app-fw-ui-sdk

This is an official BigID Apps SDK

The main purpose of the SDK is to enable communication with BigID UI and harvest some of its functionality. Some of the methods available in the SDK promotes a much more holistic UI experience.

Install

yarn add @bigid/app-fw-ui-sdk

Alternative Installation Method

<script src="https://unpkg.com/@bigid/app-fw-ui-sdk/lib/package.min.js"></script>

You may also add the SDK to your application using a script tag pointing to the lib/package.min.js file. This will expose the SDK to your application under a global variable named BigID. For example:

BigID.sdk.getApiUrl().then(function(ApiUrl) {
  console.log("Your API URL is: " + ApiUrl);
}

SDK supported topics

Bigid UI SDK let the developer the ability to read topics from bigid and take an action by implementing an topic reader that will handle the supported topic. Each topic reader should return a promise that will be transferred to the SDK for further treatment. The SDK will wait for 20 seconds before returning a default response. (Only if the app doesn't return one)

ParentTopic	Description	Return type
USER_NAVIGATE_OUT	Notice the developer that the user is about to navigate out of the app.	true - BigID keep the navigation, false - stay in app

Topic use example:

import { ParentTopic, topicHandler } from '@bigid/app-fw-ui-sdk';

useEffect(() => {
  const waitTenSecBeforeNavigate = async () => await new Promise(resolve => setTimeout(resolve, 10000));
  const navigateOutTopic = topicHandler.onTopic(ParentTopic.USER_NAVIGATE_OUT, waitTenSecBeforeNavigate);
  
  return (() => navigateOutTopic());
}, []);

SDK methods

Method	Description
getToken	Retrieve the user token
getUsername	Retrieve the bigid username
getPermissions	Retrieve an array fo the current user permissions (related to the app and the user)
getBffUrl	Retrieve the BFF url
getApiUrl	Retrieve the BigID API endpoint for server to server requests
getRouteParams	Retrieve the current BigID UI route Params
openDialog	Opens the BigID UI dialog component (On top of the hosted app)
bigidAPI	Enable using the BigID API directly from the UI
changeRoute	Change the BigID UI route
hidePageHeader	Hides the header of the custom app page for full screen mode
sendDataLakeEvent	Sending an event named "apps_sdk" to the data lake

SDK use example:

import { sdk } from '@bigid/app-fw-ui-sdk';

const response = await sdk.bigIdAPI({
  path: 'data-catalog',
  method: 'get',
  params: {
    format: 'json',
    limit: '5',
    filter: 'note',
  },
});

if (response.data === []) {
  await sdk.changeRoute({ url: 'dashboard' });
}

getToken

Use this method when you need to use BigID API via your BFF layer. Note that you should send the token to your server for the request to get authorized.

//This is an example for a common scenario in an 'interactive' flagged app.
// In this type of apps there is a BFF (Backend For Frontend) layer.
// The app don't always knows the BigID API address nor the BFF API address so it should retrieve it from the SDK as well

import { sdk } from '@bigid/app-fw-ui-sdk';

const bigIdToken = await sdk.getToken();
const apiUrl = await sdk.getApiUrl();
const bffUrl = await sdk.getBffUrl();

//Request example
const res = await fetch(`${bffUrl}/api/getCatalogData`, { headers: { 'bigid-token': bigIdToken, 'api-url': apiUrl } });
//In your BFF retrieve the bigid-token and the api-url headers value and use it to query BigID API.

getUsername

Use this method when you need the BigID username.

import { sdk } from '@bigid/app-fw-ui-sdk';
const username = await sdk.getUsername();
console.log(username);

getPermissions

Retrieves the relevant permissions according to user roles and appId

import { sdk } from '@bigid/app-fw-ui-sdk';
const permissions = await sdk.getPermissions();

getBffUrl

Retrieves the BFF URL. This method will be used for 'interactive' flagged apps. Since the BFF URL is not known to the app, it should be retrieved via the SDK.

import { sdk } from '@bigid/app-fw-ui-sdk';
const bffUrl = await sdk.getBffUrl();

getApiUrl

Retrieves the BigID API URL. This method will be used for 'interactive' flagged apps, when the BFF should communicate with BigID API. According to the common flow, the BigID API endpoint should be retrieved via the SDK and get sent to the BFF for any API use.

import { sdk } from '@bigid/app-fw-ui-sdk';
const permissions = await sdk.getApiUrl();

getRouteParams

Retrieves the BigID UI route params

import { sdk } from '@bigid/app-fw-ui-sdk';
const params = await sdk.getRouteParams();

openDialog

Open the BigID dialog box, When the user clicks one of the buttons the button value will be resolved in the promise.

import { sdk, DialogData, DialogButton } from '@bigid/app-fw-ui-sdk';
const buttons: DialogButton[] = [
  {
    text: 'Yes I am sure',
    value: true,
    type: 'tertiary',
  },
  {
    text: 'Cancel',
    value: false,
    type: 'primary',
  },
];

const dialogData: DialogData = {
  title: 'Remove user?',
  message: 'Are you sure you want to remove this user?',
  buttons,
};
const response = await sdk.openDialog(dialogData);

console.log(response); // can be either true or false

DialogData Attributes	Type	Default
title?	string	''
message?	string	''
buttons?	DialogButton[]	[]
maxWidth?	'xs' , 'sm' , 'md' , 'lg' , 'xl' , false	lg
borderTop?	boolean	false
borderBottom?	boolean	false

DialogButton Attributes	Type	Default
text?	string	''
value?	string,boolean	''
type?	'tertiary' , 'primary'	primary

bigIdApi

Use BigID API directly from the UI, no BFF layer is needed

import { sdk, ApiRequestData, API_METHODS } from '@bigid/app-fw-ui-sdk';

const request: ApiRequestData = {
  path: 'data-catalog',
  method: API_METHODS.GET,
  params: {
    format: 'json',
    limit: '5',
    filter: 'note',
  },
};

const response = await sdk.bigIdAPI(request);

console.log(response);

ApiRequestData Attributes	Type	Default
path	string
method	API_METHODS(enum)
params?	Record<string, string>	{}
data?	Record<string, string>	{}

API_METHODS Enum	Value
GET	'get'
POST	'post'
PUT	'put'
DELETE	'delete'

changeRoute

Changes BigID UI Route

import { sdk, ChangeRouteData } from '@bigid/app-fw-ui-sdk';
const route: ChangeRouteData = { url: 'dashboard' };
await sdk.changeRoute(route);

ChangeRouteData Attributes	Type	Default
url	string
params?	Record<string, string>	{}

hidePageHeader

Use this method to hide the page header - full screen mode

import { sdk } from '@bigid/app-fw-ui-sdk';
const isHidden: boolean = true;
await sdk.hidePageHeader(isHidden);

sendDataLakeEvent

Use this method to send a bi event to the data lake

import { sdk } from '@bigid/app-fw-ui-sdk';
await sdk.sendDataLakeEvent({
    data: {
        name: 'apps adk event',
    }
});

ChangeRouteData Attributes	Type	Default
data?	Record<string, unknown>	{}