Get Started
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
- 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.
- 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.
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.
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
- Clone the
ucw-app
repo. You may also fork the repository or download the repository ZIP file. - 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.
- Set environment variables in the
cp ./apps/server/cachedDefaults/preferences.example.json ./apps/server/cachedDefaults/preferences.json
- Set up your PREFERENCES.
- 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.
- Finally, run the docker containers, or simply run from the cli, via node.
- For docker:
docker compose up
- For node:
npm run dev
- For docker:
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.