Android 🤖

Our CardScanActivity Kotlin Activity makes it easy to add insurance card scanning to any Android application in 5 minutes or less.

Requirements

• Android API level 23 or higher

• AndroidX compatibility

• Kotlin coroutine compatibility

Installation

The library is published in the maven central repository, so installation is as simple as adding the dependency to your build.gradle

dependencies {
    implementation 'ai.cardscan:insurance-cardscan:0.3.5'   
}

Usage

Import the necessary classes from the library into your activity or fragment:

import ai.cardscan.insurance.CardScanActivity
// import ai.cardscan.insurance.data.*
import ai.cardscan.insurance.data.CardScanHelper
import ai.cardscan.insurance.data.CardScanConfig

Basic Example:

import ai.cardscan.insurance.CardScanActivity
import ai.cardscan.insurance.data.CardScanConfig
import android.os.Bundle
import android.view.View
import androidx.appcompat.app.AppCompatActivity

class OnboardingActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        findViewById<View>(R.id.btnScanCard).setOnClickListener {
            setUpCardScanHelper()
            launchCardScanActivity()
        }
    }

    private fun launchCardScanActivity() {
        CardScanActivity.launch(
            // Pass an activity to the launcher
            this@MainActivity,
            // A CardScanConfig instance to connect to the server and customize UI
            CardScanConfig(
                // your token goes here
                sessionToken = "xxx",
            ),
            // And other optional parameters to alter behavior
            closeAfterSuccess = true, // Close the scanner after successful scan? 
                                    // defaults to true
            closeAfterDelay = 1500 // If set to close automatically, 
                                // how long to wait after scan to close? In milliseconds
        )
    }
    
    
    private fun setUpCardScanHelper() {
        // 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 Props

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
backsideSupport	false	Boolean	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.

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:

fun handleCardScanSuccess(card: ScannedCard?) {
  print("Card scanned successfully: $card")
}

 private fun setUpCardScanHelper() {
        cardScanHelper = CardScanHelper(this).apply {
            onSuccess { card: ScannedCard ->
                handleCardScanSuccess(card)
            }
        }
    }
)

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:

fun handleCardScanError(card: CardError?) {
  print("Scanning failed: $card")
}

 private fun setUpCardScanHelper() {
        cardScanHelper = CardScanHelper(this).apply {
            onSuccess { card: ScannedCard ->
                handleCardScanSuccess(card)
            }
            onError { error: CardError? -> 
                handleCardScanError(error)
            }
        }
    }
)

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.

private fun setUpCardScanHelper() {
        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.

private fun setUpCardScanHelper() {
        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)
            }
        }
    }