Getting started

First of all: Add the Library to your Build

The gini sdk 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. You also need to add jcenter and the sonatype snapshots repo for Botls 1.5.0.

repositories {
    maven {
        url "https://repo.gini.net/nexus/content/repositories/public"
    }
    // For bolts-android 1.5.0
    //noinspection JcenterRepositoryObsolete
    jcenter()
    // For bolts-tasks and bolts-applinks 1.4.1-SNAPSHOT (which they should have released as version 1.5.0)
    maven {
        url "https://oss.sonatype.org/content/repositories/snapshots/"
    }
    ...
}

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

Integrating the Gini SDK

The Gini SDK provides the Gini class which is a façade to all functionality of the Gini SDK. We recommend using an instance of this class singleton-like. By saying singleton-like we mean that you somehow manage to create and keep one instance at application start. Instead of creating a new instance every time when you need to interact with the Gini API, you reuse this instance. This has the benefits that the SDK can reuse sessions between requests to the Gini API which may save a noteworthy number of HTTP requests.

Creating the Gini SDK instance

In order to create an instance of the Gini class, you need both your client id and your client secret. If you don’t have a client id and client secret yet, you need to register your application with Gini. See the Gini API documentation to find out how to register your Application with Gini.

All requests to the Gini API are made on behalf of a user. This means particularly that all created documents are bound to a specific user account. But since you are most likely only interested in the results of the semantic document analysis and not in a cloud document storage system, the Gini API has the feature of “anonymous users”. This means that user accounts are created on the fly and the user account is unknown to your application’s user.

The following example describes how to use the Gini API in your application with such anonymous user accounts. To use the Gini API, you must create an instance of the Gini class. The Gini instance is configured and created with the help of the SdkBuilder class. In this example, the anonymous users are created with the email domain “example.com”. An example of a username created with this configuration would be 550e8400-e29b-11d4-a716-446655440000@example.com

import net.gini.android.SdkBuilder;
import net.gini.android.DocumentTaskManager;

...

// The Gini instance is a facade to all available managers of the Gini SDK. Configure and
// create the SDK with the SdkBuilder.
Gini gini = new SdkBuilder(getContext(), "gini-client-id", "GiniClientSecret", "example.com")
        .build();
// The DocumentTaskManager provides the high-level API to work with documents.
DocumentTaskManager documentManager = gini.getDocumentTaskManager();

Congratulations, you successfully integrated the Gini SDK.

Using the Gini Accounting API

In version 2.3.0 we added support for the Gini Accounting API. To use it simply set the Gini API type to GiniApiType.ACCOUNTING when using the SdkBuilder:

Gini gini = new SdkBuilder(getContext(), "gini-client-id", "GiniClientSecret", "example.com")
        .setGiniApiType(GiniApiType.ACCOUNTING)
        .build();

Warning

Multi-page documents are not supported with the Gini Accounting API. Use only the DocumentTaskManager#createDocument() methods to upload documents.

Public Key Pinning

Since version 1.5.0 public key pinning is provided using the Android Network Security Configuration and TrustKit. The previous configuration through the SdkBuilder was removed.

Since version 2.10.0 it is also possible to use a custom TrustManager to pin certificates.

To use public key pinning you can either create an Android network security configuration xml file or set a custom TrustManager implementation.

The network security configuration is supported natively on Android Nougat (API Level 24) and newer. For versions between API Level 19 and 23 the Gini SDK relies on TrustKit.

The custom TrustManager is supported on all Android versions.

We recommend reading the Android Network Security Configuration guide and the TrustKit limitations for API Levels 19 to 23.

Configure Pinning

The following sample configuration shows how to set the public key pin for the two domains the Gini SDK uses by default (api.gini.net and user.gini.net). It should be saved under res/xml/network_security_config.xml:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <trustkit-config
            disableDefaultReportUri="true"
            enforcePinning="true" />
        <domain includeSubdomains="false">api.gini.net</domain>
        <pin-set>
            <!-- old *.gini.net public key-->
            <pin digest="SHA-256">yGLLyvZLo2NNXeBNKJwx1PlCtm+YEVU6h2hxVpRa4l4=</pin>
            <!-- new *.gini.net public key, active from around mid September 2018 -->
            <pin digest="SHA-256">cNzbGowA+LNeQ681yMm8ulHxXiGojHE8qAjI+M7bIxU=</pin>
        </pin-set>
        <domain-config>
            <trustkit-config
                disableDefaultReportUri="true"
                enforcePinning="true" />
            <domain includeSubdomains="false">user.gini.net</domain>
        </domain-config>
    </domain-config>
</network-security-config>

Note

If you set different base urls when instantiating the Gini SDK with the SdkBuilder make sure you set matching domains in the network security configuration xml.

Warning

The above digests serve as an example only. You should always create the digest yourself from the Gini API’s public key and use that one (see Extract Hash From gini.net). If you received a digest from us then always validate it by comparing it to the digest you created from the public key (see Extract Hash From Public Key). Failing to validate a digest may lead to security vulnerabilities.

TrustKit

The TrustKit configuration tag <trustkit-config> is required in order to disable TrustKit reporting and to enforce public key pinning. This is important because without it TrustKit won’t throw CertificateExceptions if the local public keys didn’t match any of the remote ones, effectively disabling pinning. The only downside of enforcing pinning is that two public key hashes are required. In the example above we create and used a “zero” key hash as a placeholder. Setting the same key hash twice won’t help since key hashes are stored in a set. Ideally you should use a backup public key hash as the second one.

In your AndroidManifest.xml you need to set the android:networkSecurityConfig attribute on the <application> tag to point to the xml:

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
    ...
    <application android:networkSecurityConfig="@xml/network_security_config">
    ...
</manifest>

Enable Pinning with a Network Security Configuration

For the Gini SDK to know about the xml you need to set the xml resource id using the SdkBuilder#setNetworkSecurityConfigResId() method:

Gini gini = new SdkBuilder(getContext(), "gini-client-id", "GiniClientSecret", "example.com")
        .setNetworkSecurityConfigResId(R.xml.network_security_config)
        .build();

Enable Pinning with a custom TrustManager implementation

You can also take full control over which certificates to trust by passing your own TrustManager implementation to the SdkBuilder#setTrustManager() method:

Gini gini = new SdkBuilder(getContext(), "gini-client-id", "GiniClientSecret", "example.com")
        .setTrustManager(yourTrustManager)
        .build();

Warning

Setting a custom TrustManager will override the network security configuration.

Extract Hash From gini.net

The current Gini API public key SHA256 hash digest in Base64 encoding can be extracted with the following openssl commands:

$ openssl s_client -servername gini.net -connect gini.net:443 | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

Extract Hash From Public Key

You can also extract the hash from a public key. The following example shows how to extract it from a public key named gini.pub:

$ cat gini.pub | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64