@chuck-blip/react-native
v1.0.0
Published
React Native Component Library with Blip UI Elements.
Downloads
3
Maintainers
Readme
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
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:
- the API key that was created earlier in the prerequisites section (via the quickstart guide).
- an enduser's
oid
, which stands fororigin 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.