iOS Native

Welcome to our iOS 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:

To integrate our native SDK into your project, follow the comprehensive documentation provided below. Ensure a seamless implementation and unlock the full potential of Device Intelligence for your application.


Getting Started

Minimum Requirements

  • Xcode 11.0+
  • iOS Deployment Target > 13.0 & Mac OS > 12.0.
Permission TypeDescription
OptionalMonitoring the Battery - UIDevice.current.isBatteryMonitoringEnabled //
OptionalUser Current location - CLLocationManager.locationServicesEnabled() //
RequiredFor Advertising Identifier IDFA - requestTrackingAuthorization

Integration Steps

At its core, the solution functions through three straightforward steps:

  1. Start by implementing Device Intelligence + OTL SDK with mobile application.
  2. Initialize the SDK using either the Client ID or Credential ID. This enables us to gather user and device data. We will then thoroughly analyze and enhance the collected data in the background.
  3. You can then utilize our API to access insights, aiding you in deciding the subsequent actions for your user, whether it's permitting, obstructing, or redirecting them.

Integration Overview

  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.

Step 1 - SDK Implementation

  1. Drag and drop "prism_ios_fingerprint_sdk.xcframework" into your Project download
  2. Project Target->General ->Frameworks,embedded content -> Framework should be “Embed & Sign”
  3. "import prism_ios_fingerprint_sdk" in your UIViewcontroller
  4. Info.plist ->Must need
    • “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.

var entrypoint:BureauAPI?

// Initialize BureauAPI 

entrypoint = BureauAPI(clientID: "***CLIENT ID ***" , environment: .production, sessionID: "*** SESSION ID ***")  

// clientID  -> Bureau Merchant Id
// environment -> .stage, .production, .sandbox
// sessionID -> unique String value
//refVC -> self 

entrypoint?.setUserID("***USER ID***") // set userid
entrypoint?.fingerprintDelegate = self // Assign the delegate

entrypoint?.submit() // submitData to bureau backend 

Note: Client ID and Session ID should be mandatory and 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 DeviceFingerPrintVC : 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 is a must for Device Intelligence.

Please find below the link to the API documentation:

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": "Bengaluru",
    "country": "India",
    "latitude": 51.5207,
    "longitude": -0.1550,
    "region": ""
  },
  "IP": "151.255.153.38",
  "IPLocation": {
    "city": "Abha",
    "country": "Saudi Arabia",
    "latitude": 51.5207,
    "longitude": -0.1550,
    "region": "Ind"
  },
  "IPSecurity": {
    "VPN": false,
    "is_crawler": false,
    "is_proxy": false,
    "is_tor": false,
    "threat_level": "LOW"
  },
  "IPType": "v4",
  "OS": "ios",
  "accessibilityEnabled": false,
  "appStoreInstall": false,
  "confidenceScore": 100,
  "createdAt": 1706654705545,
  "debuggable": false,
  "developerMode": false,
  "emulator": false,
  "fingerprint": "63ac504c-d395-46be-ab9a-f79ebc414bc8",
  "firstSeenDays": 5,
  "fridaDetected": false,
  "jailbreak": false,
  "merchantId": "org_ro2da2zNHg",
  "mockgps": false,
  "model": "D53gAP",
  "networkInformation": {
    "ipType": "HOME",
    "isp": "Jon Doe Telecom Company"
  },
  "package": "com.XXX.udel",
  "remoteDesktop": false,
  "requestId": "SqzovEj5BcwEVIw=",
  "riskCauses": null,
  "riskLevel": "LOW",
  "riskScore": 56.97,
  "sessionId": "E7150586-44D8-461F-A014-23D6A82110B6",
  "statusCode": 200,
  "timestamp": 1707147217344,
  "userId": "15572239",
  "voiceCallDetected": false
}
{
    "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

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.

KeyDescription
GPSLocation(city, country, latitude, longitude, region)GPS Based location of the user, 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.
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.
userIdThe userID that was sent as part of the request body.
jailbreakFlag to indicate if the device is jain broken.
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.
remoteDesktopFlag to indicate whether a remote desktop monitoring session is detected.
developerModeBoolean flag to indicate if developer mode is turned on
accessibilityModeBoolean flag to indicate if accessibility services are turned on
fridaDetectedBoolean status of the frida server being attached to the app
appStoreInstallBoolean status of the source of the app installation
sessionIdThe session identifier, that was used to invoke the SDK.
createdAtThe time at which the request was made.
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.
confidenceScoreThe confidence score of the generated fingerprint.

Go live Checklist