@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> | {} |