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.
Use cases
There are two approaches to consider when it comes to the enduser onboarding workflow regarding uploading transactions to Blip.
1. Pre-upload enduser transactions
In this use case, you will upload enduser transactions at some point before the enduser is logged into your app and shown the <BlipModule>
component. This is the use case that we will walk through fully below, which leverages the quickstart.
This may be preferable over use case 2 because it allows transactions to be processed beforehand. This reduces the amount of time endusers have to wait during onboarding with Blip. A downside to this approach is that you may not always have pre-existing authorization/agreements for your endusers, which restricts your ability to upload transactions to Blip in advance.
2. Upload transactions at enduser enrollment
In this use case, endusers will open your app, and when they want to enroll in Blip, the <BlipModule>
component will be shown. They will immediately see an "Enroll" button presented to them. Once endusers press "Enroll", they grant authorization to you to upload transactions to Blip's servers for processing. Endusers will be shown a waiting screen while the transactions process in the background. This can take some time.
An onEvent
prop/callback is triggered with name: 'enroll'
when endusers tap on the "Enroll" button (documented more below). This callback is responsible for communicating with your own servers, which will in turn upload the newly enrolled enduser's transactions to Blip using the create transactions API endpoint, described in our API docs.
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(`Enduser '${event.enduserOid}' is being enrolled!`);
// at this point you may want to send an API call to your own server
// that uploads transactions to Blip's servers
}
if (event?.name === 'load') {
console.log(`Enrolled enduser '${event.enduserOid}' is loaded!`);
}
}
}
// 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.
Full customization options
For full customization options, refer to the BlipTheme
documentation. Note in particular that for the card switch flow to function, cardBackgroundColor
must be provided or showCardWithWalkthrough
must be set to false.
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.
Types Documentation
Click here to expand and view auto-generated type documentation.
Interfaces
Interface: BlipTheme
Table of contents
Properties
- background
- cardBackgroundColor
- cardChipColor
- cardFontWeight
- cardLetterSpacing
- cardLogo
- cardNumberPlaceholder
- cardType
- colorAccent
- colorBackground
- colorFieldBackground
- colorFieldBackgroundFocus
- colorOutline
- colorSectionBackground
- colorSectionBackgroundAlt
- colorSkeletonBackground
- colorTextDisabled
- colorTextError
- colorTextFieldLabel
- colorTextFieldLabelDisabled
- colorTextFieldPlaceholder
- colorTextFieldPlaceholderDisabled
- colorTextPrimary
- colorTextSecondary
- fontFamily
- fontSizeExtraLarge
- fontSizeExtraSmall
- fontSizeLarge
- fontSizeMedium
- fontSizeSmall
- fontSizeXXL
- fontWeightBold
- fontWeightRegular
- fontWeightSemibold
- logo
- showCardWithWalkthrough
- showCardWithWebview
Properties
background
• background: ImageSourcePropType
Background image to use behind screens in the module. Tinted by backgroundColor
cardBackgroundColor
• cardBackgroundColor: null
| string
Background color for the card graphic during card switch flow
cardChipColor
• cardChipColor: string
Color of the chip icon in the card graphic during card switch flow
cardFontWeight
• cardFontWeight: FontWeight
Font weight for text in the card graphic during card switch flow
cardLetterSpacing
• cardLetterSpacing: number
Letter spacing for text in the card graphic during card switch flow
cardLogo
• cardLogo: null
| ImageSourcePropType
Customer logo for the card graphic during card switch flow
cardNumberPlaceholder
• cardNumberPlaceholder: string
Placeholder text for the card numnber in the card graphic during card switch flow
cardType
• cardType: null
| CardType
Type of card to use in the card graphic during card switch flow
colorAccent
• colorAccent: string
Accent color
colorBackground
• colorBackground: string
Color of neutral background elements
colorFieldBackground
• colorFieldBackground: string
Background color of fields
colorFieldBackgroundFocus
• colorFieldBackgroundFocus: string
Background color of fields when focused
colorOutline
• colorOutline: string
Color of outlines
colorSectionBackground
• colorSectionBackground: string
Color of neutral background section elements
colorSectionBackgroundAlt
• colorSectionBackgroundAlt: string
Color of alternate neutral background section elements. This allows every other element in lists to have a slightly different color.
colorSkeletonBackground
• colorSkeletonBackground: string
Background color of placeholders while elements like text and images are loading
colorTextDisabled
• colorTextDisabled: string
Color for text that is disabled i.e. in a field
colorTextError
• colorTextError: string
Color of error text
colorTextFieldLabel
• colorTextFieldLabel: string
Color of label text over fields
colorTextFieldLabelDisabled
• colorTextFieldLabelDisabled: string
Color of label text over disabled fields
colorTextFieldPlaceholder
• colorTextFieldPlaceholder: string
Color of placeholder text in fields
colorTextFieldPlaceholderDisabled
• colorTextFieldPlaceholderDisabled: string
Color of placeholder text in disabled fields
colorTextPrimary
• colorTextPrimary: string
Primary text color
colorTextSecondary
• colorTextSecondary: string
Secondary text color
fontFamily
• fontFamily: string
Font for all text
fontSizeExtraLarge
• fontSizeExtraLarge: number
Extra large font size
fontSizeExtraSmall
• fontSizeExtraSmall: number
Extra small font size
fontSizeLarge
• fontSizeLarge: number
Large font size
fontSizeMedium
• fontSizeMedium: number
Medium font size
fontSizeSmall
• fontSizeSmall: number
Small font size
fontSizeXXL
• fontSizeXXL: number
XXL font size
fontWeightBold
• fontWeightBold: FontWeight
Bold text font weight
fontWeightRegular
• fontWeightRegular: FontWeight
Regulat text font weight
fontWeightSemibold
• fontWeightSemibold: FontWeight
Semibold text font weight
logo
• logo: ImageSourcePropType
Customer logo to display on the splash screen
showCardWithWalkthrough
• showCardWithWalkthrough: boolean
Whether to show the credit card graphic with the walkthrough instructions
during the card switch flow. Note that if this is true
, a
cardBackgroundColor
must be specified
showCardWithWebview
• showCardWithWebview: boolean
Whether to show the credit card graphic with the biller website webview
during the card switch flow. Note that if this is true
, a
cardBackgroundColor
must be specified