Get started Pixelnetica™ Document Scanning SDK for Android

Two things happen before any document is scanned: the SDK is initialized with your license key, and — if your application recognizes text — the OCR language files are put where the SDK can find them. This page covers both. The demo application shows a complete working setup.

Initialization

The SDK should be initialized only once. There’s no need to pass the Application object to every SDK call — ScanningSdkLibrary keeps it. Overriding Application.onCreate() is recommended.

class DemoApp : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize Image SDK
        // Assume the license key is stored in assets
        ScanningSdkLibrary.load(this)
    }
}

Supply the License Key

load() accepts the key three ways. Pick one; whichever you choose, an absent or wrong key never crashes the SDK — see what happens without a valid key below.

Option 1 — a key file in your assets. The simplest route, and the one the demo application ships with. The SDK has a fixed lookup location — assets/pixelnetica/scanning/ — so place your key file there:

src/main/
  assets/
    pixelnetica/
      scanning/
        license.key

and initialize with the one-argument call from the sample above: ScanningSdkLibrary.load(this). The SDK tries these file names in order and uses the first one that exists: <applicationId>.key, <applicationId>, licence.key, license.key, licence, license, key. The call returns true when a non-empty key was read from the assets (a missing — or empty — file returns false); it does not tell you whether the key is valid — ScanningSdkLibrary.isLicenceValid() checks that.

Option 2 — a key string from your own source. Use this when the key does not live in assets — it arrives from your backend, sits in encrypted storage, or is injected as a build-time constant kept out of version control:

ScanningSdkLibrary.load(this, licenseKey)

Option 3 — a string resource. Keep the key in your string resources and pass the resource id:

ScanningSdkLibrary.load(this, R.string.scanning_license)

For most applications, option 1 is the right default: it matches how license keys are delivered, needs no code beyond the one-argument load(), and the demo application shows it working end to end. Option 2 exists for keys managed outside the build — including on your own server, which simplifies license updates (the application does not need an update) at the cost of making scanning depend on internet and server availability.

What happens without a valid key

The SDK does not crash when the key is missing or wrong — it starts in the unlicensed state and works normally, except that processed images carry a watermark. A malformed or empty key is rejected cleanly as invalid and produces the same unlicensed state, and so does a valid key bound to a different application ID — the demo application’s key, for example, licenses only the demo application. See the demo license key for how to obtain a free trial key bound to your own application ID.

Check the SDK Version at Runtime

ScanningSdkLibrary.versionInfo (from Java, ScanningSdkLibrary.getVersionInfo()) reports the exact SDK build your application embeds: the release version (name), the build number (build), and the source revision it was built from (gitHash). Use it on About screens, in logs, and in support requests, where knowing the exact build saves a round trip.

val version = ScanningSdkLibrary.versionInfo
Log.i("MyApp", "Scanning SDK $version")   // prints e.g. "3.2.0 (1234) [a1b2c3d]"

Setup OCR Languages

DSSDK supports more than 100 languages for text recognition and extraction. To enable this functionality, you must set up the appropriate language files in your application.

Getting Language Files

Language files are available in a single archive from our server.

Download Language Archive, unzip it, and make its contents accessible to your application. Language files can either be placed on a remote server or bundled with your application as described below.

Setting Up Languages in Your Application

There are two approaches to configure and use language files for text recognition (OCR):

1. Using the Pixelnetica UI Control to Manage Language Files
   This setup process is detailed in the relevant documentation. This method is employed in the DSSDK demo application (EasyScan), allowing users to download any available language from the server. It is a practical solution for applications requiring support for multiple languages and regions.

   However, if your application requires a restricted, predefined set of languages or a fully customized UI, you should consider the manual approach described below.

2. Managing Language Files Manually

   • Create a directory accessible by your application. This directory will be referred to as languagesDir.
   • Use the function ScanningSdkLibrary.unpackLanguageFile(languageFile, languagesDir) to unpack the desired language files into the languagesDir. Store the names of the unpacked files in a list, referred to as languageNames.
     • The languageFile can either be downloaded from a remote server or bundled with your application.
   • Unpack the file osd.pxl to enable the document orientation detector. This file is what ScanDetector uses to detect and correct a document’s orientation, which improves recognition accuracy and text readability. We recommend bundling osd.pxl with your application, so orientation detection works from the very first launch. It is also the largest single language file (about 11 MB — see application size), so if a minimal download matters more to you, take the demo application’s approach as the trade-off between size and user convenience: mark the file for automatic installation on your language server, and the language manager downloads it on first run — a smaller app, at the price of a first session that may start without orientation detection.