For the sdk to work properly, you need to handle permission logic for the camera (Manifest.permission.Camera) grant camera permission so we can access the device's camera and scan your insurance cards! More info at: https://developer.android.com/training/permissions/requesting
Suggestion for code to include with Cardscan launcher:
// Permission launcher, displays dialog asking for permissionval requestPermissionLauncher =registerForActivityResult( ActivityResultContracts.RequestPermission() ) { isGranted: Boolean ->if (isGranted) {// Permission is granted, you can launch Cardscan activity safelylaunchCardScanActivity() } else {// Permission denied or dismissed.// Explain to user that feature is unavailable, because permission// is needed to use it. } }
// Check permission status and act on it privatefunhandleScannerOpen() {when { ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA ) == PackageManager.PERMISSION_GRANTED -> {// Permission is granted, you can start// Cardscan activity safely.launchCardScanActivity() } ActivityCompat.shouldShowRequestPermissionRationale(this, Manifest.permission.CAMERA ) -> {// Show UI to app user to tell them why you need the permission.// This is a good place to take them to settings too// so they can grant permission there. }else-> {// Here you can directly ask for the permission requestPermissionLauncher.launch(Manifest.permission.CAMERA) } } }
Basic usage Example:
import ai.cardscan.insurance.CardScanActivityimport ai.cardscan.insurance.data.CardScanConfigimport android.os.Bundleimport android.view.Viewimport androidx.appcompat.app.AppCompatActivityclassOnboardingActivity : AppCompatActivity() {overridefunonCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)setContentView(R.layout.activity_main)findViewById<View>(R.id.btnScanCard).setOnClickListener {setUpCardScanHelper()launchCardScanActivity() } }privatefunlaunchCardScanActivity() { CardScanActivity.launch(// Pass an activity to the launcherthis@MainActivity,// A CardScanConfig instance to connect to the server and customize UICardScanConfig(// your token goes here sessionToken ="xxx", ),// And other optional parameters to alter behavior closeAfterSuccess =true, // Close the scanner after successful scan? // defaults to true closeAfterSuccessDelay =1500// If set to close automatically, // how long to wait after scan to close? In milliseconds closeAfterErrorDelay =2000// Cardscan activity is killed automatically after an error // You can decide between 0 and 30 seconds, how long to wait before closing
) }privatefunsetUpCardScanHelper() {// Helper class to setup observers and create the appropiate callbacks// CardScanHelper takes in a lifecycleOwner, // "this" in the case of setup within an activity,// or the host activity in the case of a fragment, or viewLifecycleOwner cardScanHelper =CardScanHelper(this).apply {onSuccess { card: ScannedCard -> Toast.makeText(this@MainActivity, "Card Scanned: ${card.cardId}", Toast.LENGTH_SHORT).show() }onError { error: CardError? -> Toast.makeText(this@MainActivity, "Error encountered!", Toast.LENGTH_SHORT).show()print(error?.message) }onRetry { Toast.makeText(this@MainActivity, "User retried after failed scan!", Toast.LENGTH_SHORT).show() }onCancel { Toast.makeText(this@MainActivity, "User closed the scanner with close button!", Toast.LENGTH_SHORT).show()
}onEligibilitySuccess { eligibility:Eligibility -> Toast.makeText(this@MainActivity, "Eligibility info found!", Toast.LENGTH_SHORT).show() }onEligibilityError { eligibilityError:EligibilityError? -> Toast.makeText(this@MainActivity, "Error during eligiblity check!", Toast.LENGTH_SHORT).show() } } }}
Available Properties
When launchingCardScanActivity, a CardScanConfig instance should be passed with properties for server connection and UI customization.
CardScanConfig(// Required sessionToken: token, live: false,// Optional backsideSupport: scanBackside, eligibility =EligibilityRequest( // We now support eligibility checks!Subscriber( firstName ="Subscriber's first name", lastName ="Subscriber's last name", dateOfBirth ="19020403"// Always in format YYYYMMDD ),Provider( firstName ="Provider's first name", lastName ="Provider's last name", npi ="12345677" ) )// UI Customization messages =CardScanMessages( autoCaptureTitle ="My Auto Capture Title", manualCaptureTitle ="My Manual Capture Title", processingTitle ="My Processing Title", frontSideCompletedTitle ="My FrontSide Completed Title", completedTitle ="My Completed Title", retryTitle ="Me Retry Title", errorTitle ="My Error Title", cameraErrorTitle ="My Camera Error Title" ) messageFontSize: messageFontSize, // Float messageTextColor: messageTextColor, // Int autoSwitchActiveColor: autoSwitchActiveColor, // Int autoSwitchInactiveColor: autoSwitchInactiveColor, // Int progressBarColor: progressBarColor, // Int widgetBackgroundColor: widgetBackgroundColor, // Int)
Main Config Props
Prop
Required
Type
Description
live
false
Boolean
Toggle the production or sandbox version. Default: false
Enable scanning of the front and back side of the card.
Default: false
eligibility
false
EligibilityRequest
Send an EligibilityRequest object with the properties shown above to perform an eligibility check.
UI/UX Customization Props
The card scanner view is designed to be 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.
messageFontSize
Float
Set the size of the text displayed by the UI.
messageTextColor
Int
Set the color of the text displayed by the UI.
messageBackgroundColor
Int
Set the background color of the text displayed by the UI.
autoSwitchActiveColor
Int
Set the color of the auto scan switch.
autoSwitchInactiveColor
Int
Set the color of the disabled auto scan switch.
progressBarColor
Int
Set the color of the progress bars or bounding box that surrounds the card scanning area.
widgetBackgroundColor
Int
Set the main background color for the widget.
Cardscan activity launcher props
Prop
Type
Description
activity
Activity
The activity from which the CardScan activity will be started. Usually MainActivity
properties
CardScanConfig
Object to set the parameters for the scanner
closeAfterSuccess
Boolean
Whether to automatically finish Cardscan activity after successful scan.
closeAfterSuccessDelay
Long
Time in milliseconds to wait before finishing Cardscan activity, after a successful scan.
closeAfterErrorDelay
Long
Time in milliseconds to wait before finishing Cardscan activity, after an error was thrown.
onSuccess Callback
onSuccess triggers when card scanning process completes successfully. This function receives the scanned card data as an argument.
Usage
To use the onSuccess callback, pass a function that receives the scanned card data to the onSuccess function in CardScanHelper:
In this example, the handleCardScanSuccess function logs the scanned card data to the console when the scanning process is completed successfully and your MainActivity or fragment resumes.
onError Callback
onError triggers after a failure occurs during the card scanning process. This function receives an error object as an argument.
Usage
Pass a function that receives the error object or implement your callback directly inside the helper:
In this example, the handleCardScanError logs the error object when a scanning failure occurs.
By using the onSuccess and onError callbacks, you can handle successful and failed scanning event with custom actions or display appropriate messages to the user.
onCancel and onRetry Callbacks
onCancel expects a function that will trigger after users cancel the card scanning process. This could be useful for tracking user behavior or displaying an appropriate message. onRetry expects a function that will trigger when your activity or fragment resumes, if the user had a retry of a scanning process.
privatefunsetUpCardScanHelper() { cardScanHelper =CardScanHelper(this).apply {onSuccess { card: ScannedCard ->handleCardScanSuccess(card) }onError { error: CardError? -> handleCardScanError(error) }onCancel {// Handle a user closing the scanner with the close button! }onRetry {// Triggered after the user retried a scan } } }
onEligibilitySuccess and onEligibilityError Callbacks
Both callbacks expect a function that will trigger in either case. onElibiligitySuccess callback will pass an Eligibility object and onEligibilityError will pas an EligibilityError object. Expect the same behavior as the other callbacks, this objects will be passed once your activity or fragment resumes.
privatefunsetUpCardScanHelper() { cardScanHelper =CardScanHelper(this).apply {onSuccess { card: ScannedCard ->handleCardScanSuccess(card) }onError { error: CardError? -> handleCardScanError(error) }onCancel {// Handle a user closing the scanner with the close button! }onRetry {// Triggered after the user retried a scan }onEligibilitySuccess { eligibility:Eligibility ->handleEligibilitySuccess(eligibility) }onEligibilityError { eligibilityError:EligibilityError? ->handleEligibilityError(eligibilityError) } } }