NHN Cloud > SDK User Guide > Document Recognizer > Credit Card (Android)

Prerequisites

  1. Enable [AI Service > Document Recognizer] in NHN Cloud Console
  2. Check Appkey and SecretKey in Document Recognizer Console.

Supported Environment

NHN Cloud Credit Card Recognizer operates in Android 5.0 or higher (API level 21 or higher).

Set up Project

Add Dependency

Add dependencies of nhncloud-creditcard-recognizer to the build.gradle file of the app.

dependencies {
    ...
    // NHN Cloud Credit Card Recognizer
    implementation 'com.nhncloud.android:nhncloud-creditcard-recognizer:1.4.1'
}


CAMERA Permission

To use Credit Card Recognizer, the permission Manifest.permission.CAMERA is required. You must obtain the Camera permission before using Credit Card Recognizer.


Use Credit Card Recognizer

Create CreditCardRecognizer Instance

Create a Credit Card Recognizer instance.

val creditCardRecognizer = NhnCloudOcr.newBuilder(context)
        .appKey(APP_KEY)
        .secretKey(SECRET_KEY)
        .createCreditCardRecognizer()


Initiate CreditCardRecognizer

Initiate credit card recognition by calling the CreditCardRecognizer's launch(Activity, CreditCardRecognitionCallback) method.

creditCardRecognizer.launch(activity) { result, data ->
    if (result.isSuccess) {
        // Success.
    } else {
        // Failure.
    }
}


Use Recognition Data

When credit card recognition is successful, credit card recognition data is transferred to the CreditCardData object. For privacy protection, the credit card number and expiration date are returned as SecureString objects, not plain strings. The SecureString.charAt(index) method returns the character at the specified index.

It is vulnerable to security when you create and use the credit card recognition data that is returned as CreditCardData as a String object.

val cardNumbers = creditCardData.cardNumbers
// firstNumber is a SecureString object.
val firstNumber = cardNumbers[0]
firstNumberTextView1.text = if (firstNumber.isNotEmpty()) firstNumber[0].toString() else ""
firstNumberTextView2.text = if (firstNumber.length > 1) firstNumber[1].toString() else ""
firstNumberTextView4.text = if (firstNumber.length > 2) firstNumber[2].toString() else ""
firstNumberTextView3.text = if (firstNumber.length > 3) firstNumber[3].toString() else ""


Customize Credit Card Recognition Screen

You can customize and use the credit card recognition screen. You must use CreditCardRecognitionService instead of CreditCardRecognizer to configure your custom screen.

Create CreditCardRecognitionService Instance

Create a CreditCardRecognitionService instance.

val creditCardRecognitionService = NhnCloudOcrServices.newBuilder(context)
        .appKey(APP_KEY)
        .secretKey(SECRET_KEY)
        .createCreditCardRecognitionService()


Register CreditCardRecognitionService Listner

Register a listener using the setCreditCardRecognitionListener() method. When a credit card is recognized, the result is notified via the CreditCardRecognitionListener.

creditCardRecognitionService.setCreditCardRecognitionListener { result, data ->
    if (result.isSuccess) {
        // Recognition success.
        creditCardRecognitionService.stop()
    } else {
        // Recognition failure.
    }
}

You must stop the service by calling the creditCardRecognitionService.stop() after credit card recognition.


Process Recognition Result

CreditCardRecognitionData passed to CreditCardRecognitionListener will return all results regardless of confidence rating. Therefore, more accurate results can be used by checking the confidence rating as shown below.

creditCardRecognitionService.setCreditCardRecognitionListener { result, data ->
    if (result.isSuccess && isConfident(data)) {
        // Recognition success.
        creditCardRecognitionService.stop()
    } else {
    }
}

private fun isConfident(data: CreditCardRecognitionData): Boolean {
    // Returns success when the card number is greater than or equal to 4
    // and the confidence rating is greater than or equal to 0.4.
    with (data.cardNumbers) {
        if (size < 4) {
            return false
        }
        for (cardNumber in this) {
            if (cardNumber.confidence < 0.4) {
                return false
            }
        }
    }
    return true
}


Use Recognition Data

When credit card recognition is successful, credit card recognition data is transferred to the CreditCardRecognitionData object. For privacy protection, the credit card number and expiration date are returned as SecureString objects, not plain strings. The SecureString.charAt(index) method returns the character at the specified index.

It is vulnerable to security when you create and use the credit card recognition data that is returned as CreditCardRecognitionData as a String object.

val cardNumbers = creditCardData.cardNumbers
// firstCardNumber is a SecureString object.
val firstNumber = cardNumbers[0].value
firstNumberTextView1.text = if (firstNumber.isNotEmpty()) firstNumber[0].toString() else ""
firstNumberTextView2.text = if (firstNumber.length > 1) firstNumber[1].toString() else ""
firstNumberTextView4.text = if (firstNumber.length > 2) firstNumber[2].toString() else ""
firstNumberTextView3.text = if (firstNumber.length > 3) firstNumber[3].toString() else ""


Configure Camera Preview

Add CreditCardRecognitionCameraPreview to Activity or Layout of Fragment as follows to configure Camera Preview.

<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.nhncloud.android.ocr.creditcard.view.CreditCardRecognitionCameraPreview
        android:id="@+id/camera_preview"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</androidx.constraintlayout.widget.ConstraintLayout>


Change Background Color

Areas except for the scan guide area appear translucent. Set the colors of the areas by using the "app:guideBackgroundColor" property.

<com.nhncloud.android.ocr.creditcard.view.CreditCardRecognitionCameraPreview
    android:id="@+id/camera_preview"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:guideBackgroundColor="#33000000" />


Customize Scan Guide View

You can freely customize the scan guide view by placing it as a subview of the CreditCardRecognitionCameraPreview. Configure the user-defined guide view using the "app:guideView" property.

CreditCardRecognitionCameraPreview is implemented by inheriting ConstraintLayout.

The size of the scan guide view is automatically adjusted.

<com.nhncloud.android.ocr.creditcard.view.CreditCardRecognitionCameraPreview
    android:id="@+id/camera_preview"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:guideView="@id/guide_view">

    <com.yourapp.view.CustomGuideView
        android:id="@+id/guide_view"
        android:layout_width="0dp"
        android:layout_height="0dp"
        android:layout_marginTop="80dp"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent">

</com.nhncloud.android.ocr.creditcard.view.CreditCardRecognitionCameraPreview>


Change Guide View When Credit Card Is Detected

You can change the color or shape of the scan guide view when a credit card is detected. Change the color or shape of the guide view according to the value passed to setDetected(Boolean) after implementation inheritance of the CreditCardDetectable interface.

class CustomGuideView(
    context: Context, attrs: AttributeSet?
): View(context, attrs), CreditCardDetectable {
    override fun setDetected(detected: Boolean) {
        if (detected) {
            color = Color.GREEN
        } else {
            color = Color.WHITE
        }
    }

    ...
}


Initiate Service

Initiate CreditCardRecognitionService by obtaining the instances of CreditCardRecognitionCameraPreview.

val cameraPreview = findViewById<CreditCardRecognitionCameraPreview>(R.id.camera_preview)
try {
    creditCardRecognitionService.start(cameraPreview)
} catch (e: IOException) {
    // Camera is not available (in use or does not exist)
}


Stop Service

Stop creditCardRecognitionService when the app enters the background or credit card recognition is successful.

creditCardRecognitionService.stop()


Release Service

Release creditCardRecognitionService when Activity or Fragment's View is destroyed.

creditCardRecognitionService.release();


Set CreditCardRecognizer Lifecycle

Call as follows according to Activity or the lifecycle of Fragment.

Activity

override fun onResume() {
    super.onResume()
    creditCardRecognitionService.start(cameraPreview)
}

override fun onPause() {
    super.onPause()
    creditCardRecognitionService.stop()
}

override fun onDestroy() {
    super.onDestroy()
    creditCardRecognitionService.release()
}

Fragment

override fun onResume() {
    super.onResume()
    creditCardRecognitionService.start(cameraPreview)
}

override fun onPause() {
    super.onPause()
    creditCardRecognitionService.stop()
}

override fun onDestroyView() {
    super.onDestroyView()
    creditCardRecognitionService.release()
}


Set Scan Direction

Set a direction to scan the credit card.

creditCardRecognitionService.scanOrientation =
    CreditCardScanOrientation.HORIZONTAL // or CreditCardScanOrientation.HORIZONTAL


Prevent Screen Capture

To prevent screen capture, add WindowManager.LayoutParams.FLAG_SECURE before setContentView() is called from onCreate() of Activity.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    window.addFlags(WindowManager.LayoutParams.FLAG_SECURE)
    setContentView(R.layout.activity_main)
    ...
}

For more details, see WindowManager.LayoutParams.FLAG_SECURE.


Device Check

Before starting the Credit Card Recognition service, you can check whether the Credit Card Recognition service is available is on the device running the application. To perform this check, use the CreditCardRecognitionService.isAvailable(Context) method.

if (CreditCardRecognitionService.isAvailable(context)) {
    // Credit card recognition service is available.
} else {
    // Credit card recognition service is not available.
}

Class References

CreditCardData

Method Returns Parameters Descriptions
getFullCardNumber SecureString Return the full card number.
getCardNumbers SecureString[] Return the array of the card number.
getExpirationDate SecureString Return the expiration date.


CreditCardRecognitionData

Method Returns Parameters Descriptions
getOriginBitmap Bitmap Return the original image.
getDetectedBitmap Bitmap Return the detected image.
(The image of the guide area is returned.)
getResolution String Return the resolution information.
(Normal when over the recommended resolution, low when below the recommended resolution)
getFullCardNumber SecureString Return the full card number.
getCardNumbers CardNumber[] Return the array of the card number data (CardNumber).
getExpirationDate ExpirationDate Return the expiration date data (ExpirationDate).
getOriginJsonData String Return the server response result.


CreditCardRecognitionData.CardNumber

Method Returns Parameters Descriptions
getValue SecureString Return the card number recognition result.
getConfidence String Return the confidence of the card number recognition result.
getCoordinates Coordinates Return the list of coordinates of the card number recognition area.


CreditCardRecognitionData.ExpirationDate

Method Returns Parameters Descriptions
getValue SecureString Return the expiration date recognition result.
getConfidence String Return the confidence of expiration date recognition result.
getCoordinates Coordinates Return the list of coordinates of expiration date recognition result.


CreditCardRecognitionData.Coordinates

Method Returns Parameters Descriptions
getPoints Point[] Return the array of coordinates (Point).
getPoint Point int Return the coordinates
- LEFT_TOP: 0
- RIGHT_TOP: 1
- RIGHT_BOTTOM: 2
- LEFT_BOTTOM: 3


TOP