Getting started

First of all: Integrate the Library

The gini vision is provided as a aar archive. You can integrate it in your gradle based project by adding it as dependency. In order to gain access to the aar file, you have to add the Gini Maven repository to your build script.

repositories {
    maven {
        credentials {
            username project.hasProperty('giniRepoUser') ? giniRepoUser : 'invalidUser'
            password project.hasProperty('giniRepoPassword') ? giniRepoPassword : 'invalidPassword'
        }
        url "https://repo.gini.net/nexus/content/repositories/releases"

    }
    ...
}

dependencies {
    compile ('net.gini:ginivision-android-sdk:1.0.231@aar'){
        transitive = true
    }
    ...
}

In the example above we inject the repo credentials via project properties which can be provided in several ways (See the gradle documentation). Please contact Technical Support if you don’t have the credentials for the Gini repo.

v7 Support Library

The default aar archive uses android.app.Activity as the base class for activities. If you use the v7 Support Library and require activities extending android.support.v7.app.AppCompatActivity you can use the compatibility build ginivision-android-sdk-compat.

dependencies {
    compile ('net.gini:ginivision-android-sdk-compat:1.0.231@aar'){
        transitive = true
    }
    ...
}

Required Permissions and Features

The Gini Vision library for Android needs access to the device’s camera. Therefore your application needs to request permission to access the camera, which, in Android, is achieved by adding the following line to your application’s manifest file. See the Android documentation.

<uses-permission android:name="android.permission.CAMERA" />

With Android 6.0 (Marshmallow) comes a new permission handling system. Apps targeting Android SDK 23 or higher need to request each permission listed in the manifest from the user at run time. See Requesting Permissions at Run Time.

The Gini Vision Library does not request the camera permission; we leave it up to you to request it. This way you can show a custom explanation and request the permission where it’s best suited for your app.

The only requirement is, that you must request the camera permission before launching Gini Vision:

public void requestCameraPermission() {
    if (ContextCompat.checkSelfPermission(this,
            Manifest.permission.CAMERA)
            != PackageManager.PERMISSION_GRANTED) {

        if (ActivityCompat.shouldShowRequestPermissionRationale(thisActivity,
                Manifest.permission.CAMERA)) {
            // Show an exlpanation to the user *asynchronously* -- don't block
            // this thread waiting for the user's response! After the user
            // sees the explanation, try again to request the permission.
        } else {
            // No explanation needed, we can request the permission.
            ActivityCompat.requestPermissions(this,
                new String[]{Manifest.permission.CAMERA},
                PERMISSION_REQUEST_CAMERA);

            // PERMISSION_REQUEST_CAMERA is an
            // app-defined int constant. The callback method gets the
            // result of the request.
        }
    } else {
        startGiniVision();
    }
}

@Override
public void onRequestPermissionsResult(int requestCode,
                                       String permissions[], int[] grantResults) {
    switch (requestCode) {
        case PERMISSION_REQUEST_CAMERA:
            if (grantResults.length > 0
                    && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                startGiniVision();
            } else {
                // Request not granted
            }
            break;
    }
}

The Gini Vision library for Android also depends on some hardware features which the device must support. It is best practice to declare these required features in the manifest file as well, as described in the Android documentation.

The following is the full listing of all required features which you should add to your application’s manifest file.

<uses-feature android:name="android.hardware.sensor.accelerometer" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.flash" />
<uses-feature android:name="android.hardware.camera.autofocus" />

Use a Large Heap

Unfortunately, image processing is a memory intensive task. Because of that, you must request a larger heap size by by setting the largeHeap attribute to “true” in the manifest <application> tag. Otherwise it is likely that your application will crash due to an OutOfMemoryException.

Example: A Complete Manifest File

Listed below is the example of a complete manifest file, declaring all required permissions and features.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="net.gini.android.visiontest" >

    <uses-permission android:name="android.permission.CAMERA" />

    <uses-feature android:name="android.hardware.camera" />
    <uses-feature android:name="android.hardware.camera.autofocus" />

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

    <application
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:largeHeap="true">
        <activity
            android:name=".StartActivity"
            android:label="Gini Testing" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

Check whether the device supports all Gini Vision requirements

The Gini Vision library for Android provides a helper method that you can use in your application’s Activity to check whether the device supports all requirements:

import static net.gini.android.vision.Helpers.fitsGiniVisionRequirements;

// Somewhere in your activity

if (!fitsGiniVisionRequirements(this)) {
    // Some action here (e.g. show a message, don't show some button etc.)
}

Warning

fitsGiniVisionRequirements() uses Camera.open() which may take a long time to complete on some devices. You should call this method from a worker thread to avoid blocking the main application UI thread.

Next: Use the Scanner Activity

After you have integrated the Gini Vision library for Android successfully and your application requests all the necessary permissions, you are good to go. Learn next How to Use the Scanner Activity to Scan Documents..