Skip to content

Database

How to add, update, and remove the database.

Overview

A database is a db.dat file that contains the documents' data. It's mandatory to have the db.dat file if the document type and Visual zone data should be recognized. If MRZ, Barcode recognition, or image cropping is performed, there is no need to have the database inside the application.

Add Database

There are several options how to get the database to the application.

graph TD
  X(( )) --> A{Internet?};
  A -->|No| B(Manually);
  B --> Y(( ));
  A -->|Yes| C{Get always<br>the latest<br>updates?};
  C -->|No| D[[prepareDatabase]];
  C -->|Yes| E[[runAutoUpdate]];
  D --> Y(( ));
  E --> Y(( ));

Warning

If you have the database in the app and want to add a new version, do not forget to increase the app's version first.

Manually (Offline)

This option is perfect for those apps that need to work offline.

Do the following:

1. Go to the Client Portal.

2. Sign up if you are not registered yet.

3. Go to the Databases page and download the database provided there.

4. Add the database file to your application:

Add the downloaded database file to the desired project's target.

Add the downloaded database file to the app/src/main/assets/Regula folder of the project.

See the iOS and Android Native descriptions.

Copy the database to the resources folder. Then insert the lines below to the config.xml file:

<platform name="android">
    <resource-file src="resources/db.dat" target="app/src/main/assets/Regula/db.dat"/>
</platform>
<platform name="ios">
    <resource-file src="resources/db.dat" />
</platform>

Copy the database to the www folder. Then insert the lines below to the config.xml file:

<platform name="android">
    <resource-file src="www/db.dat" target="app/src/main/assets/Regula/db.dat"/>
</platform>
<platform name="ios">
    <resource-file src="www/db.dat" />
</platform>

Once you build and run the project, the database will be located inside the application and processed by the SDK.

Alternatively, instead of including the database file directly in the app bundle, you can place the database file anywhere in the local file system and set its path to the configuration object:

let config = DocReader.Config(license: your_license_data)
config.databasePath = Bundle.main.path(forResource: "db.dat", ofType: nil)

RGLConfig *config = [RGLConfig initWithLicenseData:your_license_data];
config.databasePath = [[NSBundle mainBundle] pathForResource:@"db.dat" ofType:nil];

val licInput = resources.openRawResource(R.raw.regula)
val available = licInput.available()
val license = ByteArray(available)
licInput.read(license)

//Place db.dat in the path below
val customDbPath = "/storage/emulated/0/Android/data/com.regula.documentreader/folder/"
val config = DocReaderConfig(license, customDbPath)

InputStream licInput = getResources().openRawResource(R.raw.regula);
int available = licInput.available();
byte[] license = new byte[available];
licInput.read(license);

//Place db.dat in the path below
String customDbPath = "/storage/emulated/0/Android/data/com.regula.documentreader/folder/";
DocReaderConfig config = new DocReaderConfig(license, customDbPath);

var config = InitConfig(license);

// iOS
config.databasePath = "db.dat";

// Android
//Place db.dat in the path below
var customDbPath = "/storage/emulated/0/Android/data/com.regula.documentreader/folder/";
config.databasePath = customDbPath;

var config = new DocReaderConfig();
config.license = license

// iOS
config.databasePath = "db.dat";

// Android
//Place db.dat in the path below
var customDbPath = "/storage/emulated/0/Android/data/com.regula.documentreader/folder/";
config.databasePath = customDbPath;

var config = new DocReaderConfig();
config.license = license

// iOS
config.databasePath = "db.dat";

// Android
//Place db.dat in the path below
var customDbPath = "/storage/emulated/0/Android/data/com.regula.documentreader/folder/";
config.databasePath = customDbPath;

var config = new DocReaderConfig();
config.license = license

// iOS
config.databasePath = "db.dat";

// Android
//Place db.dat in the path below
var customDbPath = "/storage/emulated/0/Android/data/com.regula.documentreader/folder/";
config.databasePath = customDbPath;

// iOS
var config = new RGLConfig(your_license_data);
config.DatabasePath = NSBundle.MainBundle.PathForResource("db.dat", null);

// Android
//Place db.dat in the path below
var customDbPath = "/storage/emulated/0/Android/data/com.regula.documentreader/folder/";
var config = new DocReaderConfig(license, customDbPath);

Automatically (Online)

Choose this option if your app uses the Internet and you want to decrease the app's package size. Once the operation is completed successfully, the database is added to the resources of the application.

Make sure to have a stable Internet connection as the database is downloaded from our server over the Internet.

Permissions

Android

Add the INTERNET permission to your AndroidManifest file, this is needed to access the Internet:

AndroidManifest.xml
<uses-permission android:name="android.permission.INTERNET" />

Using prepareDatabase Method

The prepareDatabase method downloads a new version of the database only if the current one is incompatible with the SDK.

If the existing database isn't compatible with the SDK or there is no database in the app at all, the new version of the database is downloaded.

If the database was removed from the app, it is downloaded again as soon as this function is invoked.

In the code snippet below, Full is the ID of the database to be downloaded:

DocReader.shared.prepareDatabase(databaseID: "Full", progressHandler: { (progress) in
    print(progressValue) // progress block
}, completion: { (success, error) in
    if success {
        print(success) // Success state
    } else {
        print(error) // Error status
    }
})

[RGLDocReader.shared prepareDatabase:@"Full" progressHandler:^(NSProgress * _Nonnull progress) {
    // progress block
} completion:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        NSLog(success ? @"YES" : @"NO"); // Success state
    } else {
        NSLog(@"%@", error); // Error status
    }
}];

DocumentReader.Instance().prepareDatabase(this@MainActivity, "Full", object : IDocumentReaderPrepareCompletion {
    override fun onPrepareProgressChanged(progress: Int) {
        // getting progress
    }

    override fun onPrepareCompleted(status: Boolean, error: Throwable?) {
        // database was prepared
    }
})

DocumentReader.Instance().prepareDatabase(MainActivity.this, "Full", new IDocumentReaderPrepareCompletion() {
    @Override
    public void onPrepareProgressChanged(int progress) {
        // getting progress
    }

    @Override
    public void onPrepareCompleted(boolean status, Throwable error) {
        // database was prepared
    }
});

var (success, error) = await DocumentReader.instance.prepareDatabase("Full", print);

DocumentReader.prepareDatabase("Full", (respond) => {
  console.log(respond);
},
(error) => {
  console.log(error);
});

DocumentReader.prepareDatabase("Full").subscribe(response => {
    console.log(response);
});

DocumentReader.prepareDatabase("Full", function (message) {
    console.log(message);
}, function (error) {
    console.log(error);
});

// Android
public class MainActivity : DocumentReader.IDocumentReaderCompletion
{
    protected override void OnCreate(Bundle bundle)
    {
        DocumentReader.Instance().PrepareDatabase(this, "Full", this);
    }

    public void OnPrepareCompleted(bool status, String error1)
    {
        // database downloaded
    }

    public void OnPrepareProgressChanged(int progress)
    {
        // get progress update
    }
}

// iOS
RGLDocReader.Shared.PrepareDatabase("Full", (NSProgress progress) => {
    // get progress
}, (success, error) => {
    // handle completion
});

Using runAutoUpdate Method

The difference is that the runAutoUpdate method downloads the newest version of the database that it finds on our server even if your current database is still compatible with the SDK. If there are no updates to the database, nothing is downloaded.

If the operation is completed successfully, the database is added to the resources of the application.

If the existing database isn't compatible with the SDK or there is no database in the app at all, the freshest version of the database is downloaded.

In the code snippet below, Full is the ID of the database to be downloaded:

DocReader.shared.runAutoUpdate(databaseID: "Full", progressHandler: { (progress) in
    print(progressValue) // progress block
}, completion: { (success, error) in
    if success {
        print(success) // Success state
    } else {
        print(error) // Error status
    }
})

[RGLDocReader.shared runAutoUpdate:@"Full" progressHandler:^(NSProgress * _Nonnull progress) {
    // progress block
} completion:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        NSLog(success ? @"YES" : @"NO"); // Success state
    } else {
        NSLog(@"%@", error); // Error status
    }
}];

DocumentReader.Instance().runAutoUpdate(this@MainActivity, "Full", object : IDocumentReaderPrepareCompletion {
    override fun onPrepareProgressChanged(progress: Int) {
        // getting progress
    }

    override fun onPrepareCompleted(status: Boolean, error: Throwable?) {
        // database was prepared
    }
})

DocumentReader.Instance().runAutoUpdate(MainActivity.this, "Full", new IDocumentReaderPrepareCompletion() {
    @Override
    public void onPrepareProgressChanged(int progress) {
        // getting progress
    }

    @Override
    public void onPrepareCompleted(boolean status, Throwable error) {
        // database was prepared
    }
});

var (success, error) = await DocumentReader.instance.runAutoUpdate("Full", print);

DocumentReader.runAutoUpdate("Full", (respond) => {
  console.log(respond);
},
(error) => {
  console.log(error);
});

DocumentReader.runAutoUpdate("Full").subscribe(response => {
    console.log(response);
});

DocumentReader.runAutoUpdate("Full", function (message) {
    console.log(message);
}, function (error) {
    console.log(error);
});

// Android
public class MainActivity : DocumentReader.IDocumentReaderCompletion
{
    protected override void OnCreate(Bundle bundle)
    {
        DocumentReader.Instance().RunAutoUpdate(this, "Full", this);
    }

    public void OnPrepareCompleted(bool status, String error1)
    {
        // database downloaded
    }

    public void OnPrepareProgressChanged(int progress)
    {
        // get progress update
    }
}

// iOS
RGLDocReader.Shared.RunAutoUpdate("Full", (NSProgress progress) => {
    // get progress
}, (success, error) => {
    // handle completion
});

Check Database Update

Use the checkDatabaseUpdate method to check if the database update is available. Note that the internet permission is required (Android):

DocReader.shared.checkDatabaseUpdate(databaseID: "Full") { database in
    print(database?.date ?? "no update")
}

[RGLDocReader.shared checkDatabaseUpdate:@"Full" completion:^(RGLDocReaderDocumentsDatabase * _Nullable database) {
    NSLog(@"%@", database.date);
}];

DocumentReader.Instance().checkDatabaseUpdate(this@MainActivity, "Full") { it?.let {
    Log.d("DatabaseUpdate", "Date: " + it.date)
}  }

DocumentReader.Instance().checkDatabaseUpdate(MainActivity.this, "Full", new ICheckDatabaseUpdate() {
    @Override
    public void onCompleted(@Nullable DocReaderDocumentsDatabase docReaderDocumentsDatabase) {
        Log.d("DatabaseUpdate", "Date: " + it.date)
    }
});

var database = await DocumentReader.instance.checkDatabaseUpdate("Full");
print(database?.date ?? "no update");

DocumentReader.checkDatabaseUpdate("Full", (response) => {
  var database = DocReaderDocumentsDatabase.fromJson(response);
  if (database != null)
    console.log(database.date);
  else
    console.log("db is null");
},
  (error) => {
    console.log(error);
  });

  DocumentReader.checkDatabaseUpdate("Full").then(response => {
    var database = DocReaderDocumentsDatabase.fromJson(response);
    if (database != null)
      console.log(database.date);
    else
      console.log("db is null");
  });

DocumentReader.checkDatabaseUpdate("Full", function (response) => {
  var database = DocReaderDocumentsDatabase.fromJson(response);
  if (database != null)
    console.log(database.date);
  else
    console.log("db is null");
},
  function (error) => {
    console.log(error);
  });

// Android
public class MainActivity : MauiAppCompatActivity, ICheckDatabaseUpdate
{
    protected override void OnCreate(Bundle bundle)
    {
        DocumentReader.Instance().CheckDatabaseUpdate(this, "Full", this);
    }

    public void OnCompleted(DocReaderDocumentsDatabase database)
    {
        if (database != null)
            Console.WriteLine(database.Date);
        else
            Console.WriteLine("db is null");
    }
}

// iOS
RGLDocReader.Shared.CheckDatabaseUpdate("Full", (RGLDocReaderDocumentsDatabase database) =>
{
    if (database != null)
        Console.WriteLine(database.Date);
    else
        Console.WriteLine("db is null");
});

Code snippets in the previous example demonstrate accessing the date property of the database callback object. See other available properties of the same object in the table below.

Property Type Description
databaseID string unique identifier of the database
version string database version
date string database's date of creation
databaseDescription string list of database's supported documents
countriesNumber integer number of countries, included in database
documentsNumber integer number of documents, included in database
size integer database size in bytes

Detailed up-to-date information about the database object properties is available in the reference documentation:

Cancel Database Update

To cancel the database update, invoke:

DocReader.shared.cancelDBUpdate()

[RGLDocReader.shared cancelDBUpdate];

DocumentReader.Instance().cancelDBUpdate()

DocumentReader.Instance().cancelDBUpdate();

DocumentReader.instance.cancelDBUpdate();

DocumentReader.cancelDBUpdate((respond) => {
  console.log(respond);
},
(error) => {
  console.log(error);
});

DocumentReader.cancelDBUpdate().then(response => {
    console.log(response);
});

DocumentReader.cancelDBUpdate(function (message) {
    console.log(message);
}, function (error) {
    console.log(error);
});

// Android
DocumentReader.Instance().CancelDBUpdate();

// iOS
RGLDocReader.Shared.CancelDBUpdate();

Remove Database

To remove the added database from the application, invoke:

DocReader.shared.removeDatabase { (success, error) in
    if success {
        print(success) // Success state
    } else {
        print(error) // Error status
    }
}

[RGLDocReader.shared removeDatabase:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        NSLog(success ? @"YES" : @"NO"); // Success state
    } else {
        NSLog(@"%@", error); // Error status
    }
}];

DocumentReader.Instance().removeDatabase(this@MainActivity)

DocumentReader.Instance().removeDatabase(MainActivity.this);

print(await DocumentReader.instance.removeDatabase());  // Success state

DocumentReader.removeDatabase((respond) => {
  console.log(respond);
},
(error) => {
  console.log(error);
});

DocumentReader.removeDatabase().then(response => {
    console.log(response);
});

DocumentReader.removeDatabase(function (message) {
    console.log(message);
}, function (error) {
    console.log(error);
});

// Android
DocumentReader.Instance().RemoveDatabase(ApplicationContext);

// iOS
RGLDocReader.Shared.RemoveDatabase((bool success, string error) => {
    // Removing database
});

Custom Database

There are two ready-made database solutions for the Document Reader SDK: Full and FullAuth.

The Full database includes all the documents of all the countries listed in the Documents List.

The FullAuth type includes all the documents of all the countries plus all the security checks that are indicated in the "Security Features" column of the Documents List.

If you do not need the full database, you can shrink your application size by excluding some of the excess items.

graph LR
  A(How to shrink<br>the database?) --> B(By countries);
  A --> C(By document types);
  A --> D(By countries &<br>document types);
  A --> E(By types of<br>certain documents);
  A --> F(By document types<br>with RFID chip<br>embedded);
  A --> G(By languages);
  A --> H(By security checks);

On this page, several ways to shrink the database are collected.

By countries

You can exclude unnecessary countries and leave only those you need.

By document types

You can leave only the types of documents you work with, such as passports, driving licenses, IDs, visas, etc.

By countries and document types

You can leave included all the documents from the selected country and add only chosen types of documents of other countries. For example, all the types of documents of Germany plus passports of all the other countries.

By types of certain documents

In some countries, some types of documents may have several subtypes, for example, type of passports by the issuing year. You can include to your database only certain types of certain documents.

By document types with RFID chip embedded

You can leave included only documents that have an RFID chip embedded.

By languages

By default, the SDK can read text in languages that use the Latin alphabet. Besides, the Full database includes three neural networks for other languages. You can exclude all of them or leave one or two.

The neural networks recognize the following groups of languages:

  • Type 1: Chinese, Japanese, Korean.
  • Type 2: Languages of Algeria, Bahrain, Egypt, Iraq, Jordan, Lebanon, Arabic World, Libya, Morocco, Oman, Qatar, Saudi Arabia, Arabic-Syria, Tunisia, U.A.E, Yemen, Persian, Urdu, Pashto, Sindhi.
  • Type 3: Lao, Thai, Sinhala, Bengali-Bangladesh, Bengali-India, Tamil, Hindi, Kashmiri, Konkani, Marathi, Punjabi, Sanskrit, Sindhi, Amharic.

By security checks

The security checks can be excluded or set selectively. There are two groups of security checks available:

  1. For authenticity checks in ultraviolet (spectrum) light, applicable for Regula Mobile document authenticators.
  2. For Visible/IR patterns authenticity checks.

Info

To get a configured custom database, contact your account manager or create a request on the Support Portal.

FAQ

Is there a list of documents included into the database?

Yes, you can download it.

I don't need a database that includes all documents of the world. Is it possible to create a custom database with only certain documents?

Sure, see the Custom Database section for details and then reach out to us via Support Portal and let us know the configuration you need. We will create a custom database especially for you.

What is the difference between the prepareDatabase and runAutoUpdate methods?

The prepareDatabase method downloads a new version of the database only if the current one is incompatible with the SDK.

The runAutoUpdate method downloads the newest database version that it finds on our server even if the current database is still compatible with the SDK.

Which option should I use if my application needs to work offline?

The only option you can use in this case is the Manual one.

When should I invoke a method that adds the database to the app?

Before the initialization process is started.

Which option should I use so the app's package size is not increased?

Choose either the prepareDatabase or runAutoUpdate method.

Next Steps