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.3'   
}

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()
            }
        }
    }
}

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,

  // 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

PropRequiredTypeDescription

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

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

PropTypeDescription

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
            }
        }
    }

Last updated