Drop-in quick start

Get started with Monite’s Drop-in web component.

Overview

The fastest way to embed Monite’s UI into your web application is to utilize the Drop-in library, which contains pre-built JavaScript web components that can be integrated into almost all types of web apps.

To learn how this can be done, follow the steps in this tutorial.

Before you begin

Before proceeding with this tutorial, make sure you completed the steps in the Step 1: Get your credentials and Step 2: Implement server side guides.

1. Open your web app or create a new one

If you already have a web application, open it in your favourite IDE.

Alternatively, you can create a new app from scratch using one of the popular bootstrapping frameworks. For example, create an empty React application using create-react-app:

1npx create-react-app my-app

Then you can open this folder in VS Code, explore its source code or type npm start in a terminal to see the app in action.

VS Code
VS Code

2. Add monite to your app

The fastest way to add monite to your app is to download monite-app.js from a CDN. Doing this requires no “build step”, as the process does not require module bundlers.

For this, locate the index.html file in your web app folder and include the following script tag within your HTML file’s body:

HTML
1<script
2  type="module"
3  async
4  src="https://cdn.sandbox.monite.com/monite-app.js"
5></script>

Alternatively, you can also use NPM or Yarn to install monite as a package:

$npm install @monite/sdk-drop-in

After installation via NPM or Yarn, you must import the SDK to use Monite’s Drop-in components in your application:

1<script type="module">
2  import "@monite/sdk-drop-in";
3</script>

3. Embed the monite-app element

The monite-app element is a custom HTML element that contains the UI and configuration for Monite’s Drop-in components.

Add the monite-app element to your application and include the required attributes:

1<monite-app
2  api-url="https://api.sandbox.monite.com/v1"
3  entity-id="ENTITY_ID"
4  component="payables"
5  basename="/"
6></monite-app>

Here, the basename parameter should be set to the base URL for all routes in your application, but you can leave it empty in this tutorial.

Note that the entity-id parameter here should be automatically set to the entity ID you generated in Step 2: Implement server side.

4: Set up user authentication

Every entity user of the Monite app should authorize themselves with a mechanism that is used in your web application. When a user is authorized by you, you should also issue an entity user token, as described in the previous Step 2: Implement server side.

If you already implemented a backend part that is capable of issuing entity user tokens, then write a function that retrieves this token and add it to the <script slot="fetch-token"> of the monite-app.

However, if you have not implemented the backend part yet but can already generate an entity and entity user token, you can also just send a POST request to the /auth/token endpoint directly from this script, as shown below:

1<script slot="fetch-token">
2  async function fetchToken() {
3    const request = {
4      grant_type: "entity_user",
5      entity_user_id: "ENTITY_USER_ID",
6      client_id: "CLIENT_ID",
7      client_secret: "CLIENT_SECRET",
8    };
9
10    const response = await fetch(
11      "https://api.sandbox.monite.com/v1/auth/token",
12      {
13        method: "POST",
14        headers: {
15          "Content-Type": "application/json",
16          "x-monite-version": "2023-09-01",
17        },
18        body: JSON.stringify(request),
19      }
20    );
21    return await response.json();
22  }
23</script>

Monite does not recommend exposing the credentials in your fetchToken function on the client side as shown earlier. For security reasons, we recommend that all Monite tokens are generated from your server-side code.

5: Review the code

Finally, you can compare your resulting code with our template to make sure that everything is correct:

1<!DOCTYPE html>
2<html lang="en">
3  <body>
4    <script type="module">
5      import "@monite/sdk-drop-in";
6    </script>
7    <monite-app
8      entity-id="ENTITY_ID"
9      api-url="https://api.sandbox.monite.com/v1"
10      component="payables"
11      basename="/"
12    >
13      <script slot="fetch-token">
14        async function fetchToken() {
15          const request = {
16            grant_type: "entity_user",
17            entity_user_id: "ENTITY_USER_ID",
18            client_id: "CLIENT_ID",
19            client_secret: "CLIENT_SECRET",
20          };
21
22          const response = await fetch(
23            "https://api.sandbox.monite.com/v1/auth/token",
24            {
25              method: "POST",
26              headers: {
27                "Content-Type": "application/json",
28                "x-monite-version": "2023-09-01",
29              },
30              body: JSON.stringify(request),
31            }
32          );
33          return await response.json();
34        }
35      </script>
36    </monite-app>
37  </body>
38</html>

(Optional) Add theming

You can customize the theme of the monite-app component. To include theming, define the object that describes the custom themes within a script tag in your file. The script tag that contains your custom theme is assigned an slot attribute with a value of theme as shown:

1<!-- Create new theme JSON -->
2<script slot="theme" type="application/json">
3  {
4    "typography": {
5      "fontFamily": "Comic Sans MS, Comic Sans, cursive, monospace",
6      "h2": {
7        "fontSize": "26px",
8        "fontWeight": "500"
9      }
10    }
11  }
12</script>

For more information on customizing Monite Drop-in UI, see Theming and customization.

Next, insert the script into in the monite-app element as shown:

1<monite-app entity-id="ENTITY_ID">
2  <!-- Embed JSON into the monite-app element -->
3  <script slot="theme" type="application/json">
4    {
5      "typography": {
6        "fontFamily": "Comic Sans MS, Comic Sans, cursive, monospace",
7        "h2": {
8          "fontSize": "26px",
9          "fontWeight": "500"
10        }
11      }
12    }
13  </script>
14</monite-app>

(Optional) Add localization

You can customize the locale of the monite-app component renderings. To include localization, define the object that describes the localization within a script tag in your file. The script tag that contains your custom theme is assigned an slot attribute with a value of locale:

1<!-- Create new locale JSON -->
2<script slot="locale" type="application/json">
3  {
4    "code": "de-DE",
5    "messages": { "Counterparts": "Suppliers" }
6  }
7</script>

The currencyLocale property must adhere to the BCP-47 language tag standard. For more information on including localization in Monite’s Drop-in library, see Localization.

Next, insert the script into in the monite-app element as shown:

1<monite-app
2  entity-id="ENTITY_ID"
3  api-url="https://api.sandbox.monite.com/v1"
4  basename="/"
5>
6  <!-- Embed JSON into the monite-app element -->
7
8  <script slot="locale" type="application/json">
9    {
10      "code": "de-DE",
11      "messages": { "Counterparts": "Suppliers" }
12    }
13  </script>
14</monite-app>

Next steps

By completing this quick start, you have learned how to:

  • Install and set up Monite Drop-in SDK.
  • Localize it and change the default appearance.

To learn more about this integration, see Drop-in library.