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.

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

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

  let belvoWidgetURL = `https://widget.belvo.io/?access_token=${token}`;

  useEffect(() => {
    setBelvoURI(`${belvoWidgetURL}&${buildPayload(payload)}`);
  }, [belvoWidgetURL, payload]);

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

  const handleBelvoEvent = event => {
    console.log({event});
    const webviewEvent = new URL(event.url);

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

      switch (webviewEvent.hostname) {
        case 'success':
          const {link, institution} = parseParams;
          // Do something with the link and institution.
          return false;
        case 'exit':
          // If the redirect starts with "exit",
          // Do something with the data.
          return false;
        case 'error':
          const {error, error_message} = parseParams;
          // If the redirect starts with "error",
          // Do something with the error data.
          return false;
      }
      return false;
    }
    return true;
  };
  
  // Insert code to listen to additional events here

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

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:

"data": {
    "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
    }
}

data = {
  "eventName": "ERROR",
  "request_id": "UUID",
  "meta_data": {
    "error_code": "login_error",
    "error_message": "Invalid credentials provided to login to the institution",
    "institution_name": "bancoazteca_mx_retail",
    "timestamp": "2020-04-27T19:09:23.918Z"
  }
}

To listen to these events, just add the following code to your application (before thereturn statement):

const onMessage = message => {
  const {
    nativeEvent: { data },
  } = message;
  const { eventName, meta_data } = JSON.parse(data);
  // Institution name will be included on every single event (if it's already selected)
  const { institution_name } = meta_data;
  switch (eventName) {
    case 'PAGE_LOAD':
      const { page, from } = meta_data;
      // handle PAGE_LOAD event here
      break;
    case 'ERROR':
      const { error_code, error_message, timestamp } = meta_data;
      Alert.alert(
        `An ${error_code} error happends at ${timestamp}, ${error_message}`,
      );
      // handle ERROR events here
      break;
    default:
      // DO NOTHING
      break;
  }
};

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