> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/developers/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Toolkit API reference

> Explore the Cobo UI Toolkit API for efficient app development. Access hooks, functions, and types for seamless integration.

## Types

### AuthInfo

The authentication information of a user.

#### Properties

| Name              | Type   | Description                                                |
| ----------------- | ------ | ---------------------------------------------------------- |
| token             | string | The [User Info Token](/v2/apps/verify-users).              |
| orgID             | string | The user's organization ID.                                |
| userID            | string | The user ID.                                               |
| (Optional) action | string | The current operation type. You can ignore this parameter. |

### MfaListItem

The information about a multi-factor authentication (MFA) method that will be displayed in the UI.

#### Properties

| Name      | Type   | Description                                                                                                                                                                                                                                                                                                             |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mfaMethod | string | The MFA method type. The possible values are as follows:<ul><li>`google_auth`: Google Authenticator.</li><li>`cobo_guard`: Cobo Guard.</li><li>`security_key`: Security keys.</li></ul> For more details, refer to [Set up multi-factor authentication (MFA) methods](https://manuals.cobo.com/en/accounts/set-up-mfa). |
| mfaStatus | string | The active status of the MFA method. The possible values are as follows:<ul><li>`Active`: The MFA method will be displayed as enabled in the UI.</li><li>`Inactive`(default): The MFA method will be displayed as disabled in the UI.</li></ul>Any other values will be treated as `Inactive`.                          |

## Enums

### locale

The language setting.

* `en-US`: English.
* `zh-CN`: Chinese.

## Hooks

### useMFA

```typescript theme={null}
const useMFA: () => (mfaMethods: MfaListItem[]) => Promise<string>;
```

This hook manages multi-factor authentication (MFA) methods within your application. It provides a function to send MFA method data to Cobo for processing.

#### Returns

This hook returns a function `sendMfaMethods` that sends an array of MFA methods to Cobo's backend.

The `sendMfaMethods`function has the following parameter:

| Name       | Type            | Description                                                                                                             |
| ---------- | --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| mfaMethods | MfaListItem \[] | An array of [MfaListItem](#mfalistitem) objects. Each object represents an MFA method that will be displayed in the UI. |

The `sendMfaMethods` function returns a Promise that resolves to a request ID of string type, which should be sent to Cobo Portal for processing.

#### Sample code

The following example defines an array of MFA methods, sends them using `sendMfaMethods`, and handles the response or any errors.

```typescript theme={null}
import React, { useEffect } from 'react';
import { useMFA } from '@cobo/cobo-ui-toolkit';

const MyComponent = () => {
 const { sendMfaMethods } = useMFA();
 const testMFA = async () => {
  const mfaMethods = [
   { mfaMethod: "google_auth", mfaStatus: "Active" },
   { mfaMethod: "cobo_guard", mfaStatus: "Active" },
   { mfaMethod: "security_key", mfaStatus: "Active" },
  ];
  try {
   const requestId = await sendMfaMethods(mfaMethods);
   console.log('Request ID:', requestId);
  } catch (error) {
   console.error('Error sending MFA methods:', error);
  }
 };

 useEffect(() => {
  testMFA();
 }, []);
 return <div>Check console for request ID.</div>;
};

export default MyComponent;
```

### useTrackingScript

```typescript theme={null}
const useTrackingScript: (env: "production") => void;
```

This hook injects a tracking script into the DOM, which collects data for app analytics, and ensures proper cleanup when the component unmounts. This data will be accessible on Developer Console in the future.

#### Parameters

| Name | Type   | Description                                                                                                                                                                                                                                                                           |
| ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| env  | string | The type of environment in which your app runs. For more details, refer to [environments](/v2/guides/overview/environments).<br />Currently, this parameter value must be `production`, regardless of whether your app runs in the production environment or development environment. |

#### Sample code

The following example loads a tracking script in both the production and development environments.

```typescript theme={null}
import React from 'react';
import { useTrackingScript } from '@cobo/cobo-ui-toolkit';

const MyApp = () => {
  useTrackingScript('production');
  return <h1>Hello world</h1>;
};

export default MyApp;
```

#### Notes

To enable effective tracking, each clickable element in your app needs a unique tracking attribute named `data-track-id` or `dtid`. This attribute serves as the primary identifier for tracking interactions on specific buttons or elements, enabling consistent and accurate analytics collection.

Each `data-track-id` or `dtid` attribute value must be lowercase words separated by underscores in the format `{PAGE_IDENTIFIER}_{COMPONENT_IDENTIFIER}_{ELEMENT_IDENTIFIER}` that follow the following rules:

* Page identifier: Identifying the page or module's feature, including `home`, `login`, and `profile`.
* Component identifier: Identifies the specific UI component within the page, including `form`, `navbar`, `modal`, `search_bar`, `button`, `banner`, `icon_button`, `tab`, `switch_button`, `checkbox`, `radio`, `sidebar`, `footer`, `header`, and `link`.
* Element identifier: Identifies the button or interactive element, including `submit`, `register`, and `next_step`.

For example, the attribute value for a submit button on the home page can be `home_form_submit`.

When an element contains child elements, avoid using event-blocking methods such as `stopPropagation()` and `preventDefault()` because they can interfere with effective click tracking. In typical cases, you only need to apply the `data-track-id` or `dtid` attribute to the parent element, as child elements will automatically inherit it for tracking purposes.

The following example shows how to implement this:

```html theme={null}
<button data-track-id="home_form_submit">
  <span>Child Element 1</span>
</button>
```

However, if using the event-blocking methods is necessary, ensure that each child element within the parent has the same tracking attribute to maintain accurate tracking.

**Input field collection rules**

For input fields with a `data-track-id`, the user input and the value of `data-track-id` will be collected for analyzing user behavior.

In the following example, the keywords entered by the user and the value of `home_search_bar_wallet` will be collected.

```html theme={null}
<input type="text" data-track-id="home_search_bar_wallet" placeholder="Enter keywords" />
```

For sensitive information such as passwords and personal identification information, you can mark an input field as containing sensitive information by using `data-track-sensitive="true"`, which will tell the tracking script to automatically ignore the data and not collect it.

In the following example, the password entered by the user will not be collected by the tracking script.

```html theme={null}
<input type="password" data-track-id="login_form_password" data-track-sensitive="true" placeholder="Enter your password" />
```

If an input field is nested within other components (such as a form), the parent `data-track-id` will not override or replace the input field's own `data-track-id`.

In the following example, the `data-track-id` of the input field is `login_form_email`, not `login_form`.

```html theme={null}
<form data-track-id="login_form">
   <input type="text" data-track-id="login_form_email" placeholder="Email" />
</form>
```

### useAddUidToBody

```typescript theme={null}
const useAddUidToBody: (userId: string) => void;
```

This hook converts a specified user ID from string to Base64 format and adds it as a `uid` attribute to the `<body>` tag of the HTML document. It is useful in scenarios where a user ID needs to be incorporated into the document structure for global tracking or analytics.

#### Parameters

| Name   | Type   | Description                                  |
| ------ | ------ | -------------------------------------------- |
| userId | string | The user ID to be added to the `<body>` tag. |

#### Sample code

The following example uses the `useAddUidToBody` function to add a `uid` attribute to the `<body>` tag with the user ID. When the user ID changes, the value of the `uid` attribute is updated accordingly.

```typescript theme={null}
import React from 'react';
import { useAddUidToBody } from '@cobo/cobo-ui-toolkit';

const UserProfile = () => {
  const userId = 'user123';

  useAddUidToBody(userId);

  return (
    <div>
      <h1>Hello,user {userId}</h1>
    </div>
  );
};

export default UserProfile;
```

## Functions

### getAuthInfo

```typescript theme={null}
type AuthInfo = {
    token: string;
    orgID: string;
    userID?: string;
};
const getAuthInfo: () => Promise<AuthInfo | undefined>;
```

This asynchronous function retrieves user authentication information from [Cobo Portal](https://manuals.cobo.com/en/portal/introduction).

#### Returns

* `Promise<[AuthInfo]>`: For more details, refer to [AuthInfo](#authinfo).
* `undefined`: The authentication information is unavailable or the request fails.

#### Sample code

The following example retrieves user authentication information using the `getAuthInfo` function when the component mounts and displays that information.

```typescript theme={null}
import React, { useEffect, useState } from 'react';
import { getAuthInfo } from '@cobo/cobo-ui-toolkit';

const UserProfile = () => {
  const [authInfo, setAuthInfo] = useState<AuthInfo | undefined>(undefined);

  useEffect(() => {
    const fetchAuthInfo = async () => {
      const info = await getAuthInfo();
      setAuthInfo(info);
    };

    fetchAuthInfo();
  }, []);

  if (!authInfo) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <h1>User Information</h1>
      <p>Token: {authInfo.token}</p>
      <p>Organization ID: {authInfo.orgID}</p>
      {authInfo.userID && <p>User ID: {authInfo.userID}</p>}
    </div>
  );
};

export default UserProfile;
```

### parseJwtToken

```typescript theme={null}
const parseJwtToken: (token: string) => any;
```

This function parses a JSON Web Token (JWT) and returns the payload as a JSON object. Use this function to extract user information, permissions, and other related information in a JWT.

You can use this function to parse the [User Info Token](/v2/apps/verify-users), which contains the information of a Cobo Portal App user.

#### Parameters

| Name  | Type   | Description                                                                       |
| ----- | ------ | --------------------------------------------------------------------------------- |
| token | string | The JWT string to be parsed. It must be in the `header.payload.signature` format. |

#### Returns

If the token is a valid JWT, the function returns the payload as a JSON object.

#### Errors

If the token format is incorrect or cannot be parsed, the function throws an error with messages such as:

* `Invalid Base64 encoding`: The payload part of the token is not properly Base64 encoded.
* `Invalid token format`: There is an issue parsing the token, for example, incorrect structure or failure to decode.

#### Sample code

The following example uses the `parseJwtToken` function to parse a User Info Token and logs the decoded payload to the console.

```typescript theme={null}
import { parseJwtToken } from '@cobo/cobo-ui-toolkit';

const token =
  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

try {
  const payload = parseJwtToken(token);
  console.log(payload);
} catch (error) {
  console.error(error.message);
}
```

### verifyJwtToken

```typescript theme={null}
const verifyJwtToken: (token: string, publicKeySet: any) => Promise<boolean>;
```

This function verifies a JSON Web Token (JWT) using the specified public keys, ensuring that the token has not been tampered with and is valid.

You can use this function to verify a Cobo Portal App user's identity. Refer to [User Info Tokens](/v2/apps/verify-users) for more information.

#### Parameters

| Name         | Type   | Description                                                                                                                                                |
| ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token        | string | The JWT to be verified. It must be in the `header.payload.signature format`.                                                                               |
| publicKeySet | any    | A set of public keys used to verify the JWT signature. Each public key should have a `kid` attribute, which matches the `kid` attribute in the JWT header. |

#### Returns

* `true`: The JWT is valid.
* `false`: The JWT is invalid.

#### Sample code

The following example verifies a User Info Token with the public key set retrieved from the specified URL. If the verification is successful, it extracts the information from the User Info Token and sets the information as the user's information.

```typescript theme={null}
import { parseJwtToken, verifyJwtToken } from '@cobo/cobo-ui-toolkit';

get('https://api.dev.cobo.com/v2/oauth/authorize/jwks.json').then(async (res) => {
  const verified = await verifyJwtToken(token, res);
  if (!verified) return;
  const jwtInfo = parseJwtToken(token);
  setUserInfo({
    email: jwtInfo.email,
    roleNames: jwtInfo.role_names,
    roles: jwtInfo.roles,
    sub: jwtInfo.sub,
  });
});
```

### getPortalLocale

```typescript theme={null}
type Locale = {

  locale: 'en-US' | 'zh-CN';

};
const getPortalLocale: (callback: (data: Locale) => void) => void;
```

This function listens for the current locale data of [Cobo Portal](https://manuals.cobo.com/en/portal/introduction) and executes a callback when the locale data updates.

<Note>Call [removeGetLocaleListener](#removegetlocalelistener) to clean up the listener when it is no longer needed, especially in components that may unmount.</Note>

#### Parameters

| Name     | Type     | Description                                                      |
| -------- | -------- | ---------------------------------------------------------------- |
| callback | function | A function that takes a [locale](#locale) object as an argument. |

#### Returns

`void`

#### Errors

`Failed to get locale`: The locale data is undefined.

#### Sample code

The following example listens for the locale data of Cobo Portal and logs it to the console when the data updates.

```typescript theme={null}
import { getPortalLocale } from '@cobo/cobo-ui-toolkit';

import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';

<WaasSkillReminder />

useEffect(() => {
  getPortalLocale((locale) => {
    console.log("locale", locale);
  });
}, []);
```

### removeGetLocaleListener

```typescript theme={null}
const removeGetLocaleListener: () => void;
```

This function removes the listener for the current locale data of [Cobo Portal](https://manuals.cobo.com/en/portal/introduction).

After you call [getPortalLocale](#getportallocale) to listen to the locale data, use this function to clean up the listener when it is no longer needed, especially in components that may unmount.