NHN Cloud > SDK使用ガイド > OCR > ID Card (Android)

事前準備

1. NHN Cloud Consoleで[AI Service > OCR]サービスを有効にします。
2. OCRコンソールでAppKeyとSecretKeyを確認します。

サポート環境

NHN Cloud ID Card RecognizerはAndroid 5.1以上(API level 22以上)で動作します。

プロジェクト設定

依存関係追加

アプリのbuild.gradleファイルにnhncloud-idcard-recognizer依存関係を追加します。

dependencies {
    ...
    // NHN Cloud ID Card Recognizer
    implementation 'com.nhncloud.android:nhncloud-idcard-recognizer:1.9.2'
}

CAMERA権限

ID Card Recognizerを使用するには Manifest.permission.CAMERA権限が必要です。 ID Card Recognizerを起動する前にカメラの権限を取得してください。

Id Card Recognizer使用

IdCardRecognizerインスタンス作成

ID Card Recognizerインスタンスを作成します。

val nhnCloudOcr = NhnCloudOcr.newBuilder(context)
        .appKey(APP_KEY)
        .secretKey(SECRET_KEY)
        .build()
val idCardRecognizer = nhnCloudOcr.createIdCardRecognizer()

IdCardRecognizerを始める

IdCardRecognizerのlaunch(Activity, IdCardRecognitionCallback)メソッドを呼び出して身分証認識を開始します。

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

認識データ使用

IDカード認識に成功すると、IDCardDataを継承実装したオブジェクトにIDカード認識データが渡されます。 身分証明書の種類によって、住民登録証はIdCardResidentDataオブジェクト、運転免許証はIdCardDriverDataオブジェクトが返されます。

個人情報保護のために身分証データは一般文字列ではなくSecureStringオブジェクトで返されます。 SecureString.charAt(index)メソッドは指定されたindexにある文字を返します。

IdCardDataで返される身分証明書認識情報をStringオブジェクトとして作成して使用するとセキュリティに脆弱です。
画面に表示するためにSecureTextView使用を参照してください。

when (data) {
    //ID card data is a SecureString object.
    is IdCardResidentData -> {
        //Use resident card's data.
        nameSecureTextView.setText(data.name);
        residentNumberSecureTextView.setText(data.residentNumber);
    }
    //Use driver license's data.
    is IdCardDriverData -> {
        ...
    }
}

身分証真偽確認

身分証の真偽確認のためにIdCardAuthenticatorインスタンスを作成します。 身分証認識結果であるIdCardDataを利用して真偽確認をリクエストできます。

身分証真偽確認結果はBooleanタイプで返されます。

真偽確認に使用されるIdCardDataのRequestKeyは、一度限りの値のため再使用できません。
RequestKeyは発行後1時間有効で、その後は使用できません。

val authenticator = nhnCloudOcr.createIdCardAuthenticator()
viewModelScope.launch(Dispatchers.IO) {
    try {
        //Use authenticity result
        isAuthenticity = authenticator.authenticate(idCardData)
    } catch (e : OcrException) {
        //Authenticity Error
    }
}

authenticateAsyncメソッドで呼び出したい場合はIdCardAuthenticityCallbackを実装して結果を受け取ることができます。

nhnCloudOcr.createIdCardAuthenticator()
    .authenticateAsync(idCardData) { result, isAuthenticity ->
        if (result.isSuccess) {
            //Use authenticity result
        } else {
            //Authenticity Error
        }
    }

身分証認識画面ユーザー定義

身分証認識画面をユーザー定義して使用できます。 ユーザー定義画面を構成するにはIdCardRecognizerの代わりにIdCardRecognitionServiceを使用する必要があります。

IdCardRecognitionServiceインスタンス作成

IdCardRecognitionServiceインスタンスを作成します。

val ocrServices = NhnCloudOcrServices.newBuilder(context)
        .appKey(APP_KEY)
        .secretKey(SECRET_KEY)
        .build()
val IdCardRecognitionService = ocrServices.createIdCardRecognitionService()

IdCardRecognitionServiceリスナー登録

setIdCardRecognitionListener()メソッドを使用してリスナーを登録します。 身分証が認識されるとIdCardRecognitionListenerを通じて結果が通知されます。

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

身分証認識後、必ずIdCardRecognitionService.stop()を呼び出してサービスを停止する必要があります。

認識結果処理

IdCardRecognitionListenerに渡されるIdCardRecognitionDataは信頼度(confidence rating)に関係なくすべての結果を返します。 したがって、下記のように信頼度(confidence rating)をチェックして、より正確な結果を使用できます。

IdCardRecognitionService.setIdCardRecognitionListener { result, data ->
    if (result.isSuccess && isConfident(data)) {
        // Recognition success.
        IdCardRecognitionService.stop()
    } else {
        // Recognition failure.
    }
}

private fun isConfident(data: IdCardRecognitionData): Boolean {
    //Returns success if the format of the data is correct and all confidences is 0.4 or higher
    when (data) {
        is IdCardResidentRecognitionData -> {
            //Resident number is in "123456-1234567" format.
            val residentNumbers = data.residentNumber.value.split('-')
            if (residentNumbers.size != 2 ||
                residentNumbers[0].length != 6 ||
                residentNumbers[1].length != 7) {
                return false
            }

            //Issued Date is in "yyyy.mm.dd." or "yyyy.mm.dd" format.
            //the month and day can be single digits, such as "yyyy.m.d".
            val dates = data.issueDate.value.split('.')
            if (!(dates.size == 3 || dates.size == 4)) {
                return false
            }

            return data.name.confidence>= 0.4 && 
                    data.residentNumber.confidence >= 0.4 && 
                    data.issueDate.confidence >= 0.4 && 
                    data.issuer.confidence >= 0.4
        }
        is IdCardDriverRecognitionData -> {
            //Resident number is in "123456-1234567" format.
            val residentNumbers = data.residentNumber.value.split('-')
            if (residentNumbers.size != 2 ||
                residentNumbers[0].length != 6 ||
                residentNumbers[1].length != 7) {
                return false
            }

            //driver license number has the format of "12-12-123456-78".
            val driverLicenseNumbers = data.driverLicenseNumber.value.split('-')
            if (driverLicenseNumbers.size != 4 ||
                driverLicenseNumbers[0].length != 2 ||
                driverLicenseNumbers[1].length != 2 ||
                driverLicenseNumbers[2].length != 6 ||
                driverLicenseNumbers[3].length != 2) {
                return false
            }

            //Issued Date is in "yyyy.mm.dd." or "yyyy.mm.dd" format.
            //the month and day can be single digits, such as "yyyy.m.d".
            val dates = data.issueDate.value.split('.')
            if (!(dates.size == 3 || dates.size == 4)) {
                return false
            }

            //The driver type additionally checks the driver license number, serial number, and license type.
            //condition is not checked because there is a case where the value does not exist.
            return data.name.confidence>= 0.4 && 
                    data.residentNumber.confidence >= 0.4 && 
                    data.issueDate.confidence >= 0.4 && 
                    data.issuer.confidence >= 0.4 &&
                    data.driverLicenseNumber.confidence >= 0.4 && 
                    data.licenseType.confidence >= 0.4 && 
                    data.serialNumber.confidence >= 0.4
        }
        else -> error("Invalid data.")
    }
}

認識データ使用

身分証の認識に成功すると、IdCardRecognitionDataを継承して実装したオブジェクトに身分証の認識データが渡されます。 身分証明書の種類によって、住民登録証はIdCardResidentRecognitionDataオブジェクト、運転免許証はIdCardDriverRecognitionDataオブジェクトで返されます。

個人情報保護のために身分証データは一般文字列ではなくSecureStringオブジェクトで返されます。 SecureString.charAt(index)メソッドは指定されたindexにある文字を返します。

IdCardRecognitionDataで返される身分証認識情報をStringオブジェクトとして作成して使用するとセキュリティに脆弱です。
画面に表示するためにSecureTextView使用を参照してください。

when (data) {
    //ID card data is a SecureString object.
    is IdCardResidentRecognitionData -> {
        //Use resident card's data.
        nameSecureTextView.setText(data.name.value);
        residentNumberSecureTextView.setText(data.residentNumber.value);
    }

    is IdCardDriverRecognitionData -> {
        //Use driver license's data.
        ...
    }
}

身分証真偽確認

身分証真偽確認のためにIdCardAuthenticityServiceインスタンスを作成します。 身分証認識結果であるIdCardRecognitionDataを利用して真偽確認をリクエストできます。

身分証真偽確認結果はBooleanタイプで返されます。

真偽確認に使用されるIdCardRecognitionDataのRequestKeyは、一回限りの値のため再使用できません。
RequestKeyは発行後1時間有効で、その後は使用できません。

val service = ocrServices.createIdCardAuthenticityService()
viewModelScope.launch(Dispatchers.IO) {
    try {
        //Use authenticity result
        isAuthenticity = service.authenticate(idCardRecognitionData)
    } catch (e : OcrException) {
        //Authenticity Error
    }
}

authenticateAsyncメソッドで呼び出したい場合はIdCardAuthenticityCallbackを実装して結果を受け取ることができます。

ocrServices.createIdCardAuthenticityService()
    .authenticateAsync(idCardRecognitionData) { result, isAuthenticity ->
        if (result.isSuccess) {
            //Use authenticity result
        } else {
            //Authenticity Error
        }
    }

Camera Preview構成

ActivityまたはFragmentのLayoutに下記のようにIdCardRecognitionCameraPreview追加して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.idcard.view.IdCardRecognitionCameraPreview
        android:id="@+id/camera_preview"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

バックグラウンド色の変更

スキャンガイド領域を除外した領域は半透明に見えます。 この領域の色を"app:guideBackgroundColor"プロパティを使用して設定します。

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

スキャンガイドビューユーザー定義

スキャンガイドビューをIdCardRecognitionCameraPreviewのサブビューとして配置して自由に定義することができます。 カスタマイズしたガイドビューは「app:guideView」プロパティを使用して設定します。

IdCardRecognitionCameraPreviewはConstraintLayoutを継承実装されています。

スキャンガイドビューのサイズは自動的に調整されます。

<com.nhncloud.android.ocr.idcard.view.IdCardRecognitionCameraPreview
    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.idcard.view.IdCardRecognitionCameraPreview>

身分証検出時のガイドビュー変更

身分証が検出された時、スキャンガイドビューの色または形を変更できます。 OcrDetectableインターフェイスを継承実装してsetDetected(Boolean)に渡される値に基づいてガイドビューの色または形を変更します。

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

サービス開始

IdCardRecognitionCameraPreviewのインスタンスを取得してIdCardRecognitionServiceを開始します。

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

サービス停止

アプリがバックグラウンドに切り替わるか身分証認識に成功したとき、IdCardRecognitionServiceを停止します。

idCardRecognitionService.stop()

サービス解除

ActivityまたはFragmentのViewがDestoryされたとき、IdCardRecognitionServiceを解除します。

idCardRecognitionService.release();

IdCardRecognizer Lifecycle設定

ActivityまたはFragmentのライフサイクルに基づいて以下のように呼び出します。

Activity

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

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

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

Fragment

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

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

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

画面キャプチャ防止

画面キャプチャ防止のためにActivityのonCreate()でsetContentView()が呼び出される前にWindowManager.LayoutParams.FLAG_SECUREを追加します。

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

詳細については、 WindowManager.LayoutParams.FLAG_SECUREを参照してください。

デバイスチェック

ID Card Recognition Serviceを開始する前に、アプリケーションを実行するデバイスでID Card Recognition Serviceを使用できる環境かどうかを確認できます。 この検査を行うには、IdCardRecognitionService.isAvailable(Context)メソッドを使用します。

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

SecureTextView使用

個人情報保護のために身分証データは一般文字列ではなくSecureStringオブジェクトで返されます。 身分証明書認識情報をStringオブジェクトとして使用すると、セキュリティに脆弱であり、データを画面に表示するためにSecureTextViewを使用できます。

<com.nhncloud.android.ocr.SecureTextView
    android:id="@+id/id_card_name_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:com_nhncloud_text_color="#ffffff"
    app:com_nhncloud_text_size="15sp"
    app:com_nhncloud_text_style="bold"/>

SecureTextViewのsetTextメソッドで表示するテキストを設定します。

val name = idCardData.name

val idCardNameView = findViewById<SecureTextView>(id_card_name_view)
idCardNameView.setText(name)

SecureTextGroup使用

複数行のテキストを表示する必要がある場合はSecureTextGroupを使用できます。

<com.nhncloud.android.ocr.SecureTextGroup
    android:id="@+id/id_card_license_type_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:com_nhncloud_text_color="#ffffff"
    app:com_nhncloud_text_size="15sp"
    app:com_nhncloud_text_style="bold"/>

SecureTextGroupのaddTextViewsメソッドは配列をパラメータとして受け取り、1つの要素ごとに1行のテキストに設定します。

//The license type is a SecureString array.
val licenseType = idCardData.idCardLicenseType.split('/')

val idCardLicenseTypeView = findViewById<SecureTextGroup>(id_card_license_type_view)
idCardLicenseTypeView.addTextViews(licenseType)

Class References

IdCardData

Method	Returns	Parameters	Descriptions
getRequestKey	SecureString		身分証真偽確認に使用されるRequestKeyを返します。
getIdType	String		身分証の種類を返します。 ("resident" or "driver")

IdCardResidentData

Method	Returns	Parameters	Descriptions
getName	SecureString		名前を返します。
getResidentNumber	SecureString		住民登録番号を返します。
getIssueDate	SecureString		発行日時を返します。
getIssuer	SecureString		発行機関を返します。

IdCardDriverData

Method	Returns	Parameters	Descriptions
getName	SecureString		名前を返します。
getResidentNumber	SecureString		住民登録番号を返します。
getIssueDate	SecureString		発行日時を返します。
getIssuer	SecureString		発行機関を返します。
getDriverLicenseNumber	SecureString		運転免許番号を返します。
getLicenseType	SecureString		免許の種類を返します。 免許の種類が2つ以上の場合、文字列内で「/」で区切られます。
getCondition	SecureString		免許条件を返します。 運転免許証に応じて該当値が存在しない場合は空白が返されます。
getSerialNumber	SecureString		暗号一連番号を返します。

IdCardRecognitionData

Method	Returns	Parameters	Descriptions
getOriginBitmap	Bitmap		原本画像を返します。
getDetectedBitmap	Bitmap		検出された画像を返します。 (ガイド領域の画像が返されます。)
getResolution	String		解像度情報を返します。 (推奨解像度以上はnormal、未満はlow)
getRequestKey	String		身分証真偽確認に使用されるRequestKeyを返します。
getIdType	String		身分証の種類を返します。 ("resident" or "driver")
getOriginJsonData	String		サーバーレスポンス結果を返します。

IdCardRecognitionData.IdCardValue

Method	Returns	Parameters	Descriptions
getValue	SecureString		身分証認識結果を返します。
getConfidence	String		身分証認識結果の信頼度を返します。

IdCardResidentRecognitionData

Method	Returns	Parameters	Descriptions
getName	IdCardValue		名前を返します。
getResidentNumber	IdCardValue		住民登録番号を返します。
getIssueDate	IdCardValue		発行日時を返します。
getIssuer	IdCardValue		発行機関を返します。

IdCardDriverRecognitionData

Method	Returns	Parameters	Descriptions
getName	IdCardValue		名前を返します。
getResidentNumber	IdCardValue		住民登録番号を返します。
getIssueDate	IdCardValue		発行日時を返します。
getIssuer	IdCardValue		発行機関を返します。
getDriverLicenseNumber	IdCardValue		運転免許番号を返します。
getLicenseType	IdCardValue		免許の種類を返します。 免許の種類が2つ以上の場合、文字列内で「/」で区切られます。
getCondition	IdCardValue		免許条件を返します。 運転免許証に応じて該当値が存在しない場合は空白が返されます。
getSerialNumber	IdCardValue		暗号一連番号を返します。

SecureTextView

Method	Returns	Parameters	Descriptions
setText		SecureString	SecureTextViewに表示するテキストを設定します。
setTextSize	float		テキストサイズを設定します。 サイズ単位はsp、基本設定は14spです。
setTextColor	int		テキスト色を設定します。 基本設定はColor.Black(0xFF000000)です。
setTypefaceStyle	Typeface, int		テキストの書体とスタイルを設定します。 基本スタイル設定はTypeface.NORMALです。

SecureTextGroup

Method	Returns	Parameters	Descriptions
addTextView		SecureString	SecureTextGroupに表示するテキストを追加します。
addTextViews		SecureString[]	SecureTextGroupに表示するテキストを追加します。
setTextSize	float		テキストサイズを設定します。 サイズ単位はsp、基本設定は14spです。
setTextColor	int		テキスト色を設定します。 基本設定はColor.Black(0xFF000000)です。
setTypefaceStyle	Typeface, int		テキストの書体とスタイルを設定します。 基本スタイル設定はTypeface.NORMALです。
setLetterSpacing	float		テキストの文字間隔を設定します。 基本設定は0emです。