React ⚛

Our CardScanView react component makes it easy to add insurance card scanning and eligibility verification to any web application in 5 minutes or less.

Installation

$ npm i @cardscan.ai/insurance-cardscan-react
$ yarn add @cardscan.ai/insurance-cardscan-react

Usage

Import the library widget into your project files:

import { CardScanView } from "@cardscan.ai/insurance-cardscan-react";

You can optionally add the API client for more custom applications.

import { CardScanView, CardScanApi } from "@cardscan.ai/insurance-cardscan-react";

Basic Example

import React from "react";
import { render } from "react-dom";
import { CardScanView } from "@cardscan.ai/insurance-cardscan-react";

function onSuccess(card: any) {
  console.log("New Card: ", card);
}

function onError(error) {
  console.error('Error occurred: ', error);
}

// See Authentication on where to get this sessionToken.
const sessionToken = 'JWT_TOKEN'

// Render CardScanView
function App() {
  return (
    <div className="App">
      <div className="CardScanContainer">
        <CardScanView
          live={false}
          sessionToken={sessionToken}
          onSuccess={onSuccess}
          onError={onError}
        />
      </div>
    </div>
  );
}

const rootElement = document.getElementById('root');
render(<App />, rootElement);

Compatibility

  • Node Versions: 12, 14, 16, 18

  • React Versions: >=17.0.2, 18.2.0+

  • Webpack Versions: 4.x, 5.x

  • Babel Versions: 6.x, 7.x

Peer Dependencies

  • React: >=17.0.2

  • React-DOM: >=17.0.2

Configuration

Available Props

<CardScanView
  // Required
  live={false}
  sessionToken={token}
  onSuccess={onSuccess}

  // Recommneded
  onCancel={onCancel}
  onError={onError}
  onProgress={onProgress}
  
  // Eligibility
  eligibility={eligibility}
  onEligibilitySuccess={eligibilitySuccess}
  onEligibilityError={eligibilityError}
  
  // Camera Options
  cameraOptions={cameraOptions}
  
  // Optional
  backsideSupport={scanBackside}
  onRetry={onRetry}
  enableCameraPermissionModal={enableModal}
  webToMobileHandoffConfig={config}

  // UI Customization
  messages={messages}
  successIndicator={successIndicator}
  errorIndicator={errorIndicator}
  closeButton={closeButton}
/>

Main Props

PropRequiredTypeDescription

live

false

Boolean

Toggle the production or sandbox version. Default: false

sessionToken

true

String

A JWT token for the current user, see Authentication

onSuccess

true

Function

Called on successful scan. The first argument is the scanned card.

onCancel

false

Function

Triggered when the user cancels the CardScanView UI.

onError

false

Function

Called when an error is returned by the API or the CardScanView fails to initialize.

onProgress

true

Function

Progress updates during the card scanning process.

onRetry

false

Function

Called when a failed scan triggers a retry.

fullScreen

false

Boolean

Toggles the widget between full viewport coverage and a 16:9 aspect ratio within the parent container's width. Default: true

backsideSupport

false

Boolean

Enable scanning of the front and back side of the card. Default: false

eligibility

false

object

Request payload for the optional post-scan eligibility verification. See: Eligibility Verification 🩻

onEligibilitySuccess

false

Function

Called on successful eligibility request. The eligibility response is pass as an argument.

onEligibilityError

false

Function

Called when an error is returned by the eligibility API.

enableCameraPermissionModal

false

Boolean

Disable the modal which prompts the user to provide camera access to the page. Default: True

webToMobileHandoffConfig

false

object

Enables seamless handoff from desktop to mobile when errors are encountered. See: Web to Mobile Handoff 📲

cameraOptions

false

object

Configures the camera's orientation during scanning.

UI/UX Customization

The react widget is designed to be highly customizable. Please see the #customization section of UI Components to adjust these elements to match your application's branding and theme:

Customization ⚙️

Note: All UI/UX Props are optional

PropTypeDescription

messages

Object

Customize the text displayed by the UI.

successIndicator

ReactNode

Replace the success indicator with a custom react component.

errorIndicator

ReactNode

Replace the error indicator with a custom react component.

closeButton

ReactNode

Replace the close button with a custom react component.

Note: Additional UI elements can be modified using CSS

Callbacks

onSuccess Callback

The onSuccess prop allows you to execute a custom function when the card scanning process is completed successfully. This function receives the scanned card data as an argument.

Usage

To use the onSuccess prop, pass a function that receives the scanned card data:

const handleCardScanSuccess = (cardData) => {
  console.log('Card scanned successfully:', cardData);
};

<CardScanView
  sessionToken={token}
  onSuccess={handleCardScanSuccess}
/>

In this example, the handleCardScanSuccess function logs the scanned card data to the console when the scanning process is completed successfully.

onError Callback

The onError prop allows you to execute a custom function when there's a failure during the card scanning process. This function receives an error object as an argument.

Usage

To use the onError prop, pass a function that receives the error object:

const handleCardScanError = (error: CardScanError) => {
  console.error('Scanning failed:', error);
};

<CardScanView
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onError={handleCardScanError}
/>

In this example, the handleCardScanError function logs the error object to the console when a scanning failure occurs.

By using the onSuccess and onError props, you can handle successful and failed scanning events, allowing you to implement custom actions or display appropriate messages to the user.

You can find examples of theError Screens at the bottom of this document

Possible errors returned to the onError callback.

type CardScanError = {
  message: string;
  type: string;
  code: number;
  isCardScanError: boolean;
};
Error TypeError CodeError Message

VideoError

670

Various system errors of getUserMedia(), including: “Permission Denied” and “Camera not found”

VideoError

675

Various system errors of HTMLMediaElement.play(), including: “Permission Denied” and “The element has no supported sources.”

VideoError

676

Any and all other system related video capture & canvas capture errors.

WSError

640

“No websocket found - critical failure”

WSError

642

“Unknown error from websocket”

WSError

“The connection was closed abnormally”

ResponseError

HTTP Codes

Various HTTP errors returned from XMLHttpRequest and the CardScan.ai backend.

RequestError

Various

Various HTTP errors returned from Axios and XMLHttpRequest.

Unknown

606

Possible Axios setup errors, websocket setup errors, etc.

onCancel Callback

The onCancel prop enables you to execute a custom function when the user cancels the card scanning process. This can be useful for tracking user behavior, navigating to a different part of the application, or displaying an appropriate message.

Usage

To use the onCancel prop, pass a function that will be executed when the user cancels the scanning process:

import React, { useState } from 'react';
import {CardScanView} from "@cardscan.ai/insurance-cardscan-react";

const App = () => {
  const [showCardScanView, setShowCardScanView] = useState(true);

  return (
    <div>
      {showCardScanView && (
        <CardScanView
          sessionToken={token}
          onSuccess={cardScanSuccess}
          onError={cardScanError}
          onCancel={() => setShowCardScanView(false)}
        />
      )}
    </div>
  );
};

export default App;

In this example, we initialize the showCardScanView state variable to true. Then, we conditionally render the CardScanView component based on the value of showCardScanView. We then use the onCancel prop to set the showCardScanView state variable to false when the user cancels the scanning process.

onRetry Callback

The onRetry prop allows you to execute a custom function when a retry is triggered due to a scanning failure.

Usage

To use the onRetry prop, pass a function that receives the retry event as an argument:

const handleRetry = (event) => {
  console.log('Retry triggered:', event);
};

<CardScanView
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onRetry={handleRetry}
/>

In this example, the handleRetry function logs the retry event to the console when a retry is triggered.

onProgress Callback

The onProgress prop allows you to execute a custom function to report progress during the scanning process.

Usage

const handleProgress = (progress) => {
  console.log(`Card ID: ${progress.cardId} - Scan Count: ${progress.scanCount} - Card State: ${progress.cardState}`);
};

<CardScanView
  sessionToken={token}
  onSuccess={cardScanSuccess}
  onProgress={handleProgress}
/>

In this example, the handleProgress function logs the progress during a live scanning operation. When backsideSupport is enabled the scan counter will reset to zero when the card is flipped to scan the back side.

For the majority of live scanning scenarios, the scanning will be completed within 2-3 scans. In situations with low light or occluded card elements, the scan count can go as high as 12.

Additional Features

Eligibility Verification

Eligibility Verification is crucial in healthcare for confirming a patient's insurance coverage and benefits before services are provided, streamlining billing and enhancing patient care.

By providing subscriber and provider details through our React component, users can initiate the verification process effortlessly. The widget offers real-time feedback with success and error callbacks, simplifying integration into your application's UI.

See Eligibility Verification 🩻 for more details.

Embedding

The fullScreen prop controls the sizing behavior of the widget. When set to true, the widget expands to fill the entire viewport, providing a full-screen experience. Setting it to false keeps the widget within the width of its parent container, maintaining a 16:9 aspect ratio. This property ensures that the widget can be embedded in various layouts while preserving its visual integrity.

Example:

<div className="scanner-container" style={{ width: "800px" }}>
    <CardScanView 
        fullScreen={false}
        sessionToken={token}
        onSuccess={cardScanSuccess}
        onCancel={cardScanCancel}
        onError={cardScanError}
    />
</div>

Camera Options

Camera Configuration allow developers to preset the camera's view orientation for specific installation scenarios, such as mirrored cameras or kiosks. These settings ensure the camera view is correctly aligned and oriented during the initial setup of the application:

  • flipHorizontal: Enables horizontal flipping of camera view, reversing the left to right sides of the image (aka mirrored)

  • flipVertical: Enabled vertical flipping of camera view, swapping the top and bottom of the image when the camera or document is upside down.

<CardScanView 
    sessionToken={token}
    onSuccess={cardScanSuccess}
    cameraOptions={{
        flipHorizontal: false,
        flipVertical: true
    }}
/>

Camera Permissions Modal

When the react widget is unable to access the browser camera feed it will prompt the user to provide the necessary browser permissions. It displays a widget with a browser-specific video demonstrating how to grant permission to the camera.

This can be disabled by passing in false to the enableCameraPermissionModal prop.

Error Screens

Setup Failure

This screen will be shown on setup connection failure (websocket or initial REST API call), network error, auth failure (invalid or expired token), and camera error (without webToMobileHandOff or enableCameraPermissionModal enabled).

Scan Failure

This screen will be shown on direct upload of an invalid image (i.e. a photo of a cat) or when all 12+ scan attempts have been exhausted because of poor input quality or complete backend failure.

Are we missing something? Please let us know and we would be happy to add it. Contact support.

Last updated