- Print
- DarkLight
Like our Javascript Tags Deployment, Darwinium's SDK is designed to fit into your existing implementation without the need to call 3rd party APIs from directly within your app - simply append collected profiling data as a header, Dwn-Profiling
to an existing request, and have this processed by an edge step infront of an API, or call the API with this data from your backend.
Option 1: Add a step to your API endpoint to process SDK profiling data automatically
Option 2: Manually process profiling data using a backend call
Initial configuration & Repository Access
Darwinium's iOS and Android SDKs are kept up-to-date using modern package management tools (git, artifactory).
To access this, you will require an API Token. A token can be obtained by going to the Darwinium Portal and clicking Preferences:
Once in the preferences screen, click SDK Access and then click Generate Token
This will provide a username (the same as the username used to access Darwinium) and token. Note these down as they will only appear once.
Setup - Android
Darwinium's Android SDK currently works with API level 33 and above (Android 10.0) per Play Store Guidelines. If you require support for older versions of Android, please contact our team on support@darwinium.com
This guide assumes your project uses Gradle and Kotlin as a language. It will work with Java implementations, although slightly different implementation will be required (beyond the scope of this guide).
Add the Darwinium maven repo
Open settings.gradle
in your project's root, and add the Darwinium maven repo to the dependencyResolutionManagement
section of the file. An example of this full section is shown below:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
// Darwinium Maven repository. Variables stored in gradle.properties
maven {
name = 'DarwiniumMavenRepo'
url = "${dwn_maven_url}"
credentials {
username = "${dwn_maven_user}"
password = "${dwn_maven_pwd}"
}
}
}
}
Next, add your credentials (username, API token) to gradle.properties
:
dwn_maven_url=https://packages.darwinium.com/artifactory/dwn-maven/
dwn_maven_user=<your email address>
dwn_maven_pwd=<API Token>
Add the Darwinium SDK as a dependency
Open build.gradle
in your project's root, and add the following under the dependencies
section:
implementation 'com.darwinium:android_sdk:1.14.6+'
Add profiling biolerplate
import the Darwinium SDK using:
import com.darwinium.dwn_sdk.DwnProfilingSDK
Typicially, the Darwinium SDK is invoked in an activity; for example:
class MainActivity : ComponentActivity() {
private val dwnProfiling = DwnProfilingSDK(
appActivity = this,
profilingStart = false,
config = hashMapOf("debugging" to false, "MaxSwipes" to 7, "MaxSensorCount" to 120)
)
// other code...
Start profiling
It usually makes sense to configure and start profiling on your activity's onCreate()
method. For example:
override fun onCreate(savedInstanceState: Bundle?) {
dwnProfiling.start()
super.onCreate(savedInstanceState)
// ...other view logic
setContentView(R.layout.example_view)
Adding fields for Behavioral Biometrics
Darwinium can profile behavioral biometrics for android Text Views. This is done using the .addTextView(textViewRef, darwiniumContext)
function. For example:
val nameInput = this.findViewById<TextView>(R.id.txtName)
val passwordInput = this.findViewById<TextView>(R.id.txtPassword)
dwnProfiling.addTextView(nameInput, "USER_NAME")
dwnProfiling.addTextView(passwordInput, "PASSWORD")
Collecting/sending profiling data
You will want to provide the intelligence gathered by SDK profiling when an action such when a login API request to your backend occurs. The simplest way of achieving this is to add profile data as a header, Dwn-Profiling
, to your existing request. Consider the following example:
//you can collect profiling at any time.
//this is a base64 encoded string
val fpData = dwnProfiling.collect()
val request = Request.Builder()
.url("https://path/to/your/api")
.post(body)
.addHeader("Dwn-Profiling", fpData)
.build()
Permissions
Darwinium's android SDK is able to use a number of extended permissions to obtain profiling data. These can be edited in AndroidManifest.xml
:
<!-- provides extensive details on phone sim details under profiling.android.sim_info -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_NUMBERS" />
<!-- provides fine-grained GPS insights in profiling.android.location -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- provides WIFI profiling insights in profiling.android.wifi -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- provides connection insights in profiling.android.connection -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
You can delegate the process of requesting permissions to the SDK using the combination of dwnProfiling.requestPermissions()
and an onRequestPermissionsResult
handler in your activity similar to the following:
override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String?>, grantResults: IntArray) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults)
dwnProfiling.processPermissions(requestCode, grantResults)
}
Setup - iOS
Add the Darwinium SDK as a package dependency
The SDK supports both Swift Package Manager (SPM) and CocoaPods.
For SPM, add Darwinium sdk by using the following URL
https://packages.darwinium.com/sdk/dwn_ios_sdk.git
For CocoaPods, add the following lines in the Podfile
pod 'dwn_ios_sdk', :git => 'https://packages.darwinium.com/sdk/dwn_ios_sdk.git', :tag => '<version>'
Darwinium SDK depends on SwiftProtobuf which will be automatically loaded when dwn_ios_sdk loaded
Example: Adding using XCode
Using XCode, Navigate to your project settings and select the Package Dependencies tab:
If using SPM for example, click the "+" button. In the top right-hand side enter the following package URL:
https://packages.darwinium.com/sdk/dwn_ios_sdk.git
You will be prompted for a username and password. Enter the details collected in Initial configuration & Repository Access.
This will provide a package called dwn_ios_sdk. Add this as a dependency, and ensure that your project is selected as a target.
Add profiling boilerplate
Identify a view that you wish to have profiled, and add the following:
import DwnSDK_Framework
Start Profiling
In your view code, create and start your profiling. For example:
struct ContentView: View {
//create an instance of the sdk
private let sdk: DwnProfilingSDK
@StateObject var locationManager = LocationManager()
init () {
//initialize and start profiling
let config: [String: Any] = ["Max Swipes":5, "Max Sensor Count": "150", "SensorCheckInSeconds": 0.1]
sdk = DwnProfilingSDK()
sdk.setConfig(config)
sdk.start()
Adding Fields for Behavioral Biometrics
Darwinium can profile behavioral biometrics for android Text Views. This is done using the .addTextField(placeholder, darwiniumContext)
function. For example:
sdk.addTextField(placeholder: "User name", context: "user_name")
sdk.addTextField(placeholder: "Password", context: "password")
Collecting / Sending profiling data
You will want to provide the intelligence gathered by SDK profiling when an action such when a login API request to your backend occurs. The simplest way of achieving this is to add profile data as a header, Dwn-Profiling
, to your existing request. Consider the following example:
let fpData = sdk.getDwnProfiling()
var request = URLRequest(url: URL(string: "https://path/to/your/api")!,timeoutInterval: Double.infinity)
//append profiling as a header to your existing request
request.addValue(fpData, forHTTPHeaderField: "Dwn-Profiling")
Permissions
Darwinium's iOS profiling is greatly enhanced by enabling AppTrackingTransparency
and CoreLocation (GPS). We do not explicitly request these permissions ourselves, and they must be manually requested through code in your views/ changes to your Info.plist
.
Generate Event including the Profiling Data
After collecting profiling data, the Darwinium risk engine should be invoked. That decodes the profileBlob and returns risk assessment about the user action.
If using an Edge Deployment to generate events, adding the profileBlob to a header dwn-profiling on the existing request to your back end is sufficient. The Darwinium Edge worker will extract the profiling data from the request directly.
If using API to generate events, the profileBlob should be sent to your backend and then included as header dwn-profiling on the API call to Darwinium.
See:
Size of largest profileBlobs typically 4-5kb
- May need to increase permitted header length granted to the request
- If a form POST, dwn-profiling can be included in request body
- The more behavioural biometrics fields mapped, the larger the profileBlob size
Unlike their web counterparts, mobile APIs do not typically leverage session cookies, which are used by Darwinium to join steps as part of a journey. In order to join steps using SDK, you will need to specify a primary_session_tie
value. This is a unique identifier that is re-used for each subsequent call. We recommend using a value such as an email address or other value from your backend
Example Projects
Barebones boilerplate projects are available for both Android and iOS using our git repo. Follow the Initial Configuration and Repository Access guide above to obtain an api token, and checkout the projects below:
Android
git clone https://packages.darwinium.com/sdk/dwn_android_sdk_sample.git
iOS
git clone https://packages.darwinium.com/sdk/dwn_ios_sdk_sample.git