Skip to content
Last updated

React Native

Prerequisites

In order to be able to use the hosted widget in your React Native app, make sure that you:

  • Can create access tokens in your server-side.
  • Know how to implement webviews for your platform. For more information, see the webview articles from React Native's github page.

Handle events in your webview

In the code sample below you can see an example of how to listen and handle for events within your webview.

Webview Handling Example
import React, {useState, useEffect} from 'react';
import {Linking} from 'react-native';
import {WebView} from 'react-native-webview';
import {URL} from 'react-native-url-polyfill';

const BELVO_URI = 'https://widget.belvo.io/';

export default function BelvoWidget({token, payload}) {
  const [belvoURI, setBelvoURI] = useState('');

  useEffect(() => {
    setBelvoURI(`${BELVO_URI}?access_token=${token}&${buildPayload(payload)}`);
  }, [token, payload]);

  const buildPayload = (rawPayload) =>
    Object.keys(rawPayload)
      .map((key) => `${key}=${rawPayload[key]}`)
      .join('&');

  const handleBelvoEvent = (event) => {
    const {url} = event;

    // Open institution / external https URLs in the system browser — do not load them inside the WebView.
    if (url.startsWith('https://') && !url.startsWith(BELVO_URI)) {
      Linking.openURL(url);
      return false;
    }

    const webviewEvent = new URL(url);
    if (webviewEvent.protocol === 'your-url-here:') {
      const params = Object.fromEntries(webviewEvent.searchParams);

      switch (webviewEvent.hostname) {
        case 'success': {
          const {link, institution} = params;
          // Do something with the link and institution.
          return false;
        }
        case 'exit':
          // Handle exit.
          return false;
        case 'error':
          // Handle error (params.error, params.error_message).
          return false;
      }
      return false;
    }

    return true;
  };

  return (
    <WebView
      source={{uri: belvoURI}}
      originWhitelist={['your-url-here://*']}
      onShouldStartLoadWithRequest={handleBelvoEvent}
    />
  );
}
Important

Institution and other external https:// URLs must be opened in the system browser using Linking.openURL() — not loaded inside the WebView. Loading these URLs in the WebView can break institution redirects.

Listening to additional events

Our widget for webviews also sends additional data regarding events the user encounters throughout the widget. For example, when the user goes from the institution selection screen to the credentials login screen, our widget will send an event.

The events are sent through as JSON payloads with the following schema:

PAGE_LOAD Event
{
    "eventName": "PAGE_LOAD",
    "metadata":{
        "page": "/institutions", // Page that the user is directed to
        "from": "/consent", // Page where the user was previously
        "institution_name": "", // Note: This field only appears AFTER they've selected an institution
    }
}

To listen to these events, just add the following code to your application:

<WebView
      source={{
        uri: // ...
      }}
      onMessage={(event) => {
        // do something with event.nativeEvent.data
      }}
/>

Done! You can now listen to additional events in your webview!

iOS (Swift)

Android (Kotlin)