Connect a user
The Vezgo Connect process allows users to connect their exchange accounts or wallet addresses to your application. There are different ways to start the process and receive the connection result.
The easiest way to do that is using the Vezgo JS SDK to open the drop-in Vezgo Connect Widget right inside your web application, and receive the result via JS callbacks.
Or you can use an oAuth process where you redirect users to the Vezgo Connect URL to connect their account, and have them redirected back to your application with the result. This oAuth process can be used in web, mobile or desktop applications.
Via drop-in Connect Widget
document.getElementById('#connect').addEventListener('click', () => {
user.connect().onConnection(accountId => {
// Send the account id to your server
sendToServer('/some-route', accountId);
// Request account data to display in the page
const account = await user.accounts.getOne(accountId);
displayAccount(account);
});
}, false);
Start the connect process by calling user.connect()
from your web application. It will open the Vezgo Connect Widget inside the page, and let the user select the exchange / wallet they want to connect.
Receive via callbacks
user.connect().onConnection(async accountId => {
console.log('account connection success:', accountId)
}).onError(error => {
console.error('account connection error:', error)
}).onEvent((name, data) => {
console.log('event:', name, data);
});
The drop-in Connect Widget sends data to the Vezgo Frontend SDK via 3 callbacks:
onConnection(accountId)
onError(error)
onEvent(name, data)
onConnection(accountId)
The onConnection()
callback listens for successful connection from the Connect Widget. After user successfully connects their account, the Widget is automatically closed and the callback is called with an accountId
that belongs to a newly-created Vezgo account. This Vezgo account is kept in sync with the user's connected exchange account / wallet.
It is recommended that you store this accountId
in your database for future updates.
onError(error)
The onError()
callback listens for errors from the Connect Widget. During the process, if there is an error or if user clicks the close (X) button, the Widget is closed and the callback is called with an error
object.
error object attributes
Attribute | Description |
---|---|
error_type | The error code, e.g. 400. |
message | The error message. |
account | The account ID if it has been created. |
onEvent(name, data)
The onEvent()
callback listens for events from the Connect Widget during the connection process. There are multiple events corresponding with the multiple steps of the connection process that keep your web application notified of the process inside the Widget so it can act accordingly.
Supported events
Event | Data | Description |
---|---|---|
APP_LOADED | {} | The Widget is ready (fully loaded and waiting for user actions). |
SCREEN_LOADED | { screen } | Screen successfully loaded. Screens: ACCEPT_TERMS_AND_POLICY , SELECT_PROVIDER , PROVIDE_CREDENTIALS , CONNECTION_SUCCESS , EXIT . |
TERMS_AND_POLICY_ACCEPTED | {} | User has accepted Vezgo terms and policy. |
ERROR | { type } | Error occurred. Available error types: PAGE_NOT_FOUND , OAUTH_ERROR , CLIENT_ID_REQUIRED , INVALID_ORIGIN , TOKEN_REQUIRED , WRONG_CLIENT_ID , WRONG_REDIRECT_URI , INVALID_ACCOUNT_ID , RECONNECT_CONFLICT |
CLOSE | {} | The Widget has been closed automatically. Directly followed by onConnection() or onError() . |
FORCE_CLOSE | {} | The Widget has been closed by the user. Directly followed by onError() . |
PROVIDER_SEARCH | { query } | User has searched for a provider in the provider selection screen.query contains the search string which the user typed in. |
PROVIDER_SELECTED | { provider } | User has selected a provider.provider is the Provider object. |
SUBMIT_CREDENTIALS | {} | User has submitted their credentials for the exchange/wallet. User credentials are secured and won't be available to the SDK. |
SUBMIT_ANSWER | {} | User has submitted their answer to security question. |
START_OAUTH | {} | User started oAuth flow. |
RETURNED_FROM_OAUTH | {} | User returned to Vezgo from third party oAuth service. |
OPEN_METAMASK | {} | User opened MetaMask. |
OPEN_WALLET_CONNECT | {} | User opened Wallet Connect. |
OPEN_LEDGER | {} | User opened Ledger. |
Customize Connect Widget
<html>
<head>
<style>
iframe[name='vezgo-connect-widget'] {
border: 1px solid gray;
width: 300px;
height: 500px;
display: none;
}
</style>
</head>
<body>
<nav>Nav bar</nav>
<section>
<h1>Connect your account</h1>
<button id="connect">Connect</button>
<iframe name='vezgo-connect-widget'></iframe>
</section>
</body>
</html>
Under the hood, the Connect Widget is loaded inside a <iframe name='vezgo-connect-widget'>
element. By default, the .connect()
method appends the iframe at the root of your page's <body>
, with special styling so that it appears as an overlay inside the page.
You can customize the styling of the widget overlay via the vezgo-connect-widget
.
If you need to control where the iframe is inside your page, you can pre-create the <iframe name='vezgo-connect-widget>
anywhere in your page and the .connect()
method will load the Connect Widget inside that element instead of creating a new one.
NOTE: the JS SDK will add display: block
style to the iframe when opening the Connect Widget, and display: none
when closing it.
Preselect a provider
document.getElementById('#connect_bitcoin').addEventListener('click', () => {
user.connect({ provider: 'bitcoin' }).onConnection(accountId => {
console.log('bitcoin connection success:', accountId)
});
}, false);
By default .connect()
will open the Vezgo providers list for user to select from. Alternately you can pass in a provider name to skip the selection step so that Vezgo Connect Widget go straight to the provider credentials form.
NOTE: Pass in the provider name
that you get from the Provider object, not display_name
.
Reconnect an account
When an account's credentials expire or are revoked, Vezgo will no longer be able to synchronize its data from the provider. The account is put in a 'disconnected' state and will need to be reconnected.
To allow a user to reconnect a disconnected account, call user.reconnect(accountId)
from your web application. It will open the Vezgo Connect Widget inside the page, and let the user reconnect the account. The process is almost identical to connecting a new account, except that at the end of the process it would update the existing account instead of creating a new one.
Via Connect URL
Another way to connect an user is via the Vezgo Connect URL directly. You can load the Vezgo Connect URL using your own method (redirect from the current page or open in a new window, or inside a mobile WebView...).
You can customize various aspects of the Vezgo Connect process via the url params. A standard Vezgo Connect URL looks something like this:
POST https://connect.vezgo.com/connect?client_id=YOUR_CLIENT_ID
Form Data (x-www-form-urlencoded):
token=USER_TOKEN
Or with preselected provider:
POST https://connect.vezgo.com/connect/bitcoin?client_id=YOUR_CLIENT_ID
Form Data (x-www-form-urlencoded):
token=USER_TOKEN
To reconnect account:
POST https://connect.vezgo.com/reconnect/ACCOUNT_ID?client_id=YOUR_CLIENT_ID
Form Data (x-www-form-urlencoded):
token=USER_TOKEN
The same Connect URL is loaded in the iframe when you connect via the drop-in Connect Widget using the JS SDK. The SDK just automatically encapsulates all handling logic in an easy-to-use interface to save you time.
Connect URL parameters
Parameter | Required | Description |
---|---|---|
client_id | Yes | Your team's Client ID. |
token | Yes | The user token. See Authentication to see how to get the token. |
redirect_uri | No | The URI to redirect to after the process is finished. This must match one of your team's registered Redirect URIs. More on this here. |
origin | No | The URL origin that triggers the process (e.g. https://some.domain ). This is used mostly for when the Vezgo Connect is loaded inside an iframe, so it can pass data back to the parent page at the specified origin. |
lang | No | The content language. Currently only en , es , fr and it are accepted. |
state | No | An opaque string containing your application state, to maintain application state between redirects (in the oAuth process). |
provider_categories | No | Show providers only from selected categories. Available options: exchanges,blockchains,wallets . |
providers | No | Limit the list of providers available for selection. Example: binance,coinbase,ethereum . |
theme | No | Vezgo Connect widget theme. Available options: light , dark . Default: light . |
providers_per_line | No | The number of providers displayed per line on the select provider screen. Available options: 1 , 2 .Default: 2 . |
sync_nfts | No | Show "Sync NFTs" checkbox. Available for proviers which support "sync_nft" feature and also if "sync_nft" feature enabled for the team (depends on plan). Boolean. Default: false . |
Receive via URL params
The connection result is returned in the URL params at the end of the process. If you open the Connect URL inside an iframe, popup, or mobile WebView, you can expect the process to redirect to this URL when connection is successful:
https://connect.vezgo.com/connected?account=ACCOUNT_ID&code=ACCOUNT_ID
And to this URL when connection failed or is interrupted:
https://connect.vezgo.com/exit?error_type=400&message=ERROR_MESSAGE
Custom Redirect URI
You can pass in the Vezgo Connect URL a custom redirect_uri
so that it redirects to this uri at the end of the process.
For example, load the following Vezgo Connect URL:
POST https://connect.vezgo.com/connect?client_id=YOUR_CLIENT_ID&redirect_uri=https://myapp.test/crypto&state=APP_STATE_BEFORE_CONNECTION_IN_BASE64
Form Data (x-www-form-urlencoded):
token=USER_TOKEN
After user finishes connecting an account, it will redirect to:
https://myapp.test/crypto?account=ACCOUNT_ID&code=ACCOUNT_ID&state=APP_STATE_BEFORE_CONNECTION_IN_BASE64
Or if the connection failed or user closes the process, it will redirect to:
After user finishes connecting an account, it will redirect to:
https://myapp.test/crypto?error_type=400&message=Invalid+credentials&state=APP_STATE_BEFORE_CONNECTION_IN_BASE64
In both cases, your page at https://myapp.test/crypto
can look at the URL params and proceed accordingly. Optionally if you passed in a state
, you will receive it back here to restore your application to the same state before the connection.
All redirection URL params
Parameter | Type | On | Description |
---|---|---|---|
account | String | Both | The Vezgo account id corresponding to the newly-connected exchange account / wallet. Note that it's returned on Failure ONLY if it has been created before the error happens. |
code | String | Success | Same as account . For oAuth compliance. |
error_type | Number | Failure | The connection error code. |
message | String | Failure | The connection error message. |
force | Boolean | Failure | true means the process was explicitly closed by user. |
state | String | Both | The application state passed to the Vezgo Connect URL at the start of the process (if available). |