React ⚛
Last updated
Last updated
Our CardScanView
react component makes it easy to add insurance card scanning and eligibility verification to any web application in 5 minutes or less.
Import the library widget and model into your project files:
You can optionally add the API client for more custom applications.
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
React: >=17.0.2
React-DOM: >=17.0.2
Prop | Required | Type | Description |
---|---|---|---|
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. |
cameraPermissionModalConfig | false | object | The |
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. |
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:
Note: All UI/UX Props are optional
Prop | Type | Description |
---|---|---|
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
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.
To use the onSuccess
prop, pass a function that receives the scanned card data:
In this example, the handleCardScanSuccess
function logs the scanned card data to the console when the scanning process is completed successfully.
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.
To use the onError
prop, pass a function that receives the error object:
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.
Error Type | Error Code | Error 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. |
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.
To use the onCancel
prop, pass a function that will be executed when the user cancels the scanning process:
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.
The onRetry
prop allows you to execute a custom function when a retry is triggered due to a scanning failure.
To use the onRetry
prop, pass a function that receives the retry event as an argument:
In this example, the handleRetry
function logs the retry event to the console when a retry is triggered.
The onProgress
prop allows you to execute a custom function to report progress during the scanning process.
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.
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.
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:
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.
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 { enabled: false }
to the cameraPermissionModalConfig
prop.
The cameraPermissionModalConfig
object allows customization of the Camera Permission Modal in the application. It provides the flexibility to set custom texts for various parts of the modal, enhancing the user experience by providing clear and relevant information.
Properties:
enabled:
Type: boolean
(Optional)
Description: A boolean flag to enable or disable the Camera Permission Modal. If this property is not provided, the modal will default to being enabled (true
).
Example: true
modalTitle:
Type: string
(Optional)
Description: Sets the title of the Camera Permission Modal. If this property is not provided, the modal will use the default title "Camera Permission Needed."
Example: "Access Required"
modalText:
Type: string
(Optional)
Description: Sets the main content text of the Camera Permission Modal. This text explains the reason why camera permission is needed. If this property is not provided, the modal will use the default text "This application needs access to the camera to scan your medical insurance card. Please allow access to the camera."
Example: "To proceed with the verification process, please allow camera access."
modalButton:
Type: string
(Optional)
Description: Sets the text displayed on the button in the Camera Permission Modal. If this property is not provided, the modal will use the default text "Try Again."
Example: "Allow Camera Access"
If the react widget can access the browser's camera, it will automatically request camera permission without manual intervention. This only occurs if there are no strict blocks or restrictions in place on the browser.
requestPermissionModalConfig
The requestPermissionModalConfig
object allows customization of the Request Permission Modal in the application. It provides the flexibility to set custom texts for various parts of the modal, enhancing the user experience by providing clear and relevant information.
Properties:
title:
Type: string
(Optional)
Description: Sets the title of the Request Permission Modal. If this property is not provided, the modal will use the default title "Waiting for camera permission"
text:
Type: string
(Optional)
Description: Sets the main content text of the Request Permission Modal. This text instruct that you must accept to turn on the camera. If this property is not provided, the modal will use the default text "Click Allow to grant camera permission."
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.
helpModalConfig
The helpModalConfig
object allows customization of the Help Modal in the application. It provides the flexibility to set custom texts for various parts of the modal, enhancing the user experience by providing clear and relevant information.
For the instructional video, there are six different versions tailored for each browser on both desktop and mobile:
Google Chrome (desktop version)
Google Chrome (mobile app version)
Safari (desktop version)
Safari (mobile app version)
Firefox (desktop version)
Firefox (mobile version)
Depending on the browser in which the SDK is opened, it will automatically detect and display the appropriate instructional video. If the user is on an unsupported browser, the Google Chrome video will be shown by default.
Properties:
title:
Type: string
(Optional)
Description: Sets the title of the Help Modal. If this property is not provided, the modal will use the default title "Setup camera"
text:
Type: string
(Optional)
Description: Sets the main content text of the Help Modal. This text explains the reason why camera permission is needed. If this property is not provided, the modal will use the default text "To access, you need to grant permission to use the device's camera. If the prompt hasn't appeared, try reloading the page."
instructionTexts:
Type: string
(Optional)
Description: Sets the instruction text of the Help Modal. This provides users with clear instructions on how to enable their cameras. If this property is not provided, the modal will use the default text "If the prompt does not appear on browser, follow this path Go to Settings > Privacy and Security > Camera. Then enable camera access and reload the page."
tryAgainText:
Type: string
(Optional)
Description: Sets the text of the try again button. This button will appear if the browser allows requesting camera permission without needing to navigate into the device settings. If this property is not provided, the modal will use the default text "Try again."
If the user declines camera permissions in the Request Permission modal, they will be redirected to the Camera Permission modal, with the 3 options available:
Retry Camera Access: Clicking this button will attempt to re-enable camera access and open the camera. In some cases, this button may not appear if the device restricts camera permissions for the browser.
Continue on Mobile Phone: If the user has a web-to-mobile handoff feature enabled, a button with a timer will be displayed. Once the timer expires, the Web-to-Mobile Handoff modal will appear. This option will not be available if the widget is opened on a mobile device.
Get Help: Clicking this option will redirect the user to the Help Modal.
cameraPermissionModalConfig
The cameraPermissionModalConfig
object allows customization of the Help Modal in the application. It provides the flexibility to set custom texts for various parts of the modal, enhancing the user experience by providing clear and relevant information.
Properties:
enabled:
Type: boolean
(Optional)
Description: A boolean flag to enable or disable the Camera Permission Modal and Help Modal . If this property is not provided, the modal will default to being enabled (true
).
title:
Type: string
(Optional)
Description: Sets the title of the Camera Permission Modal. If this property is not provided, the modal will use the default title "Camera permission needed"
text:
Type: string
(Optional)
Description: Sets the main content text of the Camera Permission Modal. This text explains the reason why camera permission is needed. If this property is not provided, the modal will use the default text "This application needs access to the camera to scan medical insurance card".
retryText:
Type: string
(Optional)
Description: Sets the text for retry button. If this property is not provided, the button will use the default text "Retry camera access"
webToMobileText:
Type: string
(Optional)
Description: Sets the text for web to mobile button. If this property is not provided, the button will use the default text "Continue on Mobile Phone"
helpText:
Type: string
(Optional)
Description: Sets the text for help button. If this property is not provided, the button will use the default text "Get help"
This modal is applicable only for mobile SDKs (React Native, Flutter, iOS, or Android) and indicates that the app does not have camera permission. When you click on go to settings it will redirect to the device configuration to enable the camera access.
noCameraModalConfig
The noCameraModalConfig
object allows customization of the No Camera Modal in the application. It provides the flexibility to set custom texts for various parts of the modal, enhancing the user experience by providing clear and relevant information.
Properties:
title:
Type: string
(Optional)
Description: Sets the title of the No Camera Modal. If this property is not provided, the modal will use the default title "No camera access"
instructions:
Type: string
(Optional)
Description: Sets the main content text of the No Camera Modal. This text explains where you need to navigate to enable the camera. If this property is not provided, the modal will use the default text "To scan your card, allow us to use your camera in Settings > Privacy > Camera"
settingsButton:
Type: string
(Optional)
Description: Sets the text for settings button. If this property is not provided, the button will use the default text "Go to settings"
The CardScanModel
class is designed to load and "warm" the TensorFlowJS model used during live scanning to detect insurance cards. Properly warming the model ensures it is ready for immediate use in the scanning process.
To utilize the CardScanModel
in your project, import it as follows:
While importing the class and warming the model are optional, doing so will result in faster widget initialization and happier users. To warm the model, call the warm
method once during the component mount. This initializes the model loading and warming process, making it ready for scanning.
Custom Model Path
Optionally, you can provide a custom model path to a local version of the model file or to a CDN that you control. Ensure the model files are included in your build folder. If the model cannot be loaded from the provided path, it will default to fetching the model from the CDN.
To include the model assets in your build system, configure your bundler (such as Webpack, Rollup, or a similar tool) to import all files from the assets/model-tfjs
folder in the npm package. The exact configuration will depend on your specific build setup and requirements.
Please reach out to support if you need help configuring your build system.
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).
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.