Android 🤖

Our CardScanView 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.0'   
}

Usage

Import the library into your project files:

import ai.cardscan.insurance.CardScanActivity
// import ai.cardscan.insurance.data.*
import ai.cardscan.insurance.data.CardDetails
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() {

    private fun launchCardScanActivity() {
        CardScanActivity.launch(
            this@MainActivity,
            CardScanConfig(
                // your token goes here
                sessionToken = "xxx",
                onSuccess = { card ->
                    print(card)
                },
            )
        )
    }
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

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

Available Properties

When launchingCardScanActivity, a CardScanConfig instance should be passed with properties for server connection, callback handling and UI customization.

CardScanConfig(
  // Required
  sessionToken: token,
  live: false,
  onSuccess: onSuccess,

  // Recommended
  onCancel: onCancel,
  onError: onError,

  // Optional
  backsideSupport: scanBackside,
  onRetry: onRetry,

  // UI Customization
  messages: messages,
  messageFontSize: messageFontSize,
  messageTextColor: messageTextColor,
  autoSwitchActiveColor: autoSwitchActiveColor,
  autoSwitchInactiveColor: autoSwitchInactiveColor,
  progressBarColor: progressBarColor,
  widgetBackgroundColor: widgetBackgroundColor,
)

---

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
onSuccess	true	Function	Called on successful scan. The first argument is the scanned card.
onCancel	false	Function	Triggered when the user cancels the CardScanner UI.
onError	false	Function	Called when an error is returned by the API or the CardScanner fails to initalize.
backsideSupport	false	Boolean	Enable scanning of the front and back side of the card. Default: false
onRetry	false	Function	Called when a failed scan triggers a retry.

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:

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

CardScanActivity.launch(
  activity = this@MainActivity,
  CardScanConfig(
    sessionToken: token,
    onSuccess = { card ->
      handleCardScanSuccess(card)
    },
  )
)

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

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:

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

CardScanActivity.launch(
  activity = this@MainActivity,
  CardScanConfig(
    sessionToken: token,
    onSuccess = { card ->
      handleCardScanSuccess(card)
    },
    onError = { error ->
      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 Callback

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.

Usage

Pass a non-arguments function for onCancel property. It'll be executed after the user cancels the scanning process:

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import androidx.lifecycle.MutableLiveData
import androidx.lifecycle.ViewModel

class MainActivity : AppCompatActivity() {
    private lateinit var mainViewModel: MainViewModel
    
    private fun handleCardScanSuccess(card: ScannedCard?) {
      print("Card scanned successfully: $card")
    }
    
    private fun launchCardScanActivity() {
        CardScanActivity.launch(
            this@MainActivity,
            CardScanConfig(
                // your token goes here
                sessionToken = "xxx",
                onSuccess = { card ->
                    print(card)
                },
                onCancel = {
                    showCardScanWidget = false
                },
            )
        )
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        mainViewModel = ViewModelProvider(this).get(MainViewModel::class.java)
        
        mainViewModel.showCardScanner.observe(this, Observer { showCardScanner ->
            updateActivityUI(showCardScanner)
        })

        findViewById<View>(R.id.btnScanCard).setOnClickListener {
            launchCardScanActivity()
        }
    }
    
    private fun updateActivityUI(shouldButtonBeEnabled: Boolean) {
        findViewById<View>(R.id.btnScanCard).isEnabled = shouldButtonBeEnabled
    }
}

class MainViewModel : ViewModel() {
    private val _showCardScanner = MutableLiveData<Boolean>()
    val showCardScanner : LiveData<Boolean>
        get() = _showCardScanner

    init {
        showCardScanner.value = true // Initial value
    }

    fun updateShowCardScanner(showCardScanner: Boolean) {
        showCardScanner.value = showCardScanner
    }
}

In this example, we define in a ViewModel the showCardScanner variable as true. We conditionally enable/disable a button based on the value returned from mainViewModel of showCardScanner. onCancel will trigger updateActivityUI for setting the showCardScanner to false when the user cancels the scanning process.

onRetry Callback

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

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

fun handleRetry() {
  print("Retry triggered")
}

CardScanActivity.launch(
  activity = this@MainActivity,
  CardScanConfig(
    sessionToken: token,
    onSuccess = { card ->
      handleCardScanSuccess(card)
    },
    onRetry = {
      handleRetry()
    }
  )
)

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