Octus SDK uses advanced deep learning technologies for accurate and fast ID scanning and OCR. Businesses can integrate the Octus SDK into native Android Apps which comes with pre-built screens and configurations. The SDK returns the scanned images, extracted data and error codes. And as a safety measure, the SDK does not store any of the personal data or ID images that are scanned.
For the list of supported documents per country , refer to Octus Country Specific Supported Documents
You can find the latest version and release history Here
‼ ATTENTION ‼ → BREAKING CHANGE introduced at Octus SDK v3.8.0. We have introduced a new license format. If you are using versions prior to v3.8.0 and intend to update to v3.8.0 or above please contact [email protected] for an updated license.
- Prerequisite
- Android SDK Requirements
- Download
- Setup
- Quick Start
- Octus Result
- Octus Error Codes
- Octus Parameters
- Help
You will need a valid license to use the Octus SDK, which can be obtained by contacting [email protected] .
Depending on the license - offline or online - you have opted for, the ping functionality to billing servers will be disabled or enabled. For instance, if you have opted for the offline SDK model, then there will be no server ping needed to our billing server to bill you. However, if you have chosen a transaction based pricing, then after each transaction, a ping request will be made to our billing server. This cannot be overrided by the App. A point to note is that if the ping transaction fails for any reason, the whole transaction will be void without any results from the SDK.
Once you have the license , follow the below instructions for a successful integration of Octus SDK onto your Android Application.
This section lists the Octus SDK Libraries that are available for android with their gradle dependencies, latest version, and their size.
| SDK Library | Gradle dependency | Latest version | Size |
|---|---|---|---|
| Octus SDK (Required) | com.frslabs.android.sdk:octus |  |
9.1 MB |
| Core Face Bundled SDK (Required) | com.frslabs.android.sdk:core-face-bundled |  |
6.2 MB |
| Core Text Bundled SDK (Required) | com.frslabs.android.sdk:core-text-bundled |  |
4.0 MB |
Octus uses Face detection capabilities via either of these two dependencies, and it is required to include any one of them. Core Face Bundled SDK and Core Face Unbundled SDK. If size is not an issue, we recommend going with the Core Face Bundled SDK. More details about these dependencies are found below.
Include this dependency if size of the SDK is not an issue (Adds ~6.2 MB to the app size). This is the recommended approach.
Include this dependency if increase in SDK size is a concern (Adds ~600 KB to the app size). However, upon first run (and only on first run), the face dependencies are downloaded while users are shown a screen with a progress bar. The Core Face Bundled SDK does not have this behaviour as all associated files are bundled during compile time itself (hence the increase in size).
Octus also uses text detection capabilities via either of these two dependencies, and it is required to include any one of them. Core Text Bundled SDK and Core Text Unbundled SDK. If size is not an issue, we recommend going with the Core Text Bundled SDK. More details about these dependencies are found below.
Include this dependency if size of the SDK is not an issue (Adds ~4.0 MB to the app size). This is the recommended approach.
Include this dependency if increase in SDK size is a concern (Adds ~250 KB to the app size). However, upon first run (and only on first run), the face dependencies are downloaded while users are shown a screen with a progress bar. The Core Text Bundled SDK does not have this behaviour as all associated files are bundled during compile time itself (hence the increase in size).
Minimum SDK Version - 19 (Kitkat) or higher
Existing users using version 2.x.x can continue to use the SDKs until November 2020 if no changes are made to the App. And any new applications you are developing or if you are updating your existing application, then you must use SDK version 3.x.x which is AndroidX compatible. From 01 August 2020 all new applications integrating our SDK must use 3.x.x version. Support for version 2.x.x will cease from 01 November 2020. Please write to us as [email protected] if you need more information on AndroidX release.
Add the following code to your project level build.gradle file
allprojects {
repositories {
google()
jcenter()
// Repo for one of the dependencies
maven { url "https://jitpack.io" }
//Maven credentials for the Octus SDK
// Use `torus-android` if transaction based billing enabled
['torus-android','octus-android','common-core-android'].each { value ->
maven {
url "https://www.repo2.frslabs.space/repository/${value}/"
credentials {
username '<YOUR_USERNAME>'
password '<YOUR_PASSOWRD>'
}
}
}
}
}After that, add the following code to your app level build.gradle file
// ...
defaultConfig {
// ...
ndk {
abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
}
vectorDrawables.useSupportLibrary true
renderscriptTargetApi 21
renderscriptSupportModeEnabled false
}
// ...And then, Find the latest version of Octus SDK Here and add the dependencies
// ...
dependencies {
/* Dependencies for Octus SDK Using Androidx */
implementation 'com.google.android.material:<lastest version>'
implementation 'androidx.appcompat:appcompat:<latest version>'
implementation 'androidx.constraintlayout:constraintlayout:<latest version>'
// ...
/* Core Octus SDK Dependencies */
implementation 'com.frslabs.android.sdk:octus:3.X.X' // Required . Find latest version at https://github.com/frslabs/octus-android/blob/master/CHANGELOG.md
implementation 'com.github.Tgo1014:JP2ForAndroid:1.0.4' // Required
implementation 'com.rmtheis:tess-two:9.1.0' // Required
//implementation 'com.google.mlkit:barcode-scanning:17.2.0' // Optional - Needed if document type is QR code
implementation 'com.google.mlkit:text-recognition:16.0.0' // Required
implementation "org.tensorflow:tensorflow-lite:2.16.1"
implementation "org.tensorflow:tensorflow-lite-support:0.4.4"
// REQUIRED : Use ANY ONE of the below core-face modules, i.e either core-face-bundled OR core-face-unbundled
// Recommended over core-face-unbundled
implementation 'com.frslabs.android.sdk:core-face-bundled:1.0.1'
// Uncomment the below line and remove core-face-bundled mentioned above to use core-face-unbundled dependency.
//implementation 'com.frslabs.android.sdk:core-face-unbundled:1.0.1'
// Recommended over core-text-unbundled
implementation 'com.frslabs.android.sdk:core-text-bundled:1.0.0'
// Uncomment the below line and remove core-text-bundled mentioned above to use core-text-unbundled dependency.
//implementation 'com.frslabs.android.sdk:core-text-unbundled:1.0.0'
implementation 'com.frslabs.android.sdk:torus:1.2.1' // Optional - Needed if transaction based billing is enabled
implementation 'com.google.code.gson:gson:2.8.6' // Optional - Needed if transaction based billing is enabled
// ...
}Octus requires the camera permission to initiate its scanner
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="your.package.name" >
<!-- Required by Octus -->
<uses-permission android:name="android.permission.CAMERA" />
<!-- Optional - Required if transaction based billing is enabled -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<application>
...
</application>
</manifest>Initialize the Octus instance with the appropriate configurations to invoke the Octus Sdk
public class MainActivity extends AppCompatActivity implements OctusResultCallback {
// ...
/* Enter the Octus license key here */
private String OCTUS_LICENSE_KEY = "<ENTER_YOUR_LICENSE_KEY_HERE>";
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
Button callSdk = findViewById(R.id.call_sdk);
callSdk.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
/* Invoke the Octus Sdk */
callOctusSdk();
}
});
}
private void callOctusSdk() {
try {
//Initialize the Octus Sdk Config object with the appropriate configurations
OctusConfig octusConfig = new OctusConfig.Builder()
.setLicenseKey(OCTUS_LICENSE_KEY)
.showInstruction(false)
.setScanMode(Utility.ScanMode.AUTO)
.dataPointsAll(false)
.orientationFlat(false)
.setScanAlertType(Utility.Alert.VIBRATION)
.setLanguage(Utility.Language.EN)
.setDocumentCountry(Country.IN)
.setDocumentType(Document.VID)
.setDocumentSubType(Utility.SubType.OCR)
.setDocumentSide(Utility.Side.FRONT_BACK)
.aadhaarNumberMasked(false)
.removeWatermark() // Optional and only for Document.CQL
.build();
//Call the Octus Sdk to start scanning
Octus.setSdkConfig(octusConfig)
.enableLogs()
.initialise(this, this); //Pass the main context here
}catch (OctusInitException e){
//Handle exception here
Toast.makeText(this, e.getMessage(), Toast.LENGTH_SHORT).show();
e.printStackTrace();
}
}
// ...
}For all parameters and their possible values, refer Octus Parameters
Your activity must implement OctusResultCallback to receive the result.
// ...
@Override
public void onScanSuccess(OctusResult octusResult) {
/* Handle the Octus Sdk result here */
Log.d("OctusSdk Result :", octusResult.toString());
}
@Override
public void onScanFailure(String errorCode) {
/* Handle the Octus Sdk failure result here */
Toast.makeText(this, "Error: " + errorCode, Toast.LENGTH_SHORT).show();
}
// ...For all errorCode's and their meanings refer Octus Error Codes
Result of the scan is obtained from the OctusResult instance . Complete Octus result is given below,
// ...
@Override
public void onScanSuccess(OctusResult octusResult) {
/* Handle the Octus Sdk result here */
Log.d("OctusSdk Result :", octusResult.toString());
/* Below values are given for ID card with MRTD & without MRTD */
String code = octusResult.getCode();
String documentType = octusResult.getDocumentType();
String documentCountry = octusResult.getDocumentCountry();
String documentSubType = octusResult.getDocumentSubType();
String documentSide = octusResult.getDocumentSide();
String dataPointAll = octusResult.getDataPointAll();
String name1 = octusResult.getName1();
String name2 = octusResult.getName2();
String idNumber1 = octusResult.getDocumentNumber1();
String idNumber2 = octusResult.getDocumentNumber2();
String dob = octusResult.getDateOfBirth();
String expiry = octusResult.getExpiryDate();
String gender = octusResult.getGender();
String address1 = octusResult.getAddress1();
String address2 = octusResult.getAddress2();
String address3 = octusResult.getAddress3();
String address4 = octusResult.getAddress4();
String city = octusResult.getCity();
String state = octusResult.getState();
String idCountry = octusResult.getCountry();
String idIssCountry = octusResult.getIssuingCountry();
/* Below values gives the Document Image path */
String idFacePath = octusResult.getFace();
String idFrontPhotoPath = octusResult.getPhoto1();
String idBackPhotopath = octusResult.getPhoto2();
/* Below values are applicable to Cheque Leaf (India) only */
String bankAccountNumber = octusResult.getBankAccountNumber();
String bankAccIfsc = octusResult.getBankIfsCode();
String gstn = octusResult.getGSTN();
/* Below values are applicable to Voter ID (India) only */
String frontConfidenceScore = octusResult.getConfidenceIndexF();
String backConfidenceScore = octusResult.getConfidenceIndexB();
String frontIdOcrStatus = octusResult.getFrontIdScanStatus();
String backIdOcrStatus = octusResult.getConfidenceIndexB();
/* Below values are applicable to Aadhaar Card (India) only */
String aadhaarMaskStatus = octusResult.getAadhaarMaskStatus();
/* Below values are applicable to MRTD supported documents only */
String isMRZChecksumValidated = octusResult.getMrzChecksumValidityStatus();
}
// ...Given below are some public methods of OctusResult in brief
| Public Methods | ||
|---|---|---|
| String | getAadhaarMaskStatus() |
Gets the Aadhaar number masking status. Possible values are, |
Error codes and their meaning are tabulated below
| Code | Message |
|---|---|
| 801 | Scan timed out |
| 802 | Invalid ID parameters passed |
| 803 | Camera permission denied |
| 804 | Scan interrupted |
| 805 | License expired |
| 806 | License invalid |
| 807 | Invalid camera resolution |
| 811 | QR not detected |
| 812 | QR parsing failed |
| 814 | Camera Error |
| 108 | Internet unavailable |
| 401 | API limit exceeded |
| 429 | Too many requests |
| 501, 502 | Proteus Edge IO error |
| 503 | GMS dependency error |
| 504 | Face module dependency error |
-
setLicenseKey(String octusLicenseKey)(Required)Accepts the Octus licence key as a
String -
setScanMode(Utility.ScanMode scanMode)(Required)Sets the scanning mode
Value Effect Utility.ScanMode.AUTO Automatically starts scanning as soon as camera preview is ready Utility.ScanMode.MANUAL Displays a button used to start the scan when clicked -
setDocumentType(Document documentType)(Required)Sets the Document which has to be scanned. Possible values are,
Value Effect Document.PAN Pan Card Document.ADR Aadhaar Card Document.VID Voter ID Document.NID National ID Document.PPT Passport Document.VSA Visa Document.DRV Driving Licence Document.CQL Cheque Leaf Document.SSN Social Security Number Document.FRM16 Form 16 Document.GST GST Form Document.IMG_ADR Image Capture Aadhaar Document.IMG_ANY Plain Image capture -
setDocumentCountry(Country country)(Required)Sets the country associated with the Document.
For the complete list of supported countries refer Country Parameters
-
setDocumentSubType(Utility.SubType subType)(Required)Sets the Document Sub Type . Majority of the documents support only
Utility.SubType.OCRas a sub type.Documents where both
Utility.SubType.OCRandUtility.SubType.QR_CODEapply are ,Document.ADRDocument.DRV
Documents where both
Utility.SubType.MRZandUtility.SubType.OCRapply are ,Document.NID
Documents where only
Utility.SubType.MRZapply are ,Document.PPTDocument.VSA
Documents where only
Utility.SubType.PDF417apply are ,Document.DRVForCountry.NGDocument.VIDForCountry.NG
Possible values for Sub Type are,
Value Effect Utility.SubType.OCR Scans the document in OCR mode Utility.SubType.QR_CODE Scans the document in QR mode Utility.SubType.MRZ Scans the document in MRZ mode Utility.SubType.PDF417 Scans the document in PDF417 mode -
setLanguage(Utility.Language language)(Optional) (Defaults to Utility.Language.EN)Sets the language associated with the Document. Possible values are,
Value Effect Utility.Language.EN English Utility.Language.FR French Utility.Language.ES Spanish Utility.Language.AR Arabic Utility.Language.HI Hindi -
showInstruction(boolean show)(Optional) (Defaults to false)Sets flag to enable/disable the instruction screen prior to scanning. Possible values are,
Value Effect true Enables the instruction screen false Disables the instruction screen -
setScanAlertType(Utility.Alert alertType)(Optional) (Defaults to Utility.Alert.SOUND_VIBRATION)Sets the alert type when the sdk returns the result
Value Effect Utility.Alert.SOUND Triggers a beep sound after the scan completes Utility.Alert.VIBRATION Triggers a mild haptic response (Vibration alerting) after scan completes Utility.Alert.NONE Disables any feedback on scan being completed Utility.Alert.SOUND_VIBRATION Triggers both beep sound and haptic response after scan completes -
setDocumentSide(Utility.Side documentSide)(Optional) (Defaults to Utility.Side.FRONT_BACK)Sets the value of the document side to be scanned
Value Effect Utility.Side.FRONT Scans only the Front (Primary) side of the document Utility.Side.BACK Scans only the Back (Secondary) side of the document Utility.Side.FRONT_BACK Scans both Front and back side of the document -
dataPointsAll(boolean dataPointCategory)(Optional) (Defaults to false)Sets the flag to set the data point category
Value Effect true Provides the scan result only if all data points are found false Provides the scan result if atleast one of the data points are found -
orientationFlat(boolean isOrientationFlat)(Optional) (Defaults to false)Sets the value for which the scanner should lock the orientation with respect to the scan surface . Possible values are,
Value Effect true Scans only when orientation of the phone(camera) is perpendicular(flat) to the scan surface. false Scans ignoring the orientation of the phone(camera) to the scan surface. -
aadhaarNumberMasked(boolean numberMasked)(Optional) (Defaults to false) (Applies ONLY to Document.ADR and COUNTRY.IN)Sets the flag to enable/disable aadhaar number masking
Value Effect true Masks the aadhaar number in the scan result(image) false disables masking the aadhaar number in the scan result -
removeWatermark()(Optional) (Applies ONLY to Document.CQL)Sets flag to remove the watermark over the cheque leaf output image. If method is not called, default behavior is to include the watermark.
-
setScanTimeLimit(timeInSec)(Optional)Sets the document scan time limit (in sec).
Type Default value Range Document.CQL 25 12 - 30 Other documents 20 8 - 30 -
skipDocumentAlternateCaptureMode(boolean skipMode)(Optional) (Defaults to false) (Applies ONLY to Document.E_MANDATE_CAT1)Sets the flag to enable/disable alternate capture mode. At the moment, only applicable for Document.E_MANDATE_CAT1
Value Effect true Disables the alternate capture mode false Enables the alternate capture mode
For any queries/feedback , contact us at [email protected]