@chuck-blip/react-native v1.0.0

The Blip UI component library for React Native

This library contains a simple drop-in module with customizable styling and a built-in flow that helps onboard endusers with minimal effort from developers.

For more information about Blip, visit our site as well as our docs.

Table of contents

• The Blip UI component library for React Native
  • Table of contents
  • Demo
  • Prerequisites
  • Installation
  • Usage
  • Caution regarding your API keys
  • Version notes

Demo

See the official example Expo Snack here. We strongly recommend looking at this, as it is a fully functional and interactive app that uses this package.

Prerequisites

In order to use the component library, you must follow the quickstart guide at our official documentation site first to set up your account and populate your Blip institution with data. Then, come back here once the guide tells you to do so.

Installation

First, install the npm package using pnpm, yarn, or npm:

pnpm add @bliplabs/react-native

npm i @bliplabs/react-native

yarn add @bliplabs/react-native

Make sure you have a React and React Native peerDependency that matches our specified version. Currently, we require the following, but if this readme does not get updated, always consider the contents of this NPM package's package.json to be the source of truth:

...
"peerDependencies": {
  "react": "^18.2.0",
  "react-native": "^0.71.3"
},
...

Additionally, make sure that the react-native-webview dependency is respected. This should happen automatically if your package manager is functioning normally. Our package needs to use the exact version specified in this package's package.json, which as of writing this document, is 11.23.1. Other versions of the webview may not be compatible.

Usage

Now that you have the package installed, you'll want to get something working.

The first step is to create a token on behalf of one of your endusers. This token allows one of your endusers to authenticate and interface with Blip through your app, on their own device.

For the scope of this guide, this requires two things:

1. the API key that was created earlier in the prerequisites section (via the quickstart guide).
2. an enduser's oid, which stands for origin id. This is actually the enduser's unique identifier from your databases, not ours. When you create endusers, you give us a unique identifier of your choosing for each enduser.

In real world applications, you will not perform the below curl commands every time. You would instead leverage an existing service on your own infrastructure that acquires enduser tokens for your own authorized endusers. Most importantly, do not make the mistake of including your actual API keys in your customer-facing app. See the below section for more info.

For (1) above, you should already have the API key. If not, visit the quickstart guide linked above.

For (2) above, in normal situations, you would already know your own endusers' origin ID values and would have it readily available within your app. However, in this case, the quickstart has auto-generated a couple endusers as well as a few transactions for one of those endusers. We'll take a moment to get that enduser_oid quickly next.

We will plug the API key into the following curl command to get a list of all transactions that were created for all of your endusers that were created by the quickstart:

curl \
  --url 'https://api.bliplabs.com/v2/transactions' \
  --header 'X-API-Key: YOUR_API_KEY_GOES_HERE'

This will return a list of transaction data, which, if you've only followed the quickstart guide up to this point, should only be around 5 transactions that are all associated with one enduser.

Truncated results, but only one of the results is needed for the quickstart's sample transactions dataset:

{
  "total": 5,
  "page": 1,
  "size": 50,
  "items": [
    {
      "oid": "quickstart-dca479ed-0a4f-4918-84af-9427291514a8",
      "enduser_oid": "quickstart-7205214e-717b-40b8-a895-d3d30c01ce32",
      "name": "Netflix",
      "date": "2019-08-24",
      "amount": 10,
      "account_oid": "quickstart-2e0b22fc-ac1d-4cae-9e80-f8234fe3b81b",
      "account_name": "Blip Quickstart Credit Card",
      "merchant_id": "c352a66b-c667-4e0a-8a3d-eac3a0f1871b",
      "batch_id": "046e82b8-5971-4946-a50c-583cb4035688",
      "status": "complete"
    }
  ]
}

All transactions should be associated with the same enduser in this example only, so let's just pick the enduser_oid from any of them: quickstart-7205214e-717b-40b8-a895-d3d30c01ce32. Pass this enduser_oid value into YOUR_ENDUSER_OID_GOES_HERE in the following curl command, as well as replacing YOUR_API_KEY_GOES_HERE with your Blip API key:

curl --request POST \
  --url https://api.bliplabs.com/v2/tokens \
  --header 'X-API-Key: YOUR_API_KEY_GOES_HERE' \
  --header 'content-type: application/json' \
  --data '{"enduser_oid":"YOUR_ENDUSER_OID_GOES_HERE"}'

This will return a JWT contained within an object:

{"token": "xxxxx.yyyyy.zzzzz"}

Now that you have a token for an enduser, import Blip's BlipModule component in your TypeScript React Native project and use it:

import {
  BlipModule,
  type BlipModuleProps,
  type BlipTheme,
  type BlipEvent,
} from '@bliplabs/react-native'

// You do not need to specify customTheme at all if you don't want to.
const customTheme: Partial<BlipTheme> = {
  colorAccent: '#1C4646',
  colorBackground: '#cfe8de',
  // many other optional customizable theming properties not shown
}

const blipModuleProps: BlipModuleProps = {
  apiConfig: {
    // Required - This is an enduser token (JWT). See steps above.
    token: 'xxxxx.yyyyy.zzzzz'
  },
  // Optional `onEvent` handler that triggers when endusers enroll
  onEvent: (event: BlipEvent) => {
    if (event?.name === 'enroll') {
      console.log('Enroll event occurred!');
    }
  }
}

// Simplified example.
const App = (): JSX.Element => {
  return (
    <>
      <BlipModule {...blipModuleProps}/>
    </>
  )
}

Caution regarding your API keys

Do not ship your Blip API keys with customer apps. This can inadvertently grant your endusers the ability to see information about your institution/transactions/endusers/bills that they should not have permission to see.

Instead, run a server that contains your own authentication and authorization logic for your own endusers, and use it to acquire enduser tokens from Blip, then forward those tokens to your endusers in your app to be passed in as a prop for the BlipModule.

Steps for setting up a server to do this are out of scope for this guide as they may vary greatly depending on how your infrastructure is configured, as well as your company's policies regarding enduser authentication and authorization.

Version notes

Early versions of the Blip React Native component library required react-native-svg. We have removed this from current versions. We hope this helps simplify your stack a bit.