Widget (beta)

🚧

This feature is in beta!

This page discusses functionality that is in beta. You may occasionally experience unannounced changes or bugs. We'd greatly appreciate your feedback on this feature and its accompanying documentation.

The Ocrolus Widget simplifies the collection of financial data for you by offering pre-built UI components and integration points, eliminating the need for custom API integration or extensive front-end development. With the widget, you can quickly start using Ocrolus to streamline your data collection process and accelerate underwriting.

Key features of the widget include:

• Built-in document ingestion that seamlessly connects with Ocrolus.
• Responsive design for optimal display on any device or screen size.
• Extensive customization options through the Ocrolus's Dashboard, allow you to match the widget's appearance to your website.

To view the widgets, navigate to the widget section within the Ocrolus Dashboard and access the Widget page by selecting the Embedded Widget option from the Account dropdown. On this page, you can create new widgets and efficiently manage all your existing ones. A convenient list of widgets will be displayed, providing easy oversight and control.

Create a widget

To create and configure your widget to align with your branding preferences, perform the following steps:

1. Go to Dashboard > Account & Settings > Embedded Widget.

2. On the Embedded Widgets page, select the ADD WIDGET button to access the configuration page.

3. On the Add Widget page, add the URL of your desired hosting location to the allowed URLs list for the widget. Customize your website with branding colors, text colors, and displayed text. Validate your changes in the real-time preview window.

5. On the Add Widget page, select SAVE. A widget is created successfully.

Embed a widget

After the widget is created, the system generates the corresponding JavaScript code to embed it on your website. You will also receive the generated API credentials for the widget. Remember to copy and securely save these credentials as they won't be accessible later.

To embed the widget on your website, perform the following steps:

1. To embed widget requests, you'll need to authorize widget requests and set up a REST server that can handle internet requests. This includes configuring an endpoint on your server, as demonstrated in the JavaScript example, where a POST request is made with authenticated user information to request an authenticated token from Ocrolus for uploading purposes.

   Example JavaScript

   app.post('/token', function (request, response) {
       const user_token = request.headers.authorization || 1234
   
       return getUserExternalId(user_token).then(userId => {
           return POST_REQUEST(https://jwe-issuer.ocrolus.net/token', {
               client_id: OCROLUS_CLIENT_ID,
               client_secret: OCROLUS_CLIENT_SECRET,
               external_id: userId, //If you want to upload additional files at a later point, you can use this external_id for reference
               grant_type: 'client_credentials',
               name: bookName, //To customize a book name, pass your desired name into this field
           }).then(token_response => {
               const token = token_response.access_token
   
               response.json({ accessToken: token })
           })
       })
   })
   

2. Create a global getAuthToken method that utilizes the API server endpoint on your server and makes it accessible to the widget for seamless request handling.

   Example JavaScript

   window.getAuthToken = async function() {
        const response = await fetch("https://www.yourserver.com/token", { method: "POST"})
        const json = await response.json()
        return json.accessToken
   }
   

3. Create the anchor div for embedding the widget, and add an element to your website with the id ocrolus-widget-frame. The widget will dynamically populate this div with an iframe. Customize the size of this div according to your preferences, and the widget will automatically adjust to fit within it.

   Example HTML code

   <div id="ocrolus-widget-frame"></div>
   

4. Embed the widget into your website by placing the generated JavaScript snippet in either the footer or header of your website. Please note that the example below is provided for explanatory purposes and should not be directly copied.

   Example JavaScript

   <script id=ocrolus-initializer-script>
   (function (w, d, s, o, h, u, f, js, fjs) 
   { w[o] = w[o] || function () { (w[o].q = w[o].q || []).push(arguments); }; 
   (js = d.createElement(s)), (fjs = d.getElementsByTagName(s)[0]); 
   js.id = o; js.dataset.host = h; js.dataset.uuid = u; js.src = f; 
   js.async = 1; fjs.parentNode.insertBefore(js, fjs); })
   (
       window, 
       document, 
       'script', 
       'ocrolus_script', 
       'https://widget-demo.ocrolus.com',
       'd547fb8f-ba6d-4f75-972e-4944a766e5d0', 
       "https://widget-demo.ocrolus.com/static/initializer-sdk.bundle.js"
   );
   ocrolus_script('init', );
   </script>
   

📘

Notes:

• By setting up webhooks, you can receive notifications whenever files are uploaded through the Ocrolus widget. For more information about the available events, please refer to our guide.
• You can retrieve the uploaded files by making a request to the Ocrolus download file endpoint.
• To see a complete example with all steps implemented, visit the Ocrolus Widget quickstart page.