Minimum Requirements

• Xcode 11.0+
• iOS Deployment Target > 13.0 & Mac OS > 12.0.

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 frontend application (preferable from the backend where required).
2. Call the BureauAPI.shared.configure()function with the parameters ( need to call this initiate in anywhere ex:ViewDidLoad()-UIViewController or didFinishLaunchingWithOptions()-AppDelegate )
   1. clientID - MANDATORY
   2. environment - MANDATORY
   3. sessionID - MANDATORY
   4. enableBehavioralBiometrics - MANDATORY - true/false
3. Call the setters functions for the below mandatory parameters
   1. UserID - setUserId - meant to be unique to a user e.g. hashed value of a PAN number or SSN or hash of mobile number
4. Call the setters functions for the below optional parameters
   1. Flow - setFlow - String ex: "LOGIN_AUTHENTICATION"
5. If you want to collect behavior signals, then do the following-
   1. Call startSubSession to commence the collection of raw behavior data points
   2. Call stopSubSessionto end the collection of raw behavior data points
   3. Ideally, a typical flow would start collecting after the launch of the application and stop collecting after the login or sign-in button is pressed when the user enters the username and password
6. Finally, call the submit function to send the device and behavior data points for processing
   1. Call submitfunction
7. 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)
8. After receiving a successful callback, invoke Bureau's backend API /v2/services/behaviour-device-insights to fetch the results of behavior and device intelligence results such as device fingerprint ID, user similarity score, and bot score.

Quick Start

Step 1 - Add Dependency

1. SDK is available through CocoaPods. To install it, simply add the following line to your Podfile:

# Podfile
pod 'bureau-id-fraud-sdk'

#Add below lines to end of your pod file
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      if target.name == "Sentry" || target.name == "SwiftProtobuf" then
        config.build_settings["BUILD_LIBRARY_FOR_DISTRIBUTION"] = 'YES'
      end
    end
  end
end

2. "import bureau_id_fraud_sdk" in your UIViewcontroller
3. Info.plist -> Add below properties
   • “NSUserTrackingUsageDescription”
   • “NSLocationAlwaysAndWhenInUseUsageDescription”
   • “Privacy - Location When In Use Usage Description”

Step 2 - Initialise SDK

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

// Initialize BureauAPI Where ever you want AppDelegate or ViewController

BureauAPI.shared.configure(clientID: "***CLIENT ID**", environment: .production, sessionID: "*** SESSION ID ***", enableBehavioralBiometrics: true)

// clientID  -> Bureau Merchant Id
// environment -> .stage, .production, .sandbox
// sessionID -> unique String value
// enableBehavioralBiometrics -> true/false

BureauAPI.shared.setUserID("***USER ID***")

//call this to start collecting behavior biometrics signals
BureauAPI.shared.startSubSession(NSUUID().uuidString)

BureauAPI.shared.stopSubSession() //Optional -> suppose if we are not call this function
															 //it will call automatically when BureauAPI.shared.submit() 

//assign the delegate where you want to get a callback response from SDK
BureauAPI.shared.fingerprintDelegate = self

BureauAPI.shared.submit() //submit device and behavior(if enabled) data to Bureau's backend using the submit function

📘

Note

Client ID and Session ID should be mandatory. Session ID should be unique for every request.

Response returned from the SDK

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

// Should need to extent the PrismDelegate for your View controller
extension YourViewController : PrismFingerPrintDelegate{ }

// onFinished Delegate will trigger after success or failure Fingerprint SDK completion 
func onFinished(data: [String : Any]?) { }

// “data” returning blow key values
// "statusCode"  -> Int? ( if statusCode == 200 or 409 “success” else “failure” ) 
// “apiResponse” -> NSDictionary?

Step 3 - Invoke API for Insights

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

Sample Request and Response

Below is a sample request and response for our Device Intelligence API. Refer to our Behavior Biometrics API documentation for more details.

Contact our support team at [email protected] to get your API keys and the production endpoint for the API.

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

{
  "GPSLocation": {
    "city": "",
    "country": "",
    "latitude": 0,
    "longitude": 0,
    "region": ""
  },
  "IP": "106.51.82.180",
  "IPLocation": {
    "city": "Bengaluru",
    "country": "India",
    "latitude": 12.976229667663574,
    "longitude": 77.60328674316406,
    "region": "Karnataka"
  },
  "IPSecurity": {
    "VPN": false,
    "isCrawler": false,
    "isProxy": false,
    "isTor": false,
    "threatLevel": "LOW"
  },
  "IPType": "v4",
  "OS": "ios",
  "accessibilityEnabled": false,
  "adbEnabled": false,
  "behaviouralFeatures": {
    "autofillActivity": "LOW",
    "backgroundAppPushActivity": "LOW",
    "copyPasteActivity": "LOW",
    "fieldFocusActivity": "LOW",
    "sessionDurationInMS": 596908510,
    "swipeActivityDetected": false
  },
  "behaviouralRiskLevel": "MEDIUM",
  "behaviouralRiskScore": 26.79,
  "botDetectionScore": 0,
  "confidenceScore": 20,
  "createdAt": 1712648006459,
  "debuggable": true,
  "developerMode": false,
  "deviceRiskLevel": "VERY_HIGH",
  "deviceRiskScore": 81.51,
  "emulator": false,
  "factoryResetRisk": "LOW",
  "factoryResetTime": null,
  "fingerprint": "68055d2e-4811-45db-a298-cb4ff17eb2c8",
  "firstSeenDays": 12,
  "googlePlayStoreInstall": false,
  "isAppCloned": true,
  "isAppTampered": null,
  "isDebuggingEnabled": null,
  "isOEMUnlockAllowed": null,
  "isSimPresent": null,
  "isTrainingSession": false,
  "merchantId": "auth0|623980a33d162b006930a877",
  "mitmAttackDetected": false,
  "mockgps": false,
  "model": "SM-M326B",
  "networkInformation": {
    "ipType": "HOME",
    "isp": "Atria Convergence Technologies Pvt. Ltd."
  },
  "package": "id.bureau.deviceintelligence",
  "remoteDesktop": false,
  "requestId": "0a55480c-faf0-44a7-a9e3-fe3353e34214",
  "riskCauses": [
    "DEBUGGER",
    "IS_APP_CLONED"
  ],
  "riskLevel": "VERY_HIGH",
  "riskScore": 65.094,
  "rooted": false,
  "sessionId": "f70a2b7d-dd75-4075-9ba1-ee4ee2e20b5a",
  "statusCode": 200,
  "timestamp": 1713427163350,
  "totalUniqueUserId": 3,
  "userId": "sriram",
  "userSimilarityScore": 23.924109706617298,
  "voiceCallDetected": false
}

Error Codes

The table below lists a few error codes returned by Bureau's SDKs.

Verifying App Integrity with Signature Hash

Before going live, we must ensure your app hasn't been tampered with. This helps protect both you and your users.

Here's how you can verify your app's integrity:

Gather Information

• Package Name: This is the unique identifier for your app on the platform (e.g., com.yourcompany.myapp). It typically follows a reverse domain name structure, such as:
  • com.<yourcompany>.<appname>
  • com.<yourcompany>.<appname>:<servicename> (if using sub-organizations)
• Signature Hash Code: This code is generated from your app's signing certificate and helps verify its authenticity.

Get the Signature Hash Code

Most development environments provide built-in tools for obtaining the signature hash code. Below is a common way (using the GET_SIGNING_CERTIFICATES permission):

• Access your project's settings in the PackageManager.
• Look for the permission section and ensure you have the GET_SIGNING_CERTIFICATES permission enabled.
• Once enabled, follow the specific instructions provided by your development environment to retrieve the signature hash code. It's usually found within a property like signingInfo.signingCertificateHistory and will be a byte array representation of the hash.

Share the Information

Once you have your package name and signature hash code, please share them with us before launching your app live. This allows us to verify the app's authenticity and protect both you and your users.