blinkid android下载blinkid android源代码下载

Blinkid SDK适用于Android

Blinkid Android SDK可让您在Android应用中建立出色的入职体验。

经过一项快速扫描，您的用户将能够从其身份证，护照，驾驶执照以及几乎任何其他政府发行的ID中提取信息。

Blinkid是：

快速地。实时数据提取小于400ms。比长达几分钟的填充要好得多。
安全的。首先，永远。即使用户的手机处于飞机模式，扫描也有效，这意味着个人信息永远不会触及第三方服务器。
聪明的。机器学习模型，以自动从全球180多个国家 /地区的读取和解析身份文档进行了优化，因此无需预先选择其中的任何一个。
轻的。旨在提高应用程序的可用性，而不是重量。
你用它做的。自定义并重塑默认UI或将其视为原样。由你决定。
不仅仅是强大的ID扫描仪。强大的数据提取，再加上强大的特权。取回裁剪的文档图像，现场打印的文档或数据匹配ID的两侧以获得奇偶校验。

要查看所有这些功能在工作中下载我们的免费演示应用程序：

准备好与集成破解吗？首先确保我们支持您的文档类型➡️完整列表。然后遵循以下准则。

快速开始
- 快速启动示例应用程序
- SDK集成
设备要求
Blinkid SDK集成级别
- 内置活动（ UISettings ）
- 内置碎片（ RecognizerRunnerFragment ）
- 自定义UX带有RecognizerRunnerView
- 直接API
  - 使用直接API识别Android位图和自定义相机帧
  - 使用直接API进行String识别（解析）
  - 了解Directapi的状态机
  - 使用Direct API，而ensenizerrunnerview处于活动状态
  - 将直接API与组合识别器一起使用
可用的内置活动和覆盖
- BlinkIdUISettings和BlinkIdOverlayController
- DocumentUISettings
- LegacyDocumentVerificationUISettings
- 翻译和本地化
使用RecognizerRunner和RecognizerRunnerView处理处理活动
Recognizer概念和RecognizerBundle
- Recognizer概念
- RecognizerBundle
  - 通过活动之间传递Recognizer物对象
可用识别者列表
- 框架抓手识别器
- 成功框架抓取器识别器
- 光明的识别者
  - 光明的单侧识别器
  - Blinkid多边识别器
  - 机器可读的旅行文档识别器
  - 机器可读的旅行文件合并识别器
  - 护照识别器
  - 签证识别器
  - ID条形码识别器
  - 文件面部识别器
将Blinkid嵌入另一个SDK中
处理器体系结构注意事项
- 减少应用程序的最终尺寸
  - 删除处理器体系结构的后果
- 将Blinkid与其他本地图书馆结合在一起
  - 解决libc++_shared.so冲突。
故障排除
常见问题解答和已知问题
其他信息
- Blinkid SDK尺寸
- API参考
- 接触

快速开始

快速启动示例应用程序

开放式Android Studio。
在快速启动对话框中选择导入项目（Eclipse ADT，Gradle等） 。
在文件对话框中，选择BlinkidSample文件夹。
等待项目加载。如果Android Studio要求您重新加载启动项目，请选择Yes 。

包括示例应用程序

Blinkid-Aminimalsample展示了Blinkid库的快速而简单的集成
Blinkid-composeminimalsampleamper在使用Compose时展示了Blinkid库的简单集成
Blinkid-MinimalsalSampleadvanced展示了Blinkid库的简单集成，可以自定义识别器和UI设置
Blinkid-AllRecognizersSampame展示了几乎所有可用功能的集成。该示例应用程序最适合对支持功能进行快速测试
Blinkid-CustomBindSample演示了自定义扫描活动中合并识别器的高级自定义UI集成和使用
Blinkid-ComposeFragments样本演示了片段中的高级自定义UI集成和组合识别器的使用，同时使用撰写
Blinkid-Customuisample展示了自定义扫描活动中的高级集成
Blinkid-directapsample演示了如何执行Android位图的扫描
Blinkid-Imagessample演示了如何获取文档图像
Blinkid-Overlaysample演示了如何在您的活动中使用RecognizerRunnerFragment并内置相机叠加控制器

SDK集成

添加Blinkid依赖性

在您的build.gradle中，将Blinkid Maven存储库添加到存储库列表

 repositories {
    maven { url 'https://maven.microblink.com' }
}

将Blinkid添加为依赖性，并确保将transitive设置为true

 dependencies {
    implementation('com.microblink:blinkid:6.12.0@aar') {
        transitive = true
    }
}

进口Javadoc

Android Studio应自动从Maven依赖性导入Javadoc。如果没有发生，您可以通过遵循以下步骤手动执行此操作：

在Android Studio项目侧边栏中，确保启用项目视图
扩展External Libraries条目（通常这是项目视图中的最后一个条目）
找到blinkid-6.12.0条目，右键单击并选择Library Properties...
Library Properties弹出窗口将出现
单击窗口的左下角的第二个+按钮（包含+的一个小地球）
定义文档URL的窗口将出现
输入以下地址： https://blinkid.github.io/blinkid-android/
单击OK

进行第一次扫描

需要有效的许可证密钥来初始化扫描。您可以在Microblink Developer Hub上注册后请求免费的试用许可证密钥。许可证注定要包含您应用程序的包装名称，因此请确保在询问时输入正确的软件包名称。
下载您的许可证文件并将其放入应用程序的资产文件夹中。确保在使用SDK中的任何其他类之前，请确保设置许可证密钥，否则您将获得运行时异常。
我们建议您扩展Android应用程序类，并以此方式设置许可证：
爪哇
```
 public class MyApplication extends Application {
    @ Override
    public void onCreate () {
        MicroblinkSDK . setLicenseFile ( "path/to/license/file/within/assets/dir" , this );
    }
}
```
科特林
```
 public class MyApplication : Application () {
    override fun onCreate () {
        MicroblinkSDK .setLicenseFile( " path/to/license/file/within/assets/dir " , this )
    }	
}
```

在您的主要活动中，通过覆盖onActivityResult方法来定义和创建ActivityResultLauncher对象。 OneSideDocumentScan和TwoSideDocumentScan都可以互换使用，而实施没有差异。唯一的功能差异是， OneSideDocumentScan仅扫描文档的一侧，并且TwoSideDocumentScan扫描文档的一侧以上。

爪哇

 ActivityResultLauncher < Void > resultLauncher = registerForActivityResult (
         new TwoSideDocumentScan (),
         twoSideScanResult -> {
             ResultStatus resultScanStatus = twoSideScanResult . getResultStatus ();
             if ( resultScanStatus == ResultStatus . FINISHED ) {
                 // code after a successful scan
                 // use result.getResult() for fetching results, for example:
                 String firstName = twoSideScanResult . getResult (). getFirstName (). value ();
             } else if ( resultScanStatus == ResultStatus . CANCELLED ) {
                 // code after a cancelled scan
             } else if ( resultScanStatus == ResultStatus . EXCEPTION ) {
                 // code after a failed scan
             }
         }
 );

科特林

 private val resultLauncher =
     registerForActivityResult( TwoSideDocumentScan ()) { twoSideScanResult : TwoSideScanResult ->
         when (twoSideScanResult.resultStatus) {
             ResultStatus . FINISHED -> {
                 // code after a successful scan
                 // use twoSideScanResult.result for fetching results, for example:
                 val firstName = twoSideScanResult.result?.firstName?.value()
             }
             ResultStatus . CANCELLED -> {
                 // code after a cancelled scan
             }
             ResultStatus . EXCEPTION -> {
                 // code after a failed scan
             }
             else -> {}
         }
     }

Kotlin组成

@Composable
fun createLauncher (): ActivityResultLauncher < Void ?> {
     return rememberLauncherForActivityResult( TwoSideDocumentScan ()) { twoSideScanResult : TwoSideScanResult -> 
         when (twoSideScanResult.resultStatus) {
             ResultStatus . FINISHED -> {
                 // code after a successful scan
                 // use twoSideScanResult.result for fetching results, for example:
                 val firstName = twoSideScanResult.result?.firstName?.value()
             }
             ResultStatus . CANCELLED -> {
                 // code after a cancelled scan
             }
             ResultStatus . EXCEPTION -> {
                 // code after a failed scan
             }
             else -> {}
         }
     }
}

扫描后，将要更新result ，即OneSideScanResult或TwoSideScanResult对象实例。您可以定义onActivityResult函数覆盖中数据发生的情况（Kotlin代码也覆盖了此函数，但它是隐式的）。在twoSideScanResult.getResult()方法（Kotlin中的twoSideScanResult.result ）中可以访问结果。

通过调用ActivityResultObject并调用ActivityResultLauncher.launch ：开始扫描过程：

爪哇

 // method within MyActivity from previous step
public void startScanning () {
    // Start scanning
    resultLauncher . launch ( null );
}

科特林

 // method within MyActivity from previous step
public fun startScanning () {
    // Start scanning
    resultLauncher.launch()
}

Kotlin组成

 // within @Composable function or setContent block
val resultLauncher = createLauncher()
resultLauncher.launch()

结果将在回调中可用，这是在上一步中定义的ActivityResultObject中定义的。

设备要求

Android版本

Blinkid需要Android API级别21或更新。

相机

相机视频预览分辨率也很重要。为了进行成功的扫描，相机预览分辨率必须至少为720p。请注意，相机预览分辨率与视频记录分辨率不同。

处理器体系结构

Blinkid用ARMV7和ARM64本地图书馆二进制文件分发。

Blinkid是一个本地库，用C ++编写，可用于多个平台。因此， Blinkid无法在具有晦涩的硬件体系结构的设备上使用。我们仅针对最受欢迎的Android Abis编辑了Blinkid Native代码。

即使在设置许可证密钥之前，您也应该检查当前设备上是否支持BlinkID （请参见下一节：兼容性检查）。试图从SDK调用依赖本机代码的任何方法，例如许可证检查，在具有不支持的CPU体系结构的设备上会崩溃您的应用程序。

如果将Blinkid库与其他包含本机代码的库相结合到您的应用程序中，请确保与所有本机库的架构匹配。

有关更多信息，请参见处理器体系结构注意事项部分。

兼容性检查

这是您可以检查设备上是否支持Blinkid的方法：

爪哇

 // check if BlinkID is supported on the device,
RecognizerCompatibilityStatus status = RecognizerCompatibility . getRecognizerCompatibilityStatus ( this );
if ( status == RecognizerCompatibilityStatus . RECOGNIZER_SUPPORTED ) {
    Toast . makeText ( this , "BlinkID is supported!" , Toast . LENGTH_LONG ). show ();
} else if ( status == RecognizerCompatibilityStatus . NO_CAMERA ) {
    Toast . makeText ( this , "BlinkID is supported only via Direct API!" , Toast . LENGTH_LONG ). show ();
} else if ( status == RecognizerCompatibilityStatus . PROCESSOR_ARCHITECTURE_NOT_SUPPORTED ) {
    Toast . makeText ( this , "BlinkID is not supported on current processor architecture!" , Toast . LENGTH_LONG ). show ();
} else {
    Toast . makeText ( this , "BlinkID is not supported! Reason: " + status . name (), Toast . LENGTH_LONG ). show ();
}

科特林

 // check if _BlinkID_ is supported on the device,
when ( val status = RecognizerCompatibility .getRecognizerCompatibilityStatus( this )) {
    RecognizerCompatibilityStatus . RECOGNIZER_SUPPORTED -> {
        Toast .makeText( this , " BlinkID is supported! " , Toast . LENGTH_LONG ).show()
    }
    RecognizerCompatibilityStatus . NO_CAMERA -> {
        Toast .makeText( this , " BlinkID is supported only via Direct API! " , Toast . LENGTH_LONG ).show()
    }
    RecognizerCompatibilityStatus . PROCESSOR_ARCHITECTURE_NOT_SUPPORTED -> {
        Toast .makeText( this , " BlinkID is not supported on current processor architecture! " , Toast . LENGTH_LONG ).show()
    }
    else -> {
        Toast .makeText( this , " BlinkID is not supported! Reason: " + status.name, Toast . LENGTH_LONG ).show()
    }
}

一些识别器需要带有自动对焦的相机。如果您尝试在不支持自动对焦的设备上使用它们，则会出现错误。为了防止这种情况，您可以通过调用识别器是否需要自动对焦来检查其需求方法。

如果您已经有一系列识别器，则可以轻松地滤除需要使用以下代码段从数组中自动对焦的识别器：

爪哇

 Recognizer [] recArray = ...;
if (! RecognizerCompatibility . cameraHasAutofocus ( CameraType . CAMERA_BACKFACE , this )) {
    recArray = RecognizerUtils . filterOutRecognizersThatRequireAutofocus ( recArray );
}

科特林

 var recArray : Array < Recognizer > = .. .
if ( ! RecognizerCompatibility .cameraHasAutofocus( CameraType . CAMERA_BACKFACE , this )) {
    recArray = RecognizerUtils .filterOutRecognizersThatRequireAutofocus(recArray)
}

Blinkid SDK集成级别

您可以根据您的用例和自定义需求将Blinkid集成到您的应用中：

一行文档扫描（ OneSideDocumentScan和TwoSideDocumentScan ） - SDK可以处理所有内容，您只需要启动我们的内置活动并处理结果，没有自定义选项
内置活动（ UISettings ） - SDK处理大部分工作，您只需要定义识别器，设置，启动我们的内置活动和处理结果，自定义选项有限
内置片段（ RecognizerRunnerFragment ） - 在您自己的活动中内置活动中重用扫描UX
自定义UX（ RecognizerRunnerView ） - SDK在您必须实现完全自定义扫描UX时处理相机管理
直接API（ RecognizerRunner ） - SKD仅处理识别，而您必须从相机或文件提供图像

一行文档扫描（ `OneSideDocumentScan`和`TwoSideDocumentScan` ）

OneSideDocumentScan和TwoSideDocumentScan是包含所有必要的设置定义的类，以便快速启动SDK内置扫描活动。它允许用户跳过所有设置步骤，例如UISettings和RecognizerBundle ，然后直接进行扫描。

如表演所示，您的第一个扫描只需要对结果侦听器的定义，以定义扫描结果将发生的事情，并调用实际的扫描功能。

内置活动（ `UISettings` ）

UISettings是一个包含SDK内置扫描活动的所有必要设置的课程。它配置扫描活动行为，字符串，图标和其他UI元素。您应该使用ActivityRunner来启动由UISettings配置的扫描活动，如下示例所示。

我们提供多个专门用于不同扫描方案的UISettings课程。每个UISettings对象都有属性，可以通过适当的设置器方法更改。例如，您可以使用setCameraSettings Metod自定义相机设置。

所有可用的UISettings课程都在此处列出。

在您的主要活动中，创建将执行图像识别的识别器对象，将其配置并将其放入识别器绑定对象。您可以在此处查看有关可用识别器和RecognizerBundle的更多信息。

例如，要扫描支持的文档，请以这样的方式配置您的识别器：

爪哇

 public class MyActivity extends Activity {
    private BlinkIdMultiSideRecognizer mRecognizer ;
    private RecognizerBundle mRecognizerBundle ;
    
    @ Override
    protected void onCreate ( Bundle bundle ) {
        super . onCreate ( bundle );
        
        // setup views, as you would normally do in onCreate callback
        
        // create BlinkIdMultiSideRecognizer
        mRecognizer = new BlinkIdMultiSideRecognizer ();
        
        // bundle recognizers into RecognizerBundle
        mRecognizerBundle = new RecognizerBundle ( mRecognizer );
    }
}

科特林

 public class MyActivity : Activity () {
    private lateinit var mRecognizer : BlinkIdMultiSideRecognizer
    private lateinit var mRecognizerBundle : RecognizerBundle

    override fun onCreate ( bundle : Bundle ) {
        
        // setup views, as you would normally do in onCreate callback  
        
        // create BlinkIdMultiSideRecognizer
        mRecognizer = BlinkIdMultiSideRecognizer ()
        
        // build recognizers into RecognizerBundle
        mRecognizerBundle = RecognizerBundle (mRecognizer)
    } 
}

通过创建BlinkIdUISettings并调用ActivityRunner.startActivityForResult来开始识别过程：

爪哇

 // method within MyActivity from previous step
public void startScanning () {
    // Settings for BlinkIdActivity
    BlinkIdUISettings settings = new BlinkIdUISettings ( mRecognizerBundle );
    
    // tweak settings as you wish
    
    // Start activity
    ActivityRunner . startActivityForResult ( this , MY_REQUEST_CODE , settings );
}

科特林

 // method within MyActivity from previous step
public fun startScanning () {
    // Settings for BlinkIdActivity
    val settings = BlinkIdUISettings (mRecognizerBundle)
    
    // tweak settings as you wish
    
    // Start activity
    ActivityRunner .startActivityForResult( this , MY_REQUEST_CODE , settings)
}

扫描完成后，将在您的活动中调用onActivityResult ，在这里您可以获得扫描结果。

爪哇

 @ Override
protected void onActivityResult ( int requestCode , int resultCode , Intent data ) {
    super . onActivityResult ( requestCode , resultCode , data );
    
    if ( requestCode == MY_REQUEST_CODE ) {
        if ( resultCode == Activity . RESULT_OK && data != null ) {
            // load the data into all recognizers bundled within your RecognizerBundle
            mRecognizerBundle . loadFromIntent ( data );
            
            // now every recognizer object that was bundled within RecognizerBundle
            // has been updated with results obtained during scanning session
            
            // you can get the result by invoking getResult on recognizer
            BlinkIdMultiSideRecognizer . Result result = mRecognizer . getResult ();
            if ( result . getResultState () == Recognizer . Result . State . Valid ) {
                // result is valid, you can use it however you wish
            }
        }
    }
}

科特林

 override protected fun onActivityResult ( requestCode : Int , resultCode : Int , data : Intent ) {
    super .onActivityResult(requestCode, resultCode, data);
    
    if (requestCode == MY_REQUEST_CODE ) {
        if (resultCode == Activity . RESULT_OK && data != null ) {
            // load the data into all recognizers bundled within your RecognizerBundle
            mRecognizerBundle.loadFromIntent(data)
            
            // now every recognizer object that was bundled within RecognizerBundle
            // has been updated with results obtained during scanning session
            
            // you can get the result by invoking getResult on recognizer
            val result = mRecognizer.result
            if (result.resultState == Recognizer . Result . State . Valid ) {
                // result is valid, you can use it however you wish
            }
        }
    }
}

有关可用识别器和RecognizerBundle的更多信息，请参见识别器串和可用的识别器。

内置碎片（ `RecognizerRunnerFragment` ）

如果您想在自己的活动中重复使用我们内置的活动UX，请使用RecognizerRunnerFragment 。将托管RecognizerRunnerFragment的活动必须实现ScanningOverlayBinder接口。试图将RecognizerRunnerFragment添加到无法实现该接口的活动中会导致ClassCastException 。

ScanningOverlayBinder负责返回ScanningOverlay的non-null实现 - 将在RecognizerRunnerFragment上管理UI的类。不建议创建自己的ScanningOverlay实现，而是使用此处列出的一个实现之一。

这是主持RecognizerRunnerFragment的活动的最低示例：

爪哇

 public class MyActivity extends AppCompatActivity implements RecognizerRunnerFragment . ScanningOverlayBinder {
    private BlinkIdMultiSideRecognizer mRecognizer ;
    private RecognizerBundle mRecognizerBundle ;
    private BlinkIdOverlayController mScanOverlay ;
    private RecognizerRunnerFragment mRecognizerRunnerFragment ;

    @ Override
    protected void onCreate ( Bundle savedInstanceState ) {
        super . onCreate ();
        setContentView ( R . layout . activity_my_activity );
        mScanOverlay = createOverlay ();
        if ( null == savedInstanceState ) {
            // create fragment transaction to replace R.id.recognizer_runner_view_container with RecognizerRunnerFragment
            mRecognizerRunnerFragment = new RecognizerRunnerFragment ();
            FragmentTransaction fragmentTransaction = getSupportFragmentManager (). beginTransaction ();
            fragmentTransaction . replace ( R . id . recognizer_runner_view_container , mRecognizerRunnerFragment );
            fragmentTransaction . commit ();
        } else {
            // obtain reference to fragment restored by Android within super.onCreate() call
            mRecognizerRunnerFragment = ( RecognizerRunnerFragment ) getSupportFragmentManager (). findFragmentById ( R . id . recognizer_runner_view_container );
        }
    }

    @ Override
    @ NonNull
    public ScanningOverlay getScanningOverlay () {
        return mScanOverlay ;
    }

    private BlinkIdOverlayController createOverlay () {
        // create BlinkIdMultiSideRecognizer
        mRecognizer = new BlinkIdMultiSideRecognizer ();

        // bundle recognizers into RecognizerBundle
        mRecognizerBundle = new RecognizerBundle ( mRecognizer );

        BlinkIdUISettings settings = new BlinkIdUISettings ( mRecognizerBundle );

        return settings . createOverlayController ( this , mScanResultListener );
    }

    private final ScanResultListener mScanResultListener = new ScanResultListener () {
        @ Override
        public void onScanningDone ( @ NonNull RecognitionSuccessType recognitionSuccessType ) {
            // pause scanning to prevent new results while fragment is being removed
            mRecognizerRunnerFragment . getRecognizerRunnerView (). pauseScanning ();

            // now you can remove the RecognizerRunnerFragment with new fragment transaction
            // and use result within mRecognizer safely without the need for making a copy of it

            // if not paused, as soon as this method ends, RecognizerRunnerFragments continues
            // scanning. Note that this can happen even if you created fragment transaction for
            // removal of RecognizerRunnerFragment - in the time between end of this method
            // and beginning of execution of the transaction. So to ensure result within mRecognizer
            // does not get mutated, ensure calling pauseScanning() as shown above.
        }
        @ Override
        public void onUnrecoverableError ( @ NonNull Throwable throwable ) {
        }
    };
    
}

Kotlin组成

 package com.microblink.blinkid

class MainActivity : AppCompatActivity (), RecognizerRunnerFragment.ScanningOverlayBinder {
    private lateinit var mRecognizer : BlinkIdMultiSideRecognizer
    private lateinit var mRecognizerRunnerFragment : RecognizerRunnerFragment
    private lateinit var mRecognizerBundle : RecognizerBundle
    private lateinit var mScanOverlay : BlinkIdOverlayController

    override fun onCreate ( savedInstanceState : Bundle ? ) {
        super .onCreate(savedInstanceState)
        if ( ! ::mScanOverlay.isInitialized) {
            mScanOverlay = createOverlayController()
        }
        setContent {
            this . run {
                // viewBinding has to be set to 'true' in buildFeatures block of the build.gradle file
                AndroidViewBinding ( RecognizerRunnerLayoutBinding ::inflate) {
                    mRecognizerRunnerFragment =
                        fragmentContainerView.getFragment< RecognizerRunnerFragment >()
                }
            }
        }
    }

    override fun getScanningOverlay (): ScanningOverlay {
        return mScanOverlay
    }

    private fun createOverlay (): BlinkIdOverlayController {
        // create BlinkIdMultiSideRecognizer
        val mRecognizer = BlinkIdMultiSideRecognizer ()

        // bundle recognizers into RecognizerBundle
        mRecognizerBundle = RecognizerBundle (mRecognizer)

        val settings = BlinkIdUISettings (mRecognizerBundle)

        return settings.createOverlayController( this , mScanResultListener)
    }

    private val mScanResultListener : ScanResultListener = object : ScanResultListener {
        override fun onScanningDone ( p0 : RecognitionSuccessType ) {
            // pause scanning to prevent new results while fragment is being removed
            mRecognizerRunnerFragment !! .recognizerRunnerView !! .pauseScanning()

            // now you can remove the RecognizerRunnerFragment with new fragment transaction
            // and use result within mRecognizer safely without the need for making a copy of it

            // if not paused, as soon as this method ends, RecognizerRunnerFragments continues
            // scanning. Note that this can happen even if you created fragment transaction for
            // removal of RecognizerRunnerFragment - in the time between end of this method
            // and beginning of execution of the transaction. So to ensure result within mRecognizer
            // does not get mutated, ensure calling pauseScanning() as shown above.
        }
        override fun onUnrecoverableError ( p0 : Throwable ) {
        }
    }
    
}

请参阅SDK提供的示例应用程序，以获取更详细的示例，并确保主机活动的方向设置为nosensor或已启用了配置更改（IE在配置更改时未重新启动）。有关更多信息，请检查扫描方向部分。

自定义UX带有`RecognizerRunnerView`

本节讨论了如何将识别性的Ernizerrunnerview嵌入到您的扫描活动中并进行扫描。

首先确保RecognizerRunnerView是您活动中的成员字段。这是必需的，因为您需要将所有活动的生命周期事件传递给RecognizerRunnerView 。
建议将您的扫描活动保持在一个方向上，例如portrait或landscape 。设置sensor作为扫描活动的方向，每当设备方向变化时，都会触发全面的活动。这将提供非常糟糕的用户体验，因为相机和Blinkid Native Library每次都必须重新启动。有针对这种行为的措施将在后面讨论。
在您的活动的onCreate方法中，创建一个新的RecognizerRunnerView ，设置识别器包含识别器，该识别器将通过视图使用，定义将处理强制性摄像机事件的cameraeventsListener，定义ScanResultListener，定义scanResultListener，该scanResultListener将在识别完成时接收呼叫，然后呼叫其create方法。之后，添加应该在相机视图顶部布局的视图。
使用setLifecycle方法传递活动的生命周期，以自动处理生命周期事件。

以下是将RecognizerRunnerView性的最低示例作为您活动中唯一的观点：

 public class MyScanActivity extends AppCompatActivity {
    private static final int PERMISSION_CAMERA_REQUEST_CODE = 42 ;
    private RecognizerRunnerView mRecognizerRunnerView ;
    private BlinkIdMultiSideRecognizer mRecognizer ;
    private RecognizerBundle mRecognizerBundle ;

    @ Override
    protected void onCreate ( Bundle savedInstanceState ) {
        super . onCreate ( savedInstanceState );

        // create BlinkIdMultiSideRecognizer
        mRecognizer = new BlinkIdMultiSideRecognizer ();

        // bundle recognizers into RecognizerBundle
        mRecognizerBundle = new RecognizerBundle ( mRecognizer );
        // create RecognizerRunnerView
        mRecognizerRunnerView = new RecognizerRunnerView ( this );
        
        // set lifecycle to automatically call recognizer runner view lifecycle methods
        mRecognizerRunnerView . setLifecycle ( getLifecycle ());

        // associate RecognizerBundle with RecognizerRunnerView
        mRecognizerRunnerView . setRecognizerBundle ( mRecognizerBundle );

        // scan result listener will be notified when scanning is complete
        mRecognizerRunnerView . setScanResultListener ( mScanResultListener );
        // camera events listener will be notified about camera lifecycle and errors
        mRecognizerRunnerView . setCameraEventsListener ( mCameraEventsListener );

        setContentView ( mRecognizerRunnerView );
    }

    @ Override
    public void onConfigurationChanged ( Configuration newConfig ) {
        super . onConfigurationChanged ( newConfig );
        // changeConfiguration is not handled by lifecycle events so call it manually
        mRecognizerRunnerView . changeConfiguration ( newConfig );
    }

    private final CameraEventsListener mCameraEventsListener = new CameraEventsListener () {
        @ Override
        public void onCameraPreviewStarted () {
            // this method is from CameraEventsListener and will be called when camera preview starts
        }

        @ Override
        public void onCameraPreviewStopped () {
            // this method is from CameraEventsListener and will be called when camera preview stops
        }

        @ Override
        public void onError ( Throwable exc ) {
            /**
             * This method is from CameraEventsListener and will be called when
             * opening of camera resulted in exception or recognition process
             * encountered an error. The error details will be given in exc
             * parameter.
             */
        }

        @ Override
        @ TargetApi ( 23 )
        public void onCameraPermissionDenied () {
            /**
             * Called in Android 6.0 and newer if camera permission is not given
             * by user. You should request permission from user to access camera.
             */
            requestPermissions ( new String []{ Manifest . permission . CAMERA }, PERMISSION_CAMERA_REQUEST_CODE );
            /**
             * Please note that user might have not given permission to use
             * camera. In that case, you have to explain to user that without
             * camera permissions scanning will not work.
             * For more information about requesting permissions at runtime, check
             * this article:
             * https://developer.android.com/training/permissions/requesting.html
             */
        }

        @ Override
        public void onAutofocusFailed () {
            /**
             * This method is from CameraEventsListener will be called when camera focusing has failed.
             * Camera manager usually tries different focusing strategies and this method is called when all
             * those strategies fail to indicate that either object on which camera is being focused is too
             * close or ambient light conditions are poor.
             */
        }

        @ Override
        public void onAutofocusStarted ( Rect [] areas ) {
            /**
             * This method is from CameraEventsListener and will be called when camera focusing has started.
             * You can utilize this method to draw focusing animation on UI.
             * Areas parameter is array of rectangles where focus is being measured.
             * It can be null on devices that do not support fine-grained camera control.
             */
        }

        @ Override
        public void onAutofocusStopped ( Rect [] areas ) {
            /**
             * This method is from CameraEventsListener and will be called when camera focusing has stopped.
             * You can utilize this method to remove focusing animation on UI.
             * Areas parameter is array of rectangles where focus is being measured.
             * It can be null on devices that do not support fine-grained camera control.
             */
        }
    };
    
    private final ScanResultListener mScanResultListener = new ScanResultListener () {
        @ Override
        public void onScanningDone ( @ NonNull RecognitionSuccessType recognitionSuccessType ) {
            // this method is from ScanResultListener and will be called when scanning completes
            // you can obtain scanning result by calling getResult on each
            // recognizer that you bundled into RecognizerBundle.
            // for example:

            BlinkIdMultiSideRecognizer . Result result = mRecognizer . getResult ();
            if ( result . getResultState () == Recognizer . Result . State . Valid ) {
                // result is valid, you can use it however you wish
            }

            // Note that mRecognizer is stateful object and that as soon as
            // scanning either resumes or its state is reset
            // the result object within mRecognizer will be changed. If you
            // need to create a immutable copy of the result, you can do that
            // by calling clone() on it, for example:

            BlinkIdMultiSideRecognizer . Result immutableCopy = result . clone ();

            // After this method ends, scanning will be resumed and recognition
            // state will be retained. If you want to prevent that, then
            // you should call:
            mRecognizerRunnerView . resetRecognitionState ();
            // Note that reseting recognition state will clear internal result
            // objects of all recognizers that are bundled in RecognizerBundle
            // associated with RecognizerRunnerView.

            // If you want to pause scanning to prevent receiving recognition
            // results or mutating result, you should call:
            mRecognizerRunnerView . pauseScanning ();
            // if scanning is paused at the end of this method, it is guaranteed
            // that result within mRecognizer will not be mutated, therefore you
            // can avoid creating a copy as described above

            // After scanning is paused, you will have to resume it with:
            mRecognizerRunnerView . resumeScanning ( true );
            // boolean in resumeScanning method indicates whether recognition
            // state should be automatically reset when resuming scanning - this
            // includes clearing result of mRecognizer
        }
    };
    
}

扫描活动的方向

如果AndroidManifest.xml中的Activity的screenOrientation属性设置为sensor ， fullSensor或类似的活动，则每当设备从肖像变为景观，反之亦然，将重新启动活动。在重新启动活动时，将调用其onPause ， onStop和onDestroy方法，然后将重新创建新的活动。这是扫描活动的潜在问题，因为在其生命周期中，它控制着相机和本地库 - 重新启动该活动将触发相机和本地库的重新启动。这是一个问题，因为从景观到肖像的方向变化，反之亦然，将非常慢，从而降低了用户体验。我们不建议这样的设置。

为此，我们建议将您的扫描活动设置为portrait或landscape模式，并手动处理设备方向更改。为了帮助您，无论活动的screenOrientation如何， RecognizerRunnerView支持将添加将旋转的子观点添加。您将希望旋转的视图（例如包含按钮，状态消息等视图）使用AddChildView方法RecognizerRunnerView 。该方法的第二个参数是一个布尔值，该参数定义了您要添加的视图是否将使用设备旋转。为了定义允许的方向，请实现OrientationAllowEdlistener接口，并使用Method setOrientationAllowedListener将其添加到RecognizerRunnerView中。这是旋转摄像头覆盖的推荐方法。

但是，如果您真的想将screenOrientation属性设置为sensor或类似的筛选属性，并且希望Android处理扫描活动的方向更改，那么我们建议将活动的configChanges属性设置为orientation|screenSize 。这将使Android在设备方向更改时不要重新启动您的活动。取而代之的是，将调用Activity的onConfigurationChanged方法，以便可以通知活动的配置更改。在实现此方法时，您应该调用RecognizerView的changeConfiguration方法，以便它可以使其相机表面和儿童视图适应新配置。

直接API

本节将描述如何使用直接API识别Android位图而无需相机。您可以在应用程序中的任何地方使用直接API，而不仅仅是通过活动。

图像识别性能在很大程度上取决于输入图像的质量。当使用相机管理（从相机扫描）时，我们会尽力获取具有最佳质量的相机框架。另一方面，当使用直接API时，您需要提供高质量的图像，而无需模糊和眩光以成功识别。

使用直接API识别Android位图和自定义相机帧

首先，您需要使用getingletonIninstance获得对ventizerrunner singleton的引用。
其次，您需要初始化识别器跑步者。
初始化后，您可以使用Singleton来处理：

例如，从画廊中获得的Android Bitmaps 。使用识别bitbitmap或识别bitmapwithRevithizer。
例如，当您使用自己的或第三方摄像头管理时，由自定义相机视频帧构建的视频Images 。识别将针对速度进行优化，并将依靠连续的视频帧之间的时间差，以产生最佳的识别结果。使用识别videoimage或识别vIDEOIMAGEWITHRECOGNIZER。
当您需要对不属于视频流的一部分的单个或几个图像进行彻底扫描时Images仍需要从单个InputImage中获得最佳结果。 inputImage类型来自我们的SDK，也可以使用ImageBuilder创建它。使用识别量或识别词。

当您想从多个识别中删除所有缓存数据时，例如，当您想扫描其他文档和/或重新启动扫描时，您需要重置识别状态。
不要忘记在使用后终止识别器跑步者Singleton（这是共享资源）。

这是用于识别Android位图的直接API使用的最小示例：

 public class DirectAPIActivity extends Activity {
    private RecognizerRunner mRecognizerRunner ;
    private BlinkIdMultiSideRecognizer mRecognizer ;
    private RecognizerBundle mRecognizerBundle ;

    @ Override
    protected void onCreate ( Bundle savedInstanceState ) {
        super . onCreate ();
        // initialize your activity here
        // create BlinkIdMultiSideRecognizer
        mRecognizer = new BlinkIdMultiSideRecognizer ();

        // bundle recognizers into RecognizerBundle
        mRecognizerBundle = new RecognizerBundle ( mRecognizer );

        try {
            mRecognizerRunner = RecognizerRunner . getSingletonInstance ();
        } catch ( FeatureNotSupportedException e ) {
            Toast . makeText ( this , "Feature not supported! Reason: " + e . getReason (). getDescription (), Toast . LENGTH_LONG ). show ();
            finish ();
            return ;
        }

        mRecognizerRunner . initialize ( this , mRecognizerBundle , new DirectApiErrorListener () {
            @ Override
            public void onRecognizerError ( Throwable t ) {
                Toast . makeText ( DirectAPIActivity . this , "There was an error in initialization of Recognizer: " + t . getMessage (), Toast . LENGTH_SHORT ). show ();
                finish ();
            }
        });
    }

    @ Override
    protected void onResume () {
        super . onResume ();
        // start recognition
        Bitmap bitmap = BitmapFactory . decodeFile ( "/path/to/some/file.jpg" );
        mRecognizerRunner . recognizeBitmap ( bitmap , Orientation . ORIENTATION_LANDSCAPE_RIGHT , mScanResultListener );
    }

    @ Override
    protected void onDestroy () {
        super . onDestroy ();
        mRecognizerRunner . terminate ();
    }

    private final ScanResultListener mScanResultListener = new ScanResultListener () {
        @ Override
        public void onScanningDone ( @ NonNull RecognitionSuccessType recognitionSuccessType ) {
            // this method is from ScanResultListener and will be called
            // when scanning completes
            // you can obtain scanning result by calling getResult on each
            // recognizer that you bundled into RecognizerBundle.
            // for example:

            BlinkIdMultiSideRecognizer . Result result = mRecognizer . getResult ();
            if ( result . getResultState () == Recognizer . Result . State . Valid ) {
                // result is valid, you can use it however you wish
            }
        }
    };

}

scanResultListener.scanningdone方法被调用您发送到识别的每个输入映像。您可以使用同一文档的不同图像来调用RecognizerRunner.recognize*方法，以提高阅读精度，直到您在听众的onScanningDone方法中获得成功的结果。当您使用自己的或第三方摄像头管理时，这很有用。

使用直接API进行`String`识别（解析）

一些识别者支持String识别。它们可以通过直接API使用来解析给定String并返回数据，就像在输入图像上使用时一样。当在String上执行识别时，无需OCR。输入String使用方式与识别图像时使用的OCR输出相同。

String的识别可以与上一节中描述的图像识别相同的方式执行。

唯一的区别是，应称为识别字符串识别方法之一：

认可
在识别方面识别

了解Directapi的状态机

Direct API的RecognizerRunner Singleton是一台可以在3个州之一中的州机器： OFFLINE ， READY和WORKING 。

当您获得对RecognizerRunner singleton的引用时，它将处于OFFLINE状态。
您可以通过调用初始化方法来初始化RecognizerRunner 。如果您在RecognizerRunner处于OFFLINE状态时调用initialize方法，则将获得IllegalStateException 。
成功初始化后， RecognizerRunner将移至READY状态。现在，您可以调用任何recognize*方法。
在使用任何recognize*方法开始识别时， RecognizerRunner将转移到WORKING状态。如果您尝试在RecognizerRunner不READY状态时调用这些方法，您将获得IllegalStateException
识别在背景线程上执行，因此可以安全地从UI线程调用所有RecognizerRunner's方法
识别完成后， RecognizerRunner首先移回READY状态，然后调用提供的ScanResultListener的scanningdone方法。
请注意，将在背景处理线程上调用ScanResultListener的onScanningDone方法，因此请确保您在此回调中不执行UI操作。还要注意，即使在过渡到READY状态后， RecognizerRunner在onScanningDone方法完成之前，即使在刚刚调用了任何recognize*方法。这是为了确保与RecognizerRunner RecognizerBundle捆绑在一起的识别器的结果未经修改，而可能在onScanningDone方法中使用。
通过调用terminate方法， RecognizerRunner singleton将发布其所有内部资源。请注意，即使呼叫terminate后，您可能会在terminate时onScanningDone工作。
可以从任何RecognizerRunner singleton的状态调用terminate方法
您可以使用方法getCurrentState观察RecognizerRunner singleton的状态

使用Direct API，而ensenizerrunnerview处于活动状态

nessizerrunnerview和RecognizerRunner都使用与管理本机代码相同的内部单例。这个单身人士处理本地库的初始化和终止，并将识别器传播到本地库。可以将RecognizerRunnerView和RecognizerRunner一起使用，因为内部单例将确保使用正确的同步和正确的识别设置。如果您在使用RecognizerRunner与RecognizerRunnerView结合使用时遇到问题，请告诉我们！

将直接API与组合识别器一起使用

当您使用合并的识别器和两个文档侧面的图像时，您需要多次调用RecognizerRunner.recognize* 。首先将其称为文档的第一侧的图像，直到读取为止，然后使用第二侧的图像。合并的识别器成功读取第一侧后，自动切换到第二侧扫描。要在完成第一侧扫描完成时被通知，您必须通过MetadataCallbacks设置FirstSiderEcognitionCallback。如果您不需要这些信息，例如，当每个文档端只有一个图像时，请不要设置FirstSideRecognitionCallback ，并在处理第二个侧面图像之后，在scanResultListener中检查识别succescessType。

可用的内置活动和覆盖

`BlinkIdUISettings`和`BlinkIdOverlayController`

BlinkIdOverlayController实现了用于扫描身份文档的新UI，最佳设计可与新的BlinkIdMultiSideRecognizer和BlinkIdSingleSideRecognizer一起使用。它实现了几个新功能：

搜索阶段的清晰指示，当Blinkid搜索ID文档时
明确的进度指示，当Blinkid忙于OCR和数据提取时
当不支持文档时明确消息
视觉指示用户需要将文档更靠近相机
当使用BlinkidMultisiderEcognizer时，视觉指示文档前侧的数据与文档背面的数据不匹配。

新的UI允许用户以任何方向扫描文档。如果您在背面扫描条形码，我们建议强制景观取向，因为在该方向上的成功率将更高。

启动使用BlinkIdOverlayController的内置活动，请使用BlinkIdUISettings 。

扫描覆盖主题

要自定义覆盖层，请通过BlinkIdUISettings.setOverlayViewStyle()方法或ReticleOverlayView构造器提供您的自定义样式资源。您可以通过在您的样式中提供以下属性来自定义上面屏幕截图上标记的元素：

出口

mb_exitScanDrawable可绘制图标
请注意，您可以使用BlinkIdUISettings.setShowCancelButton(false)禁用此元素

火炬

mb_torchOnDrawable启用火炬时显示的图标可绘制
mb_torchOffDrawable禁用火炬时显示的图标可绘制
请注意，您可以使用BlinkIdUISettings.setShowTorchButton(false)禁用此元素

指示

mb_instructionsTextAppearance将用作android:textAppearance
mb_instructionsBackgroundDrawable -drawable -drawable用于背景
mb_instructionsBackgroundColor用于背景的颜色

手电筒警告

mb_flashlightWarningTextAppearance将用作android:textAppearance
mb_flashlightWarningBackgroundDrawable -drawable -drawable用于背景
请注意，您可以使用BlinkIdUISettings.setShowFlashlightWarning(false)禁用此元素

卡图标

mb_cardFrontDrawable卡片翻转动画中显示的图标可绘制，代表卡的前侧
mb_cardBackDrawable卡片翻转动画中显示的图标可绘制，代表卡的背面

标线

mb_reticleDefaultDrawable标线处于中性状态时显示可绘制
mb_reticleSuccessDrawable可绘制的标线处于成功状态时（扫描成功）
mb_reticleErrorDrawable标线处于错误状态时显示的可绘制
mb_reticleColor用于旋转标线元件的颜色
mb_reticleDefaultColor用于中性状态的标线颜色
mb_reticleErrorColor用于标线处于错误状态的颜色
mb_successFlashColor用于闪光效果的颜色成功扫描

简介对话框和入职对话框

为了自定义这两个对话框的可见性和样式，请使用BlinkIdUISettings中提供的方法。

控制简介对话框可见性的方法是BlinkIdUISettings.setShowIntroductionDialog(boolean showIntroductionDialog) ，默认情况下将其设置为true，这意味着将显示“简介”对话框。

控制入门对话框可见性的方法是BlinkIdUISettings.setShowOnboardingInfo(boolean showOnboardingInfo) ，默认情况下将其设置为true，这意味着将显示“简介”对话框。

还有一种控制“显示帮助”的延迟的方法。在帮助按钮上方显示的工具提示。如果先前显示入板的方法为真，则将显示按钮本身。设置工具提示延迟长度的方法是BlinkIdUISettings.setShowTooltipTimeIntervalMs(long showTooltipTimeIntervalMs) 。时间参数以毫秒为单位。

延迟的默认设置为12秒（12000毫秒）。

通过提供以下属性，可以以与上一章中解释的方式进行自定义和主题来进行这些介绍和入职元素：

帮助按钮

mb_helpButtonDrawable启用帮助按钮时显示的可绘制
mb_helpButtonBackgroundColor用于帮助按钮背景的颜色
mb_helpButtonQuestionmarkColor用于帮助按钮的颜色前景
请注意，如果禁用了登机屏幕，则该元素将被禁用

帮助工具提示

mb_helpTooltipBackground可绘制的绘制，当帮助工具提示弹出时，该背景显示为背景
mb_helpTooltipColor用于帮助工具提示背景的颜色
mb_helpTooltipTextAppearance将用作android:textAppearance

简介对话框

mb_introductionBackgroundColor用于简介屏幕背景的颜色
mb_introductionTitleTextAppearance将用作android:textAppearance
mb_introductionMessageTextAppearance将用作android:textAppearance
mb_introductionButtonTextAppearance将用作android:textAppearance
请注意，您可以使用BlinkIdUISettings.setShowIntroductionDialog(false)禁用此元素

入职对话框

mb_onboardingBackgroundColor用于入型屏幕背景的颜色
mb_onboardingPageIndicatorColor用于登机屏幕中的圆形页面指示器的颜色
mb_onboardingTitleTextAppearance将用作android:textAppearance
mb_onboardingMessageTextAppearance将用作android:textAppearance
mb_onboardingButtonTextAppearance将用作android:textAppearance
请注意，您可以使用BlinkIdUISettings.setShowOnboardingInfo(false)禁用此元素

警报对话框

SDK调用的警报对话框具有自己的一组属性，可以在styles.xml中修改。

MB_alert_dialog是一个扩展Theme.AppCompat.Light.Dialog.Alert主题的主题，并使用应用程序主题的默认颜色。为了更改这些警报对话框中的属性，而无需更改用户应用程序中的其他属性， MB_alert_dialog主题需要覆盖。

< style name = " MB_alert_dialog " parent = " Theme.AppCompat.Light.Dialog.Alert " >
    < item name = " android:textSize " >TEXT_SIZE</ item >
    < item name = " android:background " >COLOR</ item >
    < item name = " android:textColorPrimary " >COLOR</ item >
    < item name = " colorAccent " >COLOR</ item >
</ style >

未覆盖的属性将使用应用程序主题的默认颜色和大小。

colorAccent Attibute用于更改“警报”对话框按钮的颜色。如果更改了应用程序主题的colorAccent属性，则此警报对话框按钮颜色也将更改。但是，覆盖MB_alert_dialog主题及其其中的此属性将确保更改Microblink SDK中的按钮颜色。如果应用程序主题扩展了一个主题，请参见MaterialComponents集合集（例如Theme.MaterialComponents.Light.NoActionBar ），则只能通过覆盖colorOnPrimary属性而不是colorAccent属性来更改上述按钮颜色。

`DocumentUISettings`

DocumentUISettings启动了使用BlinkIdOverlayController和替代UI的活动。它最适合扫描各种卡文档的单个文档侧，不应与组合识别器一起使用，因为它没有提供有关何时切换到背面的用户说明。

`LegacyDocumentVerificationUISettings`

LegacyDocumentVerificationUISettings启动了使用替代UI的BlinkIdOverlayController的活动。它最适合组合识别器，因为它可以管理单个摄像头打开的多个文档侧面的扫描，并指导用户完成扫描过程。它也可用于单侧扫描身份证，护照，驾驶执照等。

翻译和本地化

内置活动和覆盖物中使用的字符串可以定位于任何语言。如果您在自定义扫描活动或片段中使用RecognizerRunnerView （有关更多信息，请参见本章），则应像其他任何Android应用程序一样处理本地化。 RecognizerRunnerView不使用字符串或可绘制物，它仅使用assets/microblink文件夹中的资产。这些资产不得触摸，因为识别正确工作所需的必要条件。

但是，如果您使用我们的内置活动或覆盖层，它们将使用LibBlinkID.aar中包装的资源。AAR在相机视图顶部显示字符串和图像。我们已经准备了几种语言的字符串，您可以开箱即用。您也可以修改这些字符串，也可以添加自己的语言。

要使用一种语言，您必须从代码中启用它：

要使用某种语言，在应用程序启动时，在打开SDK的任何UI组件之前，您应该调用Method LanguageUtils.setLanguageAndCountry(language, country, context) 。例如，您可以这样将语言设置为克罗地亚语：
```
 // define BlinkID language
LanguageUtils . setLanguageAndCountry ( "hr" , "" , this );
```

添加新语言

Blinkid可以轻松地翻译成其他语言。 LibBlinkID.aar中的res文件夹。AAR存档中的文件夹values ，其中包含strings.xml此文件包含英语字符串。为了进行Croatian翻译，请在您的项目中创建一个文件夹values-hr ，然后将strings.xml的副本放入其中（您可能需要提取LibBlinkID.aar档案以访问这些文件）。 Then, open that file and translate the strings from English into Croatian.

Changing strings in the existing language

To modify an existing string, the best approach would be to:

Choose a language you want to modify. For example Croatian ('hr').
Find strings.xml in folder res/values-hr of the LibBlinkID.aar archive
Choose a string key which you want to change. For example: <string name="MBBack">Back</string>
In your project create a file strings.xml in the folder res/values-hr , if it doesn't already exist
Create an entry in the file with the value for the string which you want. For example: <string name="MBBack">Natrag</string>
Repeat for all the string you wish to change

Handling processing events with `RecognizerRunner` and `RecognizerRunnerView`

Processing events, also known as Metadata callbacks are purely intended for giving processing feedback on UI or to capture some debug information during development of your app using BlinkID SDK. For that reason, built-in activities and fragments handle those events internally. If you need to handle those events yourself, you need to use either RecognizerRunnerView or RecognizerRunner.

Callbacks for all events are bundled into the MetadataCallbacks object. Both RecognizerRunner and RecognizerRunnerView have methods which allow you to set all your callbacks.

We suggest that you check for more information about available callbacks and events to which you can handle in the javadoc for MetadataCallbacks class.

Please note that both those methods need to pass information about available callbacks to the native code and for efficiency reasons this is done at the time setMetadataCallbacks method is called and not every time when change occurs within the MetadataCallbacks object. This means that if you, for example, set QuadDetectionCallback to MetadataCallbacks after you already called setMetadataCallbacks method, the QuadDetectionCallback will not be registered with the native code and you will not receive its events.

Similarly, if you, for example, remove the QuadDetectionCallback from MetadataCallbacks object after you already called setMetadataCallbacks method, your app will crash with NullPointerException when our processing code attempts to invoke the method on removed callback (which is now set to null ). We deliberately do not perform null check here because of two reasons:

it is inefficient
having null callback, while still being registered to native code is illegal state of your program and it should therefore crash

Remember , each time you make some changes to MetadataCallbacks object, you need to apply those changes to to your RecognizerRunner or RecognizerRunnerView by calling its setMetadataCallbacks method.

`Recognizer` concept and `RecognizerBundle`

This section will first describe what is a Recognizer and how it should be used to perform recognition of the images, videos and camera stream. Next, we will describe how RecognizerBundle can be used to tweak the recognition procedure and to transfer Recognizer objects between activities.

RecognizerBundle is an object which wraps the Recognizers and defines settings about how recognition should be performed. Besides that, RecognizerBundle makes it possible to transfer Recognizer objects between different activities, which is required when using built-in activities to perform scanning, as described in first scan section, but is also handy when you need to pass Recognizer objects between your activities.

List of all available Recognizer objects, with a brief description of each Recognizer , its purpose and recommendations how it should be used to get best performance and user experience, can be found here .

The `Recognizer` concept

The Recognizer is the basic unit of processing within the BlinkID SDK. Its main purpose is to process the image and extract meaningful information from it. As you will see later, the BlinkID SDK has lots of different Recognizer objects that have various purposes.

Each Recognizer has a Result object, which contains the data that was extracted from the image. The Result object is a member of corresponding Recognizer object and its lifetime is bound to the lifetime of its parent Recognizer object. If you need your Result object to outlive its parent Recognizer object, you must make a copy of it by calling its method clone() .

Every Recognizer is a stateful object, that can be in two states: idle state and working state . While in idle state , you can tweak Recognizer object's properties via its getters and setters. After you bundle it into a RecognizerBundle and use either RecognizerRunner or RecognizerRunnerView to run the processing with all Recognizer objects bundled within RecognizerBundle , it will change to working state where the Recognizer object is being used for processing. While being in working state , you cannot tweak Recognizer object's properties. If you need to, you have to create a copy of the Recognizer object by calling its clone() , then tweak that copy, bundle it into a new RecognizerBundle and use reconfigureRecognizers to ensure new bundle gets used on processing thread.

While Recognizer object works, it changes its internal state and its result. The Recognizer object's Result always starts in Empty state. When corresponding Recognizer object performs the recognition of given image, its Result can either stay in Empty state (in case Recognizer failed to perform recognition), move to Uncertain state (in case Recognizer performed the recognition, but not all mandatory information was extracted), move to StageValid state (in case Recognizer successfully scanned one part/side of the document and there are more fields to extract) or move to Valid state (in case Recognizer performed recognition and all mandatory information was successfully extracted from the image).

As soon as one Recognizer object's Result within RecognizerBundle given to RecognizerRunner or RecognizerRunnerView changes to Valid state, the onScanningDone callback will be invoked on same thread that performs the background processing and you will have the opportunity to inspect each of your Recognizer objects' Results to see which one has moved to Valid state.

As already stated in section about RecognizerRunnerView , as soon as onScanningDone method ends, the RecognizerRunnerView will continue processing new camera frames with same Recognizer objects, unless paused. Continuation of processing or resetting recognition will modify or reset all Recognizer objects's Results . When using built-in activities, as soon as onScanningDone is invoked, built-in activity pauses the RecognizerRunnerView and starts finishing the activity, while saving the RecognizerBundle with active Recognizer objects into Intent so they can be transferred back to the calling activities.

`RecognizerBundle`

The RecognizerBundle is wrapper around Recognizers objects that can be used to transfer Recognizer objects between activities and to give Recognizer objects to RecognizerRunner or RecognizerRunnerView for processing.

The RecognizerBundle is always constructed with array of Recognizer objects that need to be prepared for recognition (ie their properties must be tweaked already). The varargs constructor makes it easier to pass Recognizer objects to it, without the need of creating a temporary array.

The RecognizerBundle manages a chain of Recognizer objects within the recognition process. When a new image arrives, it is processed by the first Recognizer in chain, then by the second and so on, iterating until a Recognizer object's Result changes its state to Valid or all of the Recognizer objects in chain were invoked (none getting a Valid result state). If you want to invoke all Recognizers in the chain, regardless of whether some Recognizer object's Result in chain has changed its state to Valid or not, you can allow returning of multiple results on a single image.

You cannot change the order of the Recognizer objects within the chain - no matter the order in which you give Recognizer objects to RecognizerBundle , they are internally ordered in a way that provides best possible performance and accuracy. Also, in order for BlinkID SDK to be able to order Recognizer objects in recognition chain in the best way possible, it is not allowed to have multiple instances of Recognizer objects of the same type within the chain. Attempting to do so will crash your application.

Passing `Recognizer` objects between activities

Besides managing the chain of Recognizer objects, RecognizerBundle also manages transferring bundled Recognizer objects between different activities within your app. Although each Recognizer object, and each its Result object implements Parcelable interface, it is not so straightforward to put those objects into Intent and pass them around between your activities and services for two main reasons:

Result object is tied to its Recognizer object, which manages lifetime of the native Result object.
Result object often contains large data blocks, such as images, which cannot be transferred via Intent because of Android's Intent transaction data limit.

Although the first problem can be easily worked around by making a copy of the Result and transfer it independently, the second problem is much tougher to cope with. This is where, RecognizerBundle's methods saveToIntent and loadFromIntent come to help, as they ensure the safe passing of Recognizer objects bundled within RecognizerBundle between activities according to policy defined with method setIntentDataTransferMode :

if set to STANDARD , the Recognizer objects will be passed via Intent using normal Intent transaction mechanism , which is limited by Android's Intent transaction data limit. This is same as manually putting Recognizer objects into Intent and is OK as long as you do not use Recognizer objects that produce images or other large objects in their Results .
if set to OPTIMISED , the Recognizer objects will be passed via internal singleton object and no serialization will take place. This means that there is no limit to the size of data that is being passed. This is also the fastest transfer method, but it has a serious drawback - if Android kills your app to save memory for other apps and then later restarts it and redelivers Intent that should contain Recognizer objects, the internal singleton that should contain saved Recognizer objects will be empty and data that was being sent will be lost. You can easily provoke that condition by choosing No background processes under Limit background processes in your device's Developer options , and then switch from your app to another app and then back to your app.
if set to PERSISTED_OPTIMISED , the Recognizer objects will be passed via internal singleton object (just like in OPTIMISED mode) and will additionaly be serialized into a file in your application's private folder. In case Android restarts your app and internal singleton is empty after re-delivery of the Intent , the data will be loaded from file and nothing will be lost. The files will be automatically cleaned up when data reading takes place. Just like OPTIMISED , this mode does not have limit to the size of data that is being passed and does not have a drawback that OPTIMISED mode has, but some users might be concerned about files to which data is being written.
- These files will contain end-user's private data, such as image of the object that was scanned and the extracted data. Also these files may remain saved in your application's private folder until the next successful reading of data from the file.
- If your app gets restarted multiple times, only after first restart will reading succeed and will delete the file after reading. If multiple restarts take place, you must implement onSaveInstanceState and save bundle back to file by calling its saveState method. Also, after saving state, you should ensure that you clear saved state in your onResume , as onCreate may not be called if activity is not restarted, while onSaveInstanceState may be called as soon as your activity goes to background (before onStop ), even though activity may not be killed at later time.
- If saving data to file in private storage is a concern to you, you should use either OPTIMISED mode to transfer large data and image between activities or create your own mechanism for data transfer. Note that your application's private folder is only accessible by your application and your application alone, unless the end-user's device is rooted.

List of available recognizers

This section will give a list of all Recognizer objects that are available within BlinkID SDK, their purpose and recommendations how they should be used to get best performance and user experience.

Frame Grabber Recognizer

The FrameGrabberRecognizer is the simplest recognizer in BlinkID SDK, as it does not perform any processing on the given image, instead it just returns that image back to its FrameCallback . Its Result never changes state from Empty.

This recognizer is best for easy capturing of camera frames with RecognizerRunnerView . Note that Image sent to onFrameAvailable are temporary and their internal buffers all valid only until the onFrameAvailable method is executing - as soon as method ends, all internal buffers of Image object are disposed. If you need to store Image object for later use, you must create a copy of it by calling clone .

Also note that FrameCallback interface extends Parcelable interface, which means that when implementing FrameCallback interface, you must also implement Parcelable interface.

This is especially important if you plan to transfer FrameGrabberRecognizer between activities - in that case, keep in mind that the instance of your object may not be the same as the instance on which onFrameAvailable method gets called - the instance that receives onFrameAvailable calls is the one that is created within activity that is performing the scan.

Success Frame Grabber Recognizer

The SuccessFrameGrabberRecognizer is a special Recognizer that wraps some other Recognizer and impersonates it while processing the image. However, when the Recognizer being impersonated changes its Result into Valid state, the SuccessFrameGrabberRecognizer captures the image and saves it into its own Result object.

Since SuccessFrameGrabberRecognizer impersonates its slave Recognizer object, it is not possible to give both concrete Recognizer object and SuccessFrameGrabberRecognizer that wraps it to same RecognizerBundle - doing so will have the same result as if you have given two instances of same Recognizer type to the RecognizerBundle - it will crash your application.

This recognizer is best for use cases when you need to capture the exact image that was being processed by some other Recognizer object at the time its Result became Valid . When that happens, SuccessFrameGrabber's Result will also become Valid and will contain described image. That image can then be retrieved with getSuccessFrame() method.

BlinkID recognizers

Unless stated otherwise for concrete recognizer, single side BlinkID recognizers from this list can be used in any context, but they work best with BlinkIdUISettings and DocumentScanUISettings , with UIs best suited for document scanning.

Combined recognizers should be used with BlinkIdUISettings . They manage scanning of multiple document sides in the single camera opening and guide the user through the scanning process. Some combined recognizers support scanning of multiple document types, but only one document type can be scanned at a time.

BlinkID single side recognizer

The BlinkIdSingleSideRecognizer scans and extracts data from the single side of the supported document. You can find the list of the currently supported documents here. We will continue expanding this recognizer by adding support for new document types in the future. Star this repo to stay updated.

The BlinkIdSingleSideRecognizer works best with the BlinkIdUISettings and BlinkIdOverlayController .

BlinkID multi side recognizer

Use BlinkIdMultiSideRecognizer for scanning both sides of the supported document. First, it scans and extracts data from the front, then scans and extracts data from the back, and finally, combines results from both sides. The BlinkIdMultiSideRecognizer also performs data matching and returns a flag if the extracted data captured from the front side matches the data from the back. You can find the list of the currently supported documents here. We will continue expanding this recognizer by adding support for new document types in the future. Star this repo to stay updated.

The BlinkIdMultiSideRecognizer works best with the BlinkIdUISettings and BlinkIdOverlayController .

Machine Readable Travel Document recognizer

The MrtdRecognizer is used for scanning and data extraction from the Machine Readable Zone (MRZ) of the various Machine Readable Travel Documents (MRTDs) like ID cards and passports. This recognizer is not bound to the specific country, but it can be configured to only return data that match some criteria defined by the MrzFilter .