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
  • Use cases
    • 1. Pre-upload enduser transactions
    • 2. Upload transactions at enduser enrollment
  • Usage
  • Caution regarding your API keys
  • Full customization options
  • Version notes
  • Types Documentation

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:

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(`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

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