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

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

What you need to do:

  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 it to the app/src/main/assets/Regula folder of the project.

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

Online - Using Server

Permissions

Add the INTERNET permission to your AndroidManifest file - it's needed to access the Internet:

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

Using prepareDatabase Method

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

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

Note that "Full" in the code snippet below is the ID of the database to be downloaded. 

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
    }
});

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
    }
})

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.

Using runAutoUpdate Method

As well as the prepareDatabase method, this option is perfect if your app uses the Internet and you want to decrease the app package size.

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.

Note that "Full" in the code snippet below is the ID of the database to be downloaded. 

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
    }
});

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
    }
})

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.

Check Database Update

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

The method accepts:

  • the context parameter
  • databaseId - the database to be checked
  • the ICheckDatabaseUpdate callback with the result

ICheckDatabaseUpdate returns DocReaderDocumentsDatabase which contains information about the database.

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

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

Cancel Database Update

To cancel the database update, invoke:

DocumentReader.Instance().cancelDBUpdate();

DocumentReader.Instance().cancelDBUpdate()

Remove Database

To remove the added database from the application, invoke:

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

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

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. Please reach out to us via Support Portal and let us know which documents of which countries 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