Get Started

Objective

Load the Universal Connect Widget into your browser.

This page lists the topics you should understand before integrating, details the account requirements for aggregators, and explains how to setup the widget.

Assumptions

Before integrating UCW, you should understand the following:

• Consuming external Open Finance services for connectivity and aggregation
• Configuring your servers to consume connectivity and aggregation
• Using git
• Using docker, docker Compose, and docker containers
• Using Node.js and npm
• Securing your servers
• Securing your API keys and configurations
• Compliance with your institution's security requirements and the requirements of your security auditing entity

Preinstallation

1. To host the UCW widget, create an account in the Universal Connect Project dashboard and setup your API keys to sync institution lists and get performance data.
2. Create accounts with your chosen aggregators, using your own credentials to access aggregator production APIs. Reference the following table for sign-up requirements.

Aggregator	Required Fields
Akoya	Client ID, Client Secret
Finicity	App ID, Client ID, Client Secret
MX	API Key, Client ID. You must also whitelist your IP addresses in MX's dashboard. See MX's IP whitelisting docs.
Sophtron	UserId, AccessKey

Cached Institutions

When you fork the ucw-app project, the most recent version of the institutions list is automatically available in the ./apps/server/cachedDefaults folder.

This file is a .json file that includes a list of all institutions exported from the UCP database.

The widget is built to index and search this file in case the institution service is down. The institution service overrides the cached list.

Environment Variables

The application relies on environment variables to store configuration settings and sensitive information, such as server URLs, client IDs, and secrets for each of your aggregators.

You may also set optional variables for proxy servers, frequency of updates, and enablement of authentication and/or data endpoint use.

Refer to the lastest environment variable definitions in our repository.

Sensitive Information

Secrets must be passed through environment variables instead of hardcoded in the code files. Do not put any credentials in any of the code files. If you do so, it could get committed and leaked to the public. Use the provided .env files.

info

Be sure to sign up in the UCP Dashboard and get your UCP client ID and client secret to sync the latest institution and performance data. Then, add this information to your environment variables.

Setup

1. Clone the ucw-app repo. You may also fork the repository or download the repository ZIP file.
2. From the root directory, run:
   • npm ci
   • cp ./.env.example ./.env
   • npm run copyServerEnv
     • Set environment variables in the apps/server/env/(staging|production).env files.
     • See ENVIRONMENT.md for details on what values you must provide in environment files such as API credentials for aggregators, ports to use, and more.
   • cp ./apps/server/cachedDefaults/preferences.example.json ./apps/server/cachedDefaults/preferences.json
     • Set up your PREFERENCES.
3. Ensure you have Docker installed (or another compatible container runtime), which is a required dependency for the institution search feature to function, even when running via Node.js. More info in available in our DOCKER readme.
4. Finally, run the docker containers, or simply run from the cli, via node.
   • For docker: docker compose up
   • For node: npm run dev

tip

For a production instance, the easiest way to deploy the widget is via docker-compose. We provide docker files for both the server and the UI, along with a docker-compose file that runs all necessary containers, including Redis and ElasticSearch. You can also use the dockerfiles directly.

See docker-compose.yml for setup details.

Commands to debug Docker issues

To debug Docker issues, the following commands are available:

Server

docker build -f ./docker-server.Dockerfile -t ucw-app-server-cli --build-arg APP=server .
docker run --name ucw-app-server-cli -p 8080:8080 --env-file ./apps/server/.env -t ucw-app-server-cli

UI

docker build -f ./docker-ui.Dockerfile -t ucw-app-ui-cli --build-arg APP=ui .
docker run --name ucw-app-ui-cli -p 5137:5137 -e UI_PORT=5137 -t ucw-app-ui-cli

The server may take a few moments to initialize and set up elasticsearch.

Once the server is running, you'll receive the following message: "Message":"App initialized successfully".

The Universal Connect Widget UI will load in a browser at http://localhost:8080/widget?jobTypes=transactions&userId=test-user-id.