Android

You have to perform the following steps in sequential order to use OIP Risk Management in the host application.

This quickstart contains:

• Step 1: Adding OIP Risk Management dependencies to project
• Step 2: Adding permissions
• Step 3: Creating configuration objects
• Step 4: Certificate pinning
• Step 5: Initialising OIP Risk Management SDK
• Step 6: Starting prefetch signals
• Step 7: Requesting for prefetch status
• Step 8: Requesting and processing of visitID
• Step 9: Clearing transaction resources
• Step 10: Stopping prefetch signals

Step 1: Adding OIP Risk Management dependencies to project

A set of files are stored in deliverable package folder for you to perform the following steps:

1. Clone the github repository from https://github.com/gemalto/idcloud-fpp-tutorials-android.
2. Create a libs folder in idcloud-fpp-tutorials-android/01-ProjectSetup/app.
3. Copy the debug version of OIP Risk Management from the deliverable package external/debug to the 01-ProjectSetup/app/libs/debug folder.
4. Copy the release version of OIP Risk Management from the deliverable package external/release to the 01-ProjectSetup/app/libs/release folder.
5. Copy all AAR files inside the 3pty and put them into the 01-ProjectSetup/app/libs/3pty folder.
6. Copy the Proguard configuration file proguard-project.txt from external/proguard to 01-ProjectSetup/app.

7. Add the native dependency in the app/build.gradle file.

   ```groovy
   sourceSets {
           debug {
               jniLibs.srcDirs += ['libs/debug']
           }
   
           release {
               jniLibs.srcDirs += ['libs/release']
           }
   }
   ```
   

   1. Add all the library dependencies in the app/build.gradle file. Search for PLACEHOLDER - Jar + Aar Dependency in 01-ProjectSetup App.

   ```groovy dependencies { // Add Risk Management Platform java library releaseImplementation files('libs/release/GAHRiskEngine.jar') debugImplementation files('libs/debug/GAHRiskEngine.jar')

   // 3pty dependencies
   implementation fileTree(include: "*.aar", dir: "libs/3pty")
   
   // Add JNA dependency
   api 'net.java.dev.jna:jna:5.5.0@aar'
   

   } ```

Step 2: Adding permissions

The following permissions are required in the manifest file to enable OIP Risk Management to work properly:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />

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

Refer to OIP Risk Management Permissions for details on the permissions needed for different signals.

Note

Follow the Android specific guidelines for handling risky permissions in and above Android version 6.0 Reference: https://developer.android.com/guide/topics/permissions/overview

Step 3: Creating configuration objects

There are different configuration objects to be configured for OIP Risk Management.

These two configuration objects are mandatory:

• GAHCoreConfig: A mandatory configuration which is used to initialise the core components of OIP Risk Management.
• GAHGemaltoSignalConfig: A mandatory configuration which is used to initialise all parameters related to Thales signals.

The remaining configurations are optional and used for proprietary signal groups.

• GAHBSecConfig: Specific to the proprietary signal group BehavioSec. Use this configuration if you want to enable the BehavioSec group signal collection for the risk calculation.
• GAHTMXConfig: Specific to the proprietary signal group ThreatMetrix. Use this configuration if you want to enable the ThreatMetrix group signal collection for the risk calculation.

The following tables list the configurable parameters from the different configuration classes of OIP Risk Management.

GAHCoreConfig object

Table 1: Configurable Parameters of GAHCoreConfig

GAHGemaltoSignalConfig object

Table 2: Configurable Parameters of GAHGemaltoSignalConfig

Builder design pattern

All the configuration classes follow the builder design pattern. Mandatory parameters have to be passed to the constructor of the builder, optional parameters have to be set through setters. Once all the parameters are set, call build(). Subsequently, the parameters will be taken into account.

Note

Refer to your Thales representative on the following for your organization: * For ThreatMetrix: orgID

Caution

Without a Wi-Fi/Data network, the SDK initialization will not be successful and hence signals such as ThreatMetrix can never be collected until the initialization is done again with the availability of the Internet.

Search for PLACEHOLDER - Configuration in placeholder for configuration in Sample App

// Setup core config, set other optional parameters, if required
GAHCoreConfig coreConfig = new GAHCoreConfig.Builder(getApplicationContext(), riskEngineUrl)
    .build();

//Setup Signal config, set other optional parameters, if required
GAHGemaltoSignalConfig signalConfig = new GAHGemaltoSignalConfig.Builder()
    .build();

Step 4: Certificate Pinning

This is used to check that the Risk Engine backend server’s certificate matches a known copy of that certificate at the application.

To use certificate pinning, the application sends the array of X509Certificate to OIP Risk Management’s GAHCoreConfig and sends the GAHCoreConfig object to initialize().

You can also configure the TLS connection settings. OIP Risk Management will take care of the default configurations if this is not set from the application.

Note

• Ceritificate Pinning is mandatory for Release variant of SDK, it is optional for Debug.

• It is not recommended to override the connection settings or attributes/parameters in a production environment. Allowing Self Signed and Host mismatch configurations will reduce the security of the communication link with the server. Insecure connections are not permitted in the Release mode.

//Add the certificates to GAHCoreConfig and pass to initialize
* Set certificate array to GAH Core config */
final X509Certificate[] certificates = new X509Certificate[2];
certificates[0] = AppUtils.getCertificate(this, R.raw.digital_cloud_cert_parent_der);
certificates[1] = AppUtils.getCertificate(this, R.raw.digital_cloud_cert_child_der);
coreConfigBuilder = coreConfigBuilder.setSecureConnectionCertificates(certificates);

if (BuildConfig.DEBUG)
{
    coreConfigBuilder = coreConfigBuilder.setSecureConnectionPermits(new GAHCoreConfig
            .Permit[]{GAHCoreConfig.Permit.INSECURE_COMMUNICATIONS});
}

The following code snippet shows how to get a certificate in the X509Certificate format. It is assumed that the certificate file is placed in res/raw folder:

public static X509Certificate getCertificate(Context context, int resId)
{
    X509Certificate certificate = null;
    InputStream caInput = null;

    try {
        final CertificateFactory factory = CertificateFactory.getInstance("X.509");
        caInput = new BufferedInputStream(context.getResources().openRawResource(resId));
        certificate = (X509Certificate) factory.generateCertificate(caInput);
        Log.i(TAG, "ca=" + (certificate).getSubjectDN());
    } catch (final CertificateException exception) {
        Log.e(TAG, exception.getMessage());
    }
    finally {
        if (caInput != null) {
            try {
                caInput.close();
            } catch (IOException ex) {
                Log.e(TAG, ex.getMessage());
            }
        }
    }
    return certificate;
}

Step 5: Initialising OIP Risk Management SDK

Initialise the SDK by passing the mandatory configurations GAHCoreConfig, GAHGemaltoSignalConfig and optional configurations GAHTMXConfig, GAHBSecConfig. If GAHTMXConfig, GAHBSecConfig are not set, these signal groups will not be initiated, hence no signal collection under these will be made.

During the initialisation, OIP Risk Management SDK internally performs the initialisation and signal collection of proprietary SDKs such as ThreatMetrix. Once the corresponding initialisation/registration are successful, the proprietary SDK signals are collected and stored in cache until SignalCacheTime (Configurable parameter in GAHGemaltoSignalConfig) so that these signals are readily available during the next events such as Login and Add beneficiary.

Note

• Initialisation and signal collection of proprietary groups are time-consuming. Signal collection completion can be verified using the requestPrefetchStatus API explained in Step 6 of this codelab.
• Initialisation of SDK is a one-time process for an app cycle.
• A RuntimeException is thrown if the mandatory configurations required for GAHCoreConfig and GAHGemaltoSignalConfig are not passed to the initialize() method. If the optional configuration is not sent, the SDK assumes that the features are not needed by the application and subsequent use of the feature will cause exceptions/errors.

Search for PLACEHOLDER - Initialisation in placeholder for initialisation in Sample App.

// Pass configuration to core.
GAHCore.initialize(coreConfig, signalConfig);

Step 6: Starting prefetch signals

Prefetching signals means collecting and storing the signal values in the cache for SignalCacheTime (configurable parameter in GAHGemaltoSignalConfig) so that collection time is reduced during the actual transaction action.

This method can either be called from the UI or from a non-UI thread. Basically, signals which are time-consuming to collect are identified and prefetched.

Note

No API call to OIP Risk Management back-end is made during the execution of prefetching the signals.

Currently, prefetching collects and caches a few of the signals such as:

• Location signals: Sends a request to the operating system to get the latest location coordinates.
• ThreatMetrix signal: Sends a request to TMX SDK for a new sessionID.

It is recommended to call this method during the launch of a screen containing a transaction event such as Login, Add Beneficiary, so that signals are cached at an early stage before the actual transaction is made.

Caution

• If the signal values present in the cache are older than SignalCacheTime, the signals will not be considered as part of the request to IdCloud Risk Management back-end, instead they will be discarded and a request will be made to collect the new values.

• The same signal collection and caching process is done for ThreatMetrix signal groups during OIP Risk Management initialization. But if this needs to be done in some screen later after the initialization, the Prefetch API can be called. Prefetching will first check if a valid signal is already present in the cache before actually collecting the signals.

Search for PLACEHOLDER - Prefetch in placeholder for prefetch in Sample App.

// Start Signal prefetch
GAHCore.startPrefetchSignals();

Step 7. Requesting for prefetch status

Ensure that the signals mentioned in step 5 (Location, ThreatMetrix) are collected and cached before requesting visitID from OIP Risk Management.

This can be ensured by requesting for a status callback using the requestPrefetchStatus() method. Callback will be invoked at the end of SignalPrefetchTime (Configurable in GAHGemaltoSignalConfig class). Error status will be received from the callback if all signals are not collected and cached within SignalPrefetchTime.

Note

It is not recommended for the application to perform any transaction such as login or fund transfer before signal collection is completed and the statusCode is returned as GAHErrorCodes: .PREFETCH_STATUS_OK.

OIP Risk Management has an internal default timeout of 5 seconds (configurable).

• If all signals are collected then the status is set as GAHErrorCodes.PREFETCH_STATUS_OK.
• If any of the signals cannot be collected then the status is GAHErrorCodes.PREFETCH_STATUS_PARTIAL_OK.
• If no signal is collected then status is set as GAHErrorCodes.PREFETCH_STATUS_FAILURE.

Failure and partial_ok status can occur due to various reasons such as:

• Network latency
• Runtime permission is not granted.
• GPS feature is not enabled.

Ensure all integration steps are followed and the device is connected to the internet with feasible speed to avoid the erroneous condition.

Note

This method will wait for SignalPrefetchTime (Configurable in GAHGemaltoSignalConfig) to get any signals before invoking the callback, in case the signals are not ready and present in the cache.

If the signal does not have a value in the cache or if it cannot be collected within SignalPrefetchTime, then a callback error is invoked.

Search for PLACEHOLDER - Prefetch Status in placeholder for prefetch status check in Sample App.

// Listen to prefetch status
GAHCore.requestPrefetchStatus(this.processPrefetchStatusResponse);

Step 8: Requesting and processing of visitID

The application requests OIP Risk Management SDK for the visitID, this visitID can be forwarded by application/bank back-end to OIP Risk Management back-end to receive the “decision” based on the risk calculated from various signals that are collected by OIP Risk Management SDK.

Internally, this method fetches all the requested signal values as configured during initialisation, then sends the signal JSON to the OIP Risk Management back-end and gets the visitID corresponding to the set of signals present in the request JSON.

The signals mentioned in Step 5 will be taken from the cache and all other signals will be collected freshly every time the requestVisitID() call is made.

If the cached signal timestamp is older than SignalCacheTime, the signals cache will be discarded and a request will be made to collect the new values.

As a new request to collect the signal to be cached is time-consuming, it is recommended to call the Prefetch function to ensure that signals are cached before making the call to requestVisitID().

To get the visitID, the application has to call the requestVisitID method. This method internally runs on a separate worker thread.

The GAHResponseCallback interface is used to get the result from OIP Risk Management:

• If OIP Risk Management successfully fetches the visitID, the application gets the callback in “success” method with visitID.
• If OIP Risk Management fails to get the visitID, it returns the error code and error message in the “error” callback method.

The requestVisitID method is called to decide the “next step” of every event such as:

• Login
• Add beneficiary
• Fund transfer

Search for PLACEHOLDER - Request Visit Id in Sample App

// Make sure that we have all signals prefetched.
if (statusCode == GAHErrorCodes.PREFETCH_STATUS_OK) {
  // With all signals in place. Request Visit ID.
  GAHCore.requestVisitID(new GAHResponseCallback() {
    @Override
    public void success(String visitID) {
      processVisitIDResponse(true, visitID);
    }

    @Override
    public void error(int statusCode, String statusMsg) {
      processVisitIDResponse(false, statusMsg);
    }
  });
}

Step 9: Clearing transaction resources

This method is called after every transaction to clear the transaction resources used in OIP Risk Management.

A transaction may be an action in the application such as Login, Add beneficiary and Fund transfer.

Note

If the BehavioSec signal group is initialised, this method must be called from a UI thread as this will clear some of the information pertaining to UI elements.

Search for PLACEHOLDER - Clear Transaction Resources in placeholder for clearing transaction resources in Sample App.

// Clear transaction resources
GAHCore.clearTransactionResources();

Step 10: Stopping prefetch signals

Stopping the prefetching of signals results in the termination of background process of storing values in the cache.

This method can either be called from the UI (main) or a non-UI (background) thread.

Note

It is recommended to call this method during a transaction screen exit where startPrefetchSignals() is called previously.

Search for PLACEHOLDER - Stop Prefetch in placeholder for stopping prefetch in Sample App.

//Stop signal Prefetch
GAHCore.stopPrefetchSignals();

Next

Evaluating risk