Android Native

This SDK has the capabilities related to device intelligence and behavioural biometrics

Overview

By intricately profiling keystroke activity, touch gestures, sensor engagement, autofill behavior, and copy-paste patterns, Behavioural Biometrics goes beyond traditional methods, providing a multifaceted analysis that adapts to the unique behaviors of individual users.

Our technology enables continuous authentication, ensuring that the user in control is the genuine account holder.

Key Features:

Keystroke Dynamics:

Understand users through their typing patterns, creating a secure and personalized typing profile.

Touch Gesture Analysis:

Utilize touch gestures as a behavioral fingerprint, adding an extra layer of security to your applications.

Sensor Intelligence:

Leverage device sensors to enhance behavioral profiling, capturing the essence of user interactions.

Autofill Recognition:

Identify users based on their autofill behavior, contributing to a robust behavioral profile.

Copy-Paste Analytics:

Analyze copy-paste activities for a nuanced understanding of user behavior.


Getting Started

Minimum Requirements

  • minSdkVersion 21
  • AndroidX
  • The XML below is a representation of the permissions required. Please refer to the table below.
PERMISSIONUSAGE STATUS
USE_BIOMETRICREQUIRED
USE_FINGERPRINTREQUIRED
READ_GSERVICESREQUIRED
ACCESS_WIFI_STATEREQUIRED
ACCESS_NETWORK_STATEREQUIRED
ACCESS_GPSREQUIRED
CHANGE_WIFI_STATEREQUIRED
SYSTEM_ALERT_WINDOWREQUIRED
ACTION_MANAGE_OVERLAY_PERMISSIONREQUIRED
CHANGE_NETWORK_STATEREQUIRED
MANAGE_EXTERNAL STORAGEOPTIONAL
ACCESS_COARSE_LOCATIONREQUIRED
ACCESS_FINE_LOCATIONOPTIONAL
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.USE_BIOMETRIC" />
  <uses-permission android:name="android.permission.USE_FINGERPRINT" />
  <uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.ACCESS_GPS" />

  <uses-feature android:name="android.hardware.location.gps" />
  <uses-feature android:name="android.hardware.location" />

  <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
  <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
  <uses-permission android:name="android.permission.ACTION_MANAGE_OVERLAY_PERMISSION" />

Integration Steps

Flow Diagram

This diagram shows the interactions between your mobile app and Bureau's SDK.

  1. sessionID , userid and flow are made available to your front end application (preferable from backend where required).
  2. Call the BureauAPI.getBureauApiInstance()function with the parameters ( need to call this initiate in onCreate() of application class)
    1. sessionId - MANDATORY
    2. credentialId - MANDATORY
    3. environment - MANDATORY - default is production
    4. applicationInstance - MANDATORY - java class application
  3. Call the setters functions for the below mandatory parameters
    1. UserID - setUserId - meant to unique to a user for e.g. hashed value of a PAN number or SSN number or hash of mobile number
    2. Flow - setFlow - only allowed value is LOGIN_AUTHENTICATION - no other values are allowed
  4. If you want to collect behavioural signals, then do the following-
    1. Call startSubSession to commence the collection of raw behavioural data points
    2. Call stopSubSessionto end the collection of raw behavioural data points
    3. Ideally a typical flow would to start collecting after the launch of the application and stop collecting after the login or sign-in button is pressed when the user enters username and password
  5. Finally call the submit function to send the device and behavioural datapoints for processing
    1. Call submitfunction
  6. Upon successful submission of the parameters, a callback is received in the SDK. The next steps can be taken based on the callback (success/failure)
  7. After receiving a successful callback, invoke Bureau's backend API /v2/services/behaviour-device-insights to fetch the results of behavioural and device intelligence results such as device fingerprint ID, user similarity score, bot score and so on

Step 1 - SDK Implementation

Add following lines in your root build.gradle

Properties properties  = new Properties()
properties.load(new FileInputStream(project.rootProject.file('local.properties')))
buildscript {
.....
}
allprojects {
    repositories {
        google()
        jcenter()
        maven { url "https://packages.bureau.id/api/packages/Bureau/maven" }
    }
}
Latest Version

Add following lines in your module level build.gradle.

The latest version is 2.2.0

dependencies {
//add the following dependency in your gradle file
    implementation 'id.bureau:corelib:2.1.1'
}

This library also uses some common android libraries. So if you are not already using them then make sure you add these libraries to your module level build.gradle

  • androidx.appcompat:appcompat:1.2.0

Step 2 - Initialise SDK

The SDK is initialised in the client app. Once the submit function is called, the data relating to the user and device is automatically synced in the background.

//Get SDK Instance with Client Id and Environment
val sessionId = UUID.randomUUID().toString()
val bureauAPI : BureauAPI  = BureauAPI.getBureauApiInstance(
            this,
            YOUR_CLIENT_ID,
            sessionId,
            Environment.ENV_SANDBOX,
            true // true if you want to enable behavioral biometrics, default is false
        ) // need to call this initiate in onCreate() of application class

						val subSessionId = UUID.randomUUID().toString()
            bureauAPI.startSubSession(subSessionId) //call this to start collecting behavior biometrics signals
            
            bureauAPI.stopSubSession() //call this to stop collecting behavior biometrics signals
            
            bureauAPI.setFlow(YOUR_FLOW_NAME)//mandatory
            
            bureauAPI.setUserId(YOUR_USER_ID)//mandatory

//submit device and behavior(if enabled) data to Bureau's backend using the submit function
            bureauAPI.submit(object :
                DataCallback {
                override fun onError(errorMessage: ErrorResponse) {
                  
                }

                override fun onResult(message: SubmitResponse) {
                  
                }
            })
//Get SDK Instance with Client Id and Environment
BureauAPI bureauAPI = BureauInstanceProvider.getBureauApiInstance(context, "YOUR_CLIENT_ID", Environment.ENV_PRODUCTION);
bureauAPI.setSessionId("YOUR_SESSION_ID");  //Mandatory
bureauAPI.setFlow("your_flow_name");  //optional
bureauAPI.setUserId("your_user_id");  //optional

//Start collecting and submit data to Bureau's backend using the submit function
bureauAPI.submit((new DataCallback() {
   public void onError(@NotNull ErrorResponse errorMessage) {
       //implement your own logic
   }

   public void onResult(@NotNull SubmitResponse message) {
       //implement your own logic
   }
}));
Note:
  • To initialise the SDK we need to provide CREDENTIAL_ID.
  • Session ID i.e. is mandatory and unique for each submission.
  • To obtain the fingerprint Id query Bureau backend.
  • The default environment is production. If you want to run on UAT pass ENV_SANDBOX in getBureauApiInstance function.
Response returned from the SDK

The DataCallback added in the Submit function returns whether the device data has been registered or not.

object :DataCallback{
            override fun onError(errorMessage: ErrorResponse) {
               //Failure Callback
               Log.w(TAG,"Error "+errorMessage)
            }

            override fun onResult(message: SubmitResponse) {
                //Success Callback
                Log.w(TAG,"Success "+message)
            }
        }}
bureauAPI.submit((new DataCallback() {
   public void onError(@NotNull ErrorResponse errorMessage) {
       //implement your own logic
   }

   public void onResult(@NotNull SubmitResponse message) {
       //implement your own logic
   }
}));

Step 3 - Invoke API for Insights

To access insights from users and devices, including OTL, device fingerprint, and risk signals, integrating with Bureau's backend API is a must for both OTL and Device Intelligence.

Please find below the link to the respective API documentations:

Behavioural and Device Intelligence - https://docs.bureau.id/reference/device-intelligence

API Requests

The URL to Bureau's API service is either:

Authentication

API's are authenticated via an clientID and secret, they have to be base64 encoded and sent in the header with the parameter name as Authorisation.

Authorisation : Base64(clientID:secret)

curl --location --request POST 'https://api.overwatch.stg.bureau.id/v1/suppliers/device-fingerprint' \
--header 'Authorization: Basic MzNiNxxxx2ItZGU2M==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sessionKey": "697bb2d6-1111-1111-1111-548d6a809360"
}'

curl --location --request POST 'https://api.overwatch.bureau.id/v1/suppliers/device-fingerprint' \
--header 'Authorization: Basic MzNiNxxxx2ItZGU2M==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sessionKey": "697bb2d6-1111-1111-1111-548d6a809360"
}'

API Response

Bureau's Backend API will return one of the following HTTP status codes for every request:

{
    "GPSLocation": {
        "city": "Madurai",
        "country": "India",
        "latitude": 9.961932591738853,
        "longitude": 78.12884837677319,
        "region": "Tamil Nadu"
    },
    "IP": "106.51.82.180",
    "IPLocation": {
        "city": "Bengaluru",
        "country": "India",
        "latitude": 12.97623,
        "longitude": 77.603287,
        "region": "Karnataka"
    },
    "IPSecurity": {
        "isCrawler": false,
        "isProxy": false,
        "isTor": false,
        "VPN": false,
        "threatLevel": "LOW"
    },
    "IPType": "v4",
    "OS": "android",
    "accessibilityEnabled": false,
    "adbEnabled": true,
    "debuggable": true,
    "developerMode": false,
    "emulator": true,
    "fingerprint": "1e3f8831-a062-4b55-ad37-ee5f414f1941",
    "confidenceScore": 100,
    "firstSeenDays": 188,
    "googlePlayStoreInstall": false,
    "mockgps": false,
    "model": "M2006C3MII",
    "package": "com.prism.android.prismsampleapp",
    "rooted": true,
    "userId": "demo-session-shekh-prd-user-25677",
    "isAppTampered": null,
    "isAppCloned": false,
    "riskLevel": "HIGH",
    "totalUniqueUserId": 3,
    "remoteDesktop": false,
    "voiceCallDetected": false,
    "userSimilarityScore": 76.23,
    "behaviouralAnomalyscore": 12.2,
    "botDetectionScore": 0,
    "behaviouralFeatures": {
        "copyPasteActivity": "LOW",
        "autofillActivity": "LOW",
        "swipeActivityDetected": true,
        "backgroundAppPushActivity": "LOW",
        "fieldFocusActivity": "LOW",
        "sessionDurationInMS": 636
    },
    "isTrainingSession": false
    "sessionId": "demo-session-shekh-dev-android-2023-5-30-fp-640-19",
    "createdAt": 1686125656521,
    "riskLevel": "VERY_HIGH",
    "riskScore": 90.46
}

{
    "statusCode": 400,
    "error": {
        "code": 0,
        "type": "BAD_REQUEST",
        "message": "Session ID is missing",
        "description": "request does not contain additionalData.sessionKey param in request",
        "referenceId": "24f94ae8-xxxx-48a4-xxxx-b25f99fb06d9",
        "metadata": null
    },
    "timestamp": 1658402143450,
    "merchantId": "auth0|61dfbbxxxx3420071be7021",
    "requestId": "66403193-xxxx-44bc-xxxx-14735a45dfeb"
}
{
  "data": null,
  "errors": {
    "status": 401,
    "errorCode": "UNAUTHORIZED",
    "service": "Overwatch"
  },
  "message": "",
  "meta": {
    "length": 0,
    "took": 0,
    "total": 0
  }
}
{
    "error": {
        "code": 422,
        "description": "Failed to find fingerprint for given session ID",
        "message": "NO_RECORD_FOUND",
        "metadata": null,
        "referenceId": "",
        "type": "NO_RECORD_FOUND"
    },
    "merchantId": "auth0|61dfbbxxxx420071be7021",
    "requestId": "24e1aa7f-xxxx-404d-xxxx-5f8a0227e8f0",
    "statusCode": 422,
    "timestamp": 1658402132141
}
{
  "error": {
    "code": 0,
    "description": "",
    "message": "Server encountered an error",
    "metadata": null,
    "referenceId": "86529a18-a5cb-4da9-91b0-8d04cdb9167e",
    "type": "INTERNAL_SERVER_ERROR"
  },
  "merchantId": "auth0|61dfxxxx0071be7021",
  "requestId": "c69d86f0-xxxx-4ef0-xxxx-e687d595a507",
  "statusCode": 500,
  "timestamp": 1657009043753
}

Responses

HTTP Status Code Description

The Bureau's Backend API attempts to return the appropriate HTTP status code for every request. The following table illustrates the possible status codes and their meanings:

Status CodeStatus SummaryDescription
200Successful RequestThe request succeeded.
400Bad RequestRequest is not well-formed, syntactically incorrect, or violates schema. The server could not understand the request. Indicates one of these conditions:
1. The API cannot convert the payload data to the underlying data type.
2. The data is not in the expected data format.
3. A required field is not available.
4. A simple data validation error occurred.
401UnauthorisedThe server rejected the request because authentication credentials provided was not valid.
422No Record FoundThe API can't carry out the requested action to get the fingerprint generated from the provided Session Key or Session ID. It's possible that the sent Session Key or Session ID is incorrect.
500Internal Server ErrorA problem happened with the system or application. Even though the client's request seems right, something unexpected took place on the server.

Insight Response Descriptions

Bureau's Device Intelligence solution combines device and behavioral data to identify devices using fingerprints. With the application of Bureau's proprietary signal detection and fraud risk model, you can use these data to adeptly unveil and thwart fraudulent activities.

Signal AttributesDescription
GPSLocation(city, country, latitude, longitude, region)GPS Based location of the user's device. User's consent is required to be taken to get this details.
IPLocation(city, country, latitude, longitude, region)IP based location of the user.
IPIP address of the user.
VPNFlag to indicate if the IP being used by the user is a VPN. (Note the VPN within the IPSecurity JSON object should be used and not the one outside).
isCrawlerFlag to indicate if the IP being used by the user is associated with a crawler.
isProxyFlag to indicate if the IP being used by the user is a proxy.
isTorFlag to indicate if the IP being used by the user is of a Tor network.
threatLevelThe threat level associated with the IP. Possible values can be ["low", "medium", "high"]
IPTypeThe type of IP, ["v4", "v6"]
OSThe OS of the user's device.
debuggableFlag to indicate if the app is in debug mode.
developerModeBoolean Flag to indicate if the user has turned on developer options on their android OS
accessibilityEnabledBoolean Flag to indicate if the user has turned on the accessibility feature on android
adbEnabledBoolean Flag to indicate if the user enabled the android debugger bridge with the phone connecting the laptop and mobile
googlePlayStoreInstallBoolean Flag to indicate if the app has been installed outside of the Google Playstore
emulatorFlag to indicate if the app is being run on an emulator.
fingerprintA hash generated for the device, this identifier will be unique for a device.
firstSeenDaysThe number of days from which the device is identified on Bureau's network.
isAppClonedFlag to indicate if the app is cloned.
isAppTamperedFlag to indicate if the app is tampered.
mockgpsFlag to indicate if the user is spoofing their GPS location. This will need users permission for background location.
modelThe device model.
packageThe package name.
rootedFlag to indicate if the device is rooted.
remoteDesktopFlag to indicate whether a remote desktop monitoring session is detected
voiceCallDetectedFlag to indicate if a voice call was active when device data was collected
sessionIdThe session identifier, that was used to invoke the SDK.
riskLevelAlternative scoring models that incorporates data that is derived from the above raw signals. The possible values for the score are Low, Medium, High, and Very High.
riskScoreAlternative scoring models that uses data derived from the above raw signals.
userIdThe userID that was sent as part of the request body.
totalUniqueUserIdThe total number of unique usersIDs associated to the fingerprint.
confidenceScoreThe confidence score of the generated fingerprint.
userSimilarityScoreA score between 0-100 that indicates the similarity of behavioural actions of the user logging in. A higher score represents the same person. A score of less than 30 means there is a higher chance of a different person that requires attention.
behaviouralAnomalyscoreA float score between 0-100 that indicates a clear anomaly between the user's behaviour in comparison to the group average statistics. A higher score indicates that this user is behaving in a very different fashion from the average uses likely indicating fraudulent activity
botDetectionScoreA float score between 0-100 that indicates an automated attach. A higher score says there is a bot operating the login.
copyPasteActivityA string value that is high, medium or low. A high value implies that the user was trying to use copy paste multiple times.
autofillActivityA string value that is high, medium or low. A high value implies that the user was trying to use autofill repeatedly or is changing it over and over again.
swipeActivityDetectedA boolean - TRUE or FALSE. The user is trying to swipe in the password or the username - unlikely activity for login sessions.
backgroundAppPushActivityA string value that is high, medium or low.The user is toggling between different apps during this login session. They could be using many apps for other purposes in the background.
fieldFocusActivityA string value that is high, medium or low. A high value indicates behaviour that is more associated with a fraudsters' actions
sessionDurationInMSThe time taken from initiating the session to completing the login session.
isTrainingSessionThe first 6 sessions are considered are training sessions to train the model about a user's activity.

Go-live Checklist

To determine if your app has been tampered with, we will need your package name and signature hash code. Please share this information with us before going live. The hash code can be obtained from the PackageManager using the GET_SIGNING_CERTIFICATES permission. The signingInfo.signingCertificateHistory property will return a byte array containing the hash code.