Web SDK

Welcome to our web plugin designed to seamlessly integrate with the Bureau's Device Intelligence, enhancing the functionality of mobile apps or webpages.

Overview: Device Intelligence

Our Device Intelligence module empowers you to gain comprehensive insights into your users by meticulously gathering data on their devices. This data serves as the foundation for creating a distinctive identifier for each user, known as a device fingerprint. The device fingerprint not only enables user identification but also facilitates the tracking of user activities across various sessions.

Key Features:

Seamless Integration: Effortlessly incorporate the Flutter plugin into your existing applications, ensuring a smooth and unobtrusive user experience.

Anti-Fraud Accuracy: Benefit from our solution's exceptional anti-fraud capabilities, safeguarding your platform against potential threats while maintaining accuracy and reliability.

Trusted Device View: Obtain a reliable view of trusted devices, allowing you to make informed decisions without compromising user interactions.


Getting Started

This is compatible with all front end browser frameworks that work with JS and HTML. The common one includes - JS, React, Vue, Flutter, Angular and so on.

Integration Steps

Include the following script in your HTML page.

<script src="https://fingerprint.app.stg.bureau.id/index.js"></script> 
<script src="https://fingerprint.app.bureau.id/index.js"></script> 

​​Initializing an SDK instance

Inside your JavaScript code, initialize SDK with the Session ID, Client ID, and environment once the page is loaded. This initializes the data-capturing functionality and collects browser data such as the device's IP address, browser, and operating system.

Example:

window._Fingerprint.init({ 
	sessionId:'f3199e64-cce9-47a2-a79c-67d55314',
	clientId:'3e912115-7890-4238-a123-ab4bb6d82975', 
	userId:'7a68c98e-feb5-4dc0-b9ff-85b469ba97b5', 
	environment:'SANDBOX'
});
window._Fingerprint.init({ 
	sessionId:'f3199e64-cce9-47a2-a79c-67d55314',
	clientId:'3e912115-7890-4238-a123-ab4bb6d82975', 
	userId:'7a68c98e-feb5-4dc0-b9ff-85b469ba97b5', 
	environment:'PRODUCTION'
});

Learn more

Submitting an SDK

This submits the collected data to the Bureau and generates a fingerprint. Invoke this method at the end of your page.

window._Fingerprint.onSubmit((response)=>{
  //do something
});

Learn more

Invoke API for Insights

To access insights about users, devices, browser fingerprints, and risk signals, invoke the following API from your backend.
Sandbox - https://api.overwatch.stg.bureau.id/v1/suppliers/device-fingerprint
Production - https://api.overwatch.bureau.id/v1/suppliers/device-fingerprint

Example:

curl --location 'https://api.overwatch.stg.bureau.id/v1/suppliers/device-fingerprint' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MW==' \
--data '{   
        "sessionId": "f3199e64-cce9-47a2-a79c-67d55314"
}'
curl --location 'https://api.overwatch.bureau.id/v1/suppliers/device-fingerprint' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MW==' \
--data '{   
        "sessionId": "f3199e64-cce9-47a2-a79c-67d55314"
}'

Note: Make sure the Init and Submit methods are called before invoking this.
Learn more

The diagram is a typical implementation of our browser SDK.

  1. sessionKey and userid are generated / retrieved by the client backend and sent to your application
  2. Your mobile application initialises our SDK through the init function by setting these attributes -
    1. Session ID (mandatory unique UUID)
    2. User ID (optional)
    3. Flow (optional)
  3. Invoke the submit function in SDK to pass the data to Bureau backend.
  4. 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).
  5. If the callback is successful, your mobile application relays the success to your backend
  6. Invoke Bureau's backend API /v1/suppliers/device-fingerprint to fetch insights
    1. Input :sessionId
  7. Based on the insights provided (fingerprint, and risk signals), you can determine the next steps for the user, such as allowing, blocking, or redirecting them.

Additional information

init

  • This method integrates the SDK with an object that has an environment, session ID and client ID.
  • We recommend initializing the SDK at the root of your website, but it can be placed anywhere depending on your use case.

Example:

window._Fingerprint.init({ 
	sessionId:'f3199e64-cce9-47a2-a79c-67d55314',
	clientId:'3e912115-7890-4238-a123-ab4bb6d82975', 
	userId :'7a68c98e-feb5-4dc0-b9ff-85b469ba97b5', 
	environment:'SANDBOX'
});
window._Fingerprint.init({ 
	sessionId:'f3199e64-cce9-47a2-a79c-67d55314',
	clientId:'3e912115-7890-4238-a123-ab4bb6d82975', 
	userId :'7a68c98e-feb5-4dc0-b9ff-85b469ba97b5', 
	environment:'PRODUCTION'
});

Parameters

sessionId

String Required

Session ID for the page. Make sure that for each init call, the sessionId must be unique. In case of duplicate sessionId, a 409 will be thrown during the submit call.

clientId

String Required

To identify the client. This will be shared with you from the Bureau. This will be static key.

userId

String Optional

To identify the user. This can be set later using setUserId API. Learn more

environment

String Required

Run the SDK in SANDBOX or PRODUCTION mode.

Return value

Null


submit

  • Invoking this function will call the Bureau's SDK POST endpoint, passing the details captured after the init() function to generate a fingerprint.
  • Call this method at the end of your page.
  • Examples:
    • After Sign in/Sign up
    • After address change confirmation
    • Nominee change confirmation
    • Email / password change confirmation
    • After payment / pre-payment initiation

Example:

window._Fingerprint.onSubmit((response)=>{
	//do something
});

Parameters

callback

Function Optional
You will get a callback on successful submission if a callback function is provided.

Example:

function callback(response){  
	if(response.status === 200){  
		console.log("Submit is successful")  
	}else{  
		console.log("Submit is not successful")  
	}  
}  
window._Fingerprint.submit(callback);

setuserid

You can also set the user ID later using the following API. Note: This should be called before 'submit API' call.

window._Fingerprint.setUserId('Merchant_ABC');

insights

Invoke API for insights

  • To access insights about users, devices, browser fingerprints, and risk signals.
  • Make sure the init and submit methods are called before invoking this.

Syntax:

curl --location 'https://api.overwatch.stg.bureau.id/v1/suppliers/device-fingerprint' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MW==' \
--data '{   
        "sessionId": "f3199e64-cce9-47a2-a79c-67d55314"
}'
curl --location 'https://api.overwatch.bureau.id/v1/suppliers/device-fingerprint' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MW==' \
--data '{   
        "sessionId": "f3199e64-cce9-47a2-a79c-67d55314"
}'

Parameters

Authorization

String Required
Authorization header. This will be shared by Bureau.

sessionId

String Required
The session Id should be the same as the one used during the initialization function's session ID.

API Response

{
  "sessionId": "0be8c4ab-1185-4b50-90ce-c5d3c3c2743a",
  "userId": "",
  "fingerprint": "b1630855-f27b-4ab7-ba96-bc822db36284",
  "networkInformation": {
    "isp": "Bharat Sanchar Nigam Limited",
    "ipType": "HOME"
  },
  "GPSLocation": {
    "city": "Bangalore",
    "country": "India",
    "latitude": 51.5207,
    "longitude": -0.1550,
    "region": "Karnataka"
  },
  "IPLocation": {
    "city": "Bangalore",
    "country": "India",
    "latitude": 51.5207,
    "longitude": -0.1550,
    "region": "Karnataka"
  },
  "IPSecurity": {
    "isCrawler": false,
    "isProxy": false,
    "isTor": false,
    "VPN": false,
    "threatLevel": "LOW"
  },
  "totalUniqueUserId": 1,
  "firstSeenDays": 6,
  "createdAt": 1695294348960,
  "OS": "",
  "riskLevel": "MEDIUM",
  "riskScore": 26.29,
  "platform": "web",
  "fingerprintConfidenceScore": "87",
  "ip": "192.168.369.619",
  "trueUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
  "userAgentSpoof": false,
  "incognitoDetected": false,
  "adBlockerDetected": false,
  "botDetectionScore": 100,
  "detectCanvasSpoof": false,
  "anonymisationAttempted": true,
  "anonymisationAttemptedReasons": [
    "webgl spoof",
    "canvas spoof",
    "font manipulation"
  ]
}
{
    "statusCode": 400,
    "error": {
        "code": 0,
        "type": "BAD_REQUEST",
        "message": "Session key 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 key",
        "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

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 Description

KeyDescription
GPS Location(city, country, latitude, longitude, region)GPS Based location of the user, the user's consent is required to be taken to get these details.
Network Information - ISP NameThe name of the internet service provider for e.g. Atria Convergence Technologies
IP TypeHOME / OFFICE - OFFICE for Commercial uses like cloud or AWS
IP Location(city, country, latitude, longitude, region)IP-based location of the user.
IPThe IP address of the user.
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", "very_high"]
fingerprintA hash is generated for the device, this identifier will be unique for the device.
fingerprintConfidenceScoreThe confidence score of the fingerprint generation mechanism
firstSeenDaysThe number of days from which the device is identified on the Bureau's network.
osThe operating system - MAC or Android or Windows
platformWeb
userIdThe user ID that was sent as part of the request body.
totalUniqueUserIdTotal number of unique users associated with the fingerprint
sessionIdThe session identifier, that was used to invoke the SDK.
createdAtThe time at which the request was made.
TrueUserAgentThe actual user agent behind the browser
adBlockerDetectedFlag to indicate if the user's has enabled adblocker
incognitoDetectedFlag to indicate if the user's is working in incognito
userAgentSpoofFlag to indicate if the users have spoofed user agent to avoid being detected via automation or to anonymize themselves
botDetectionScoreBot detection score between 0-100
anonymisationAttemptedFlag to indicate if the user is trying something to avoid being detected via automation or to anonymize themselves
anonymisationAttemptedReasonsThe array of strings indicates the methods by which users are trying to avoid being detected.
riskLevelAlternative scoring models that incorporate 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 use data derived from the above raw signals.

What’s Next

Understand how to fetch insights from the server side endpoint