Branding and customization (OFDA)

Add some personal flair to your widget by customizing the logo and adding some custom text to engage your users 🚀.

With Belvo's Connect Widget, you can optionally add the following branding and customization:

  • Your company logo
  • Your company icon
  • Your company name
  • Link to your privacy policy
  • Add a custom overlay color
  • Add custom colors to the widget
3845

Screens in the widget where you'll see your custom branding

Elements that you can modify the colors of (OFDA-only)

Elements that you can modify the colors of ()

Full customization and branding example

🚧

Add branding when generating access_token

To add branding to your widget, it must be done in the same backend call as your request to generate an access_token. For a full example of how this looks like, see the code example below.

{
  "id": "SECRET_ID",
  "password": "SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "credentials_storage": "365d",
  "stale_in": "300d",
  "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"],
  "widget": {
    "branding": {
      "company_icon": "https://mysite.com/icon.svg",
      "company_logo": "https://mysite.com/logo.svg",
      "company_name": "ACME",
      "company_terms_url": "https://belvo.com/terms-service/",
      "overlay_background_color": "#F0F2F4"
    },
    "theme": [
      {
        "css_key": "--color-primary-base",
        "value": "#907AD6"
      },
      {
        "css_key": "--nav-bar-title-color",
        "value": "#4F518C"
      },
      {
        "css_key": "--nav-bar-icon-color",
        "value": "#4F518C"
      }
    ]
  }
}

For more detailed information on each customization, see the relevant sections below.

Add a company icon

You can add your company icon to the widget to make it more aligned with your brand. When you add your company icon, it appears on the following screen:

  • initial start of the widget

Make sure that your icon has square dimensions, in SVG format, has a transparent background, and contains no surrounding whitespace. If your icon does not follow these specifications, the Belvo widget will display the following icon:

150

Standard square icon displayed if your icon is not SVG or square.

Instructions
To add a custom company icon, just add the URL to your SVG image to the company_icon key.

{
  "widget": {
    "branding": {
      ...
      "company_icon": "https://mysite.com/icon.svg",
      ...
        }
     }
}

Add a company logo

You can add your company logo to the widget to make it more aligned with your brand. When you add your company logo, it appears on the following screens:

  • while the account is being linked
  • once an account is successfully linked
  • when a user chooses to cancel the linking process

Make sure that your logo is in SVG format, has a transparent background, and contains no surrounding whitespace. For the best visibility and scaling, we suggest that you use a horizontal logo (see the top-left example in the image below).

4153

Please ensure that your logo contains no whitespace (left-hand example).

Instructions
To add a custom company logo, just add the URL to your SVG image to the company_logo key.

{
  "widget": {
    "branding": {
      ...
      "company_logo": "https://mysite.com/logo.svg",
      ...
        }
     }
}

Add your company name

You can add your company name to be displayed when the widget first starts. By default, it'll just display "Link your account". When you add your company name, the message will follow the format "[company_name] uses Belvo to connect your account".

📘

Please note, only the company name is customizable in the introductory sentence.

Instructions

To add your company name, just add it to the company_name key.

{
  "widget": {
    "branding": {
      ...
      "company_name": "ACME",
      ...
        }
     }
}

Add a link to your privacy policy

You can add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. By default the widget will include the URL to Belvo's privacy policy (<https://belvo.com/terms-service/>).

Instructions
To add a link to your privacy policy in the initial connect screen, just add the URL to your policy to the company_terms_url key.

{
  "widget": {
    "branding": {
      ...
      "company_terms_url": "https://belvo.com/terms-service/",
      ...
        }
     }
}

Add a custom overlay color

You can add a custom overlay color for when the widget loads in your desktop application. We recommend choosing a neutral color related to your brand to keep environmental context. By default, this overlay is set to grey.

1728

Widget with custom overlay color

📘

Overlay opacity

No matter what color you upload, Belvo will automatically set the opacity to 90%. This is due to the following UX best practices:

  • With lower opacities (less than 70%), the user can experience difficulties focusing on the flow as they will have “visual noise” in the background.

  • Block colors (opacity set at 100%) may cause a drastic change, resulting in a disjointed or unnatural experience.

Instructions

To set the overlay color, just add the full HEX code (# followed by six characters) to the overlay_background_color key.

{
  "widget": {
    "branding": {
      ...
      "overlay_background_color": "#F0F2F4",
      ...
        }
     }
}

Add custom colors to the widget

You can further customize the widget by adding your own brand’s colors to several parts of the widget:

  • The primary color for buttons, checkboxes, and the progress bar
  • The color of the navigation icons and text
Default color scheme

Default color scheme (OFDA widget)

Example with custom color configuration

Example with custom color configuration (OFDA widget)

Instructions

To set your brand’s colors:

  1. Add the theme array to the widget object.
  2. For each item you want to modify, add an object that has the keys css_key and value (see the code sample below). The color values can be either in HEX, RGB, or RGBA format.
{
  "widget": {
    "branding": {}, // Your customized branding
    "theme": [
      {
        "css_key": "--color-primary-base",
        "value": "#907AD6"
      },
      {
        "css_key": "--nav-bar-title-color",
        "value": "#4F518C"
      },
      {
        "css_key": "--nav-bar-icon-color",
        "value": "#4F518C"
      }
    ],
  }
}

📘

You do not have to include all the possible css_keys. You can just set the keys (and values) that you want to modify.