Integrator manual
SDK
Get started
The Ironchip mobile SDK captures device information, location-related signals (GPS, Wi-Fi), and user sessions to help differentiate attackers from legit users. To gather risk assessment from the APIs, start by installing and configuring the mobile SDK.
Supported platforms
We currently support Android and iOS. The following are the latest SDK version for each operating system:
Android
Changelog
[1.2.7] - 2023-03-15 - nowadays
Added
- Changed transaction model to add information about the sim card.
Changed
Removed
[1.2.6] - 2023-02-02 - 2023-03-15
Added
Changed
- Changed transaction model to add the requested permissions and if they are granted.
- Changed transaction model to add if the gps and wifi providers are enabled.
Removed
[1.2.5] - 2023-01-13 - 2023-02-02
Added
Changed
- Fixed proguard configuration causing the consumer application to be repackaged into our library internal folder.
Removed
[1.2.4] - 2023-01-10 - 2023-01-13
Added
Changed
- Errors during the send transaction callback will now be logged instead of redirected to the exception callback.
Removed
[1.2.3] - 2022-12-09 - 2023-01-10
Added
Changed
- Fixed issue with the fingerprint id.
Removed
[1.2.2] - 2022-11-30 - 2022-12-09
Added
Changed
- Fix a bug when not connected to a wifi.
- Fix new lines on the encrypted ids.
- Improved the emulation detection.
Removed
[1.2.1] - 2022-11-23 - 2022-11-30
Added
Changed
- Class name refactorization.
- Changed the tags on the logs to match the refactorization.
- Fraud constructor no longer supports a url host, it only allow to select the desired environment.
Removed
[1.2.0] - 2022-10-12 - 2022-11-22
Added
- Added kernel version into the device properties
- Debug logs
Changed
- Fixed bugs with the JSON sending strings instead of arrays
- Improvement to the device id, installation id and fingerprint
- GPS and Signal can no longer cause a blockage in the process
Removed
[1.1.3] - 2022-09-30 - 2022-10-12
Added
Changed
- Publish repository from nexus to github.
Removed
[1.1.2] - 2022-09-30 - 2022-10-12
Added
- Compatibility for versions 5+
Changed
Removed
[1.1.0] - 2022-09-22 - 2022-09-30
Added
- LICENSE file added to the project
Changed
- Refactor module name.
Removed
[1.0.2] - 2022-09-10 - 2022-09-22
Added
- Custom exceptions
Changed
- Excluded callbacks and exceptions from offuscation for easier client use.
- Changed model paramters names and structure.
Removed
[1.0.1] - 2022-09-10 - 2022-09-12
Added
- CI/CD to build and publish on the dev, testing and release branches.
Changed
- Excluded callbacks and exceptions from offuscation for easier client use.
- Changed model paramters names and structure.
Removed
[1.0.0] - 2022-09-10
Added
- Code obfuscation and gitignore extended.
Changed
- Migrated code sections of the code to a common library.
- Modified the behaviour of the GPS service.
Removed
Setup
Supported versions
Platform Supported versions Android 5.0.0+ Add Ironchip Location Based Fraud SDK
Add our library in other projects
First, on the setting.gradle file, reference the remote repository where the library is located.
dependencyResolutionManagement {
...
repositories {
maven { url 'https://jitpack.io' }
...
}
}Then, inside the gradle.build file, add the dependency to the sdk.
dependencies {
...
implementation 'com.github.Ironchip-Security:LBFraud-SDK-Android:1.2.7'
...
}Permissions
Add the following permissions to your manifest:
<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.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
Usage
Use in an app
To make full use of the potential of the sdk, the ACCESS_FINE_LOCATION permission needs to be granted.
import com.ironchip.ironchiplbfraudandroidsdk.LBFraudSDK;
...
// Replace APIKEY with the desired generated api key.
LBFraudSDK fraud = new LBFraudSDK(this, "APIKEY");
// By default our SDK target to the production environment.
// In case you desire to target a diferent enviroment:
// LBFraudSDK fraud = new LBFraudSDK(this, "APIKEY", LBFraudSDK.Environment.Testing);
//public enum Environment {
// Production,
// Testing,
// Development
//}
String transactionID = "random_identifier_generated"; // Transaction identifier request for fraud results
String userID = "john.doe@gmail.com"; // User identifier
Map<String, Object> extraData = new HashMap<>(); // Extra information for analysis
extraData.put("concept", "Book august");
extraData.put("amount", new Integer(30));
extraData.put("operation", "booking");
// TransactionID (required,unique): transaction identifier request for fraud results
// UserID (required): User identifier
// ExtraData (optional): extra information for analysis
// The sendTransaction can be provided with 2 callbacks, one is executed when the transaction is finished
// and the other one is called in case an error did occure during the transaction process.
fraud.sendTransaction(transactionID, userID, extraData, () -> {
// Add here any code you want to be executed after the transaction
// has finished.
}, exception -> {
// Add here any code you want to perform in case of an error
// during the transaction.
// exception.printStackTrace()
});
IOS
Changelog
[1.2.7] - 2023-03-23 - nowadays
Added
Changed
- Commons has been made to link to LBFraud and not be embedded.
Removed
[1.2.6] - 2023-03-15 - 2023-03-23
Added
- Changed the transaction model to add information about the device’s SIM and eSIM cards.
Changed
Removed
[1.2.5] - 2023-02-02 - 2023-03-15
Added
Changed
- Changed transaction model to add the requested permissions status.
- Changed transaction model to add if the gps and wifi providers are enabled.
Removed
[1.2.4] - 2022-12-20 - 2023-02-02
Added
Changed
- Fixed the problem when validating the application in the Apple Store.
- Location service logs for iOS 13.
Removed
[1.2.3] - 2022-12-09 - 2022-12-20
Added
Changed
- Fixed issue with the fingerprint id.
- Handle external HTTP cals.
Removed
[1.2.2] - 2022-11-30 - 2022-12-09
Added
Changed
- Change some property of the device in the transaction model.
Removed
[1.2.1] - 2022-11-23 - 2022-11-30
Added
Changed
- Class name refactorization.
- Changed the tags on the logs to match the refactorization.
- Fraud constructor no longer supports a url host, it only allow to select the desired environment.
- GPS service, throw error when permission is not granted or Location service is disabled.
Removed
[1.2.0] - 2022-11-16 - 2022-11-22
Added
- Debug Logs
Changed
- Management of new errors in Commons library.
- Changes in the transaction model.
Removed
- Network errors, now throw the generic not custom ones
[1.1.8] - 2022-10-25 - 2022-10-31
Added
Changed
- Version 1.1.7 is promoted to 1.1.8 because of organizative reasons.
Removed
[1.1.7] - 2022-10-25 - 2022-10-25
Added
- Compatibility for versions 13+.
Changed
- Change url from Nexus to GitHub.
Removed
[1.1.6] - 2022-09-14 - 2022-10-25
Added
Changed
Removed
- Unnecesary prints.
[1.1.5] - 2022-09-14 - 2022-09-14
Added
- In commons library throw custom errors, and in LBFraud rethrow them.
Changed
- Rename commons Services.
Removed
[1.1.4] - 2022-09-12 - 2022-09-14
Added
- Add CHANGELOG file to the project.
Changed
- Changed model parameters names and structure.
Removed
[1.1.2] - 2022-09-03 - 2022-09-12
Added
Changed
- Change nexus repository name of .xcframework.zip.
Removed
[1.1.1] - 2022-08-27 - 2022-09-03
Added
- Now the project have two .xcframework one from Commons Library and the other from LBFraud.
Changed
- Now the Swift Package is getting the .xcframework from remote not local one.
Removed
[1.1.0] - 2022-08-24 - 2022-08-27
Added
- LICENSE file added to the project.Changed
Removed
[1.0.9] - 2022-08-23
Added
- First Stable version of a SwiftPackage with one XCFramework called LBFraudSDKiOS.xcframework.
- gitignore added.Changed
Removed
Setup
Supported versions
Platform Supported versions iOS 13.0.0+ Add Ironchip Location Based Authentication SDK
Using Xcode:
To import this swift package dependency, in Xcode go to the root of your application for example ExampleApp.xcodeproj, at the top in PROJECT select ExampleApp item and go to the thrird tab, Package dependencies, select + button.
A pop up will open and in search or enter url copy the repositorie url and press add package button.
In this case: https://github.com/Ironchip-Security/LBFraud-SDK-iOS.git
A new window appears, in dependency rule, you can select an exact version, a range of versions, a branch… in this case to test it you can choose the exact version 1.2.7 and finally add the package to use it, or a range like 1.0.9 < 1.2.7, we recommend to ease package upgrades that you use a range of versions
To be able to use Ironchip LBFraud as a SwiftPackage you will need to add to the target of your app a capability so go to Singing and Capabilities and add access Wifi Information.
Then in the Target of the app in info tab you have to add the key values of location permission.
- Privacy - Location Always and When In Use Usage Description, and insert the description as string
- Privacy - Location When In Use Usage Description, and insert the description as string
- Privacy - Location Always Usage Description, and insert the description as string
- LSApplicationQueriesSchemes, and insert the description (this permission is to be able to know if the device is jailbroken)
First of all you have to request Location Permission in your app:
import CoreLocation
let locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()
Usage
Use in an app
The library initialization method must be called in the main thread.
import LBFraudSDKiOS
...
// Replace apikey with the desired generated api key.
let ironchipLBFraud = LBFraudSDKiOS.init(apikey: "XXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
// By default our SDK target to the production environment.
// In case you desire to target a diferent enviroment:
// let ironchipLBFraud = LBFraudSDKiOS.init(apikey: "XXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", environment: Environment.Testing)
//public enum Environment: String {
// case Production
// case Testing
// case Development
//}
//Call Ironchip Location Based Antifraud to Analyze transaction
let data: [String: Any] = [
"concept": "Book august",
"amount": 60,
"operation": "booking"
]
//TransactionID (required,unique): transaction identifier request for fraud results
//UserID (required): User identifier
//ExtraData (optional): extra information for analysis
// The sendTransaction can be provided with 2 callbacks, one is executed when the transaction is finished
// and the other one is called in case an error did occure during the transaction process.
ironchipLBFraud.sendTransaction(transactionId: "random_identifier_generated", userId: "john.doe@gmail.com", extraData: extraData, finish: {
// Add here any code you want to be executed after the transaction has finished.
}, onError: { err in
// Add here any code you want to perform in case of an error
// during the transaction.
// example:
//if(err is TransactionError) {
// let transactionError = err as! TransactionError
// print(transactionError.traceability_id)
// print(transactionError.message)
// print(transactionError.http_code)
// print(transactionError.code)
//} else {
// print("NetworkError: ", err)
//}
}
)
Web
Changelog
[0.1.0] - 202-02-22
Added
- First version of the Web SDK
Changed
Removed
Setup
What is LBFraud web SDK?
LBFraud web SDK is the piece that allow you to integrate Ironchip LBFraud in your web environment. Using it Ironchip can evaluate if the device and environment that uses the website is secure. To add the SDK to the website you just need to follow the next steps.
JavaScript integration
First, you need to download the necessary JavaScript file (Click here). Once you have it you need to import the file
import { LBFraudSDK, LBFraudSDKEnvironment } from 'ironchip.modern.js';Then, with the SDK imported you need to initialize the client. Please ensure that you have the API- Key and the environment where you will work. By default the chosen environment is Production.
You will initialize the client (Choose just one environment):
const client = new LBFraudSDK({
apiKey: 'api-key',
environment: LBFraudSDKEnvironment.Development,
LBFraudSDKEnvironment.Testing,
LBFraudSDKEnvironment.Production,
});
Usage
No sooner you initialize the client you can send transaction using the next method.
You have to pass as entry parameters the Transaction ID and the User ID.
client
.sendTransaction(transactionID, userID)And that is all. Every time the method is called it will send a transaction.
Full example
The following code is a very simple example to test the SDK
test.js
import { LBFraudSDK, LBFraudSDKEnvironment } from './ironchip.modern.js';
const client = new LBFraudSDK({
apiKey: 'api-key',
environment: LBFraudSDKEnvironment.Testing
});
const myButton = document.getElementById('myButton');
function setListener() {
myButton.onclick = function(){
const transactionID = document.getElementById('transactionId').value;
const userID = document.getElementById('userId').value;
client
.sendTransaction(transactionID, userID)
.then((success) => {console.log(success)})
.catch((errorMsg) => {
console.log(errorMsg)
});
}
}
window.onload=function(){
setListener()
}index.html
<!DOCTYPE html>
<html>
<head>
<title>Web SDK test</title>
</head>
<body>
<label for="transactionId">Transaction ID:</label>
<input type="text" id="transactionId" name="transactionId">
<label for="userId">User ID:</label>
<input type="text" id="userId" name="userId">
<button id="myButton">Send transaction</button>
<script type="module" src="test.js"></script>
</body>
</html>
API's
Generating an access api-key
All endpoints are protected by an api-key.
Once you generate the api-key, send it through the Authorization header as follows:
Authorization: <apikey>To generate the api-key, go to the Credentials page, click on ‘Generate api-key’:
With this api-key you will have access to all possible requests. The generated QR is used to synchronize the mobile application with the dashboard.
API libraries
Official libraries are available to help the integration with the Ironchip API. These libraries serve as API wrappers and handle features such as:
- Transparent API authentication
- Requests for all available endpoints
- HTTP error handling
Understanding risk assesssments
Risk assessment types
Ironchip may provide four types of risk assessments, which depend on our confidence level in a given action performed by a device:
- fraud: Ironchip deems the action performed by the device as fraudulent, involved in a fraud
- high_risk: Ironchip deems the action (e.g. sign up, login) performed by the device to be potentially fraudulent, and advises you to take preventive actions in these scenarios.
- low_risk: ironchip considers this action performed by the device to be safe to accept.
- unknown_risk: ironchip is unable to provide a precise assessment at the time of the request.
Risk assessment evidences
Ironchip’s APIs rely on evidence to provide risk assessments. This decision is built on top of different analyses through distinct lenses.
The table below describes possible evidence values, their meaning, and which use cases they impact.
Understanding sensor match type
Match Type Description gps When Ironchip is able to perform comparisons by GPS data. wifi_scan When Ironchip is able to perform comparisons by Wi-Fi sensors, but no matching connected networks are found. wifi_connection When Ironchip is able to perform comparisons by connected Wi-Fi networks. mobile_networks When Ironchip is able to perform comparisons by connected Mobile networks. Risk assessment decision
Ironchip’s APIs rely on decisions to provide risk assessments. This decision is built on top of different analyses through distinct lenses.
The table below describes possible decisions values, their meaning, and which use cases they impact.
Decision Description Type SIM Swapping / ATO Detected Account Takeover based or not on Sim Swapping attack (depending on client user protection) string Phising Detected phising attack from specific location (Multiple ATO) string Synthetic identity Detected Synthetic Identity attack string New user New user detected in Ironchip’s platform string Location fraud Detected location fraud attempt by user comparing all location datasources string Banned location Detected location from a banned place. In example: Location detected from russia string Device Swapping Detected legitimate device swapping of a user string Location Swapping Detected legitimate location swapping of a user string Common usage Detected common usage string
Report API
Documentation
Ironchip AntiFraud API reference
Ironchip Antifraud API provides seamless identity verification that reduces trusted user verification and onboarding time, and detects application fraud. Check device location behavior to provide risk assessment and supporting evidence.
When a device is new to the Ironchip network, our technology determines the location of the new user. At the same time, each operation collects location data and provides an updated risk assessment.
In order to evaluate a new registration, Ironchip needs to receive a token to identify the device from which it originates.
Get the specific report
GET
https://report.lbfraud.ironchip.com/report/{transaction_id}?timeout=TIMEOUTThis method allows you to query the latest assessment for a given transaction event, identified by its id.
RequestResponseSample Curl:
curl -X 'GET' \
'https://dev.report.lbfraud.ironchip.com/report/lHsGJ?timeout=TIMEOUT' \
-H 'accept: application/json' \
-H 'Authorization: APIKEY'Response body
For a 200-OK response, these are the fields you should expect as a result:
Response field Type Description id integer Unique report identifier which can be used to verify if the assessment changed in later calls. transaction_id string A unique identifier to the user’s transaction. application_id string event object Assessment result. The object provides risk assessment and fraud case. user object An object with the information of the user who made the transaction. device object An object with the information of the device with which the transaction was made. location object An object with the information of the location in which the transaction was made. ip object An object with the information of the ip used to make the transaction. descriptive_report string String understandable to any customer. latencies object An object with the information of all latencies. latency integer The latency with which a report has been made. Get all reports
GET
https://report.lbfraud.ironchip.com/reports?limit=LIMIT&since=SINCE&user=USER&risk=RISKThis method allows you to query assessments, these assessments could be parameterized by limit number of reports, since report generation, user involved and risk assigment.
RequestResponseSample Curl:
curl -X 'GET' \
'https://dev.report.lbfraud.ironchip.com/reports?limit=LIMIT&since=SINCE&user=USER&risk=RISK' \
-H 'accept: application/json' \
-H 'Authorization: APIKEY'Response body
For a 200-OK response, the fields you should expect as a result are the same as when you make a report request.
Realtime reports
GET
This method allows you to view all the reports in realtime. This request is unsupported via web. It have not any request paremeter.
ResponseResponse body
For a 200-OK response, the fields you should expect as a result are the same as when you make a report request.
Release notes
1.0.2
Features
- Added swagger documentation.
- Batch and streaming report API.
- Pagination.
- New client dashboard to manage and view metrics.
- Transaction processing time improvement.
- Bussiness rule engine added to time procesing.
- Banned location settings added.