Mobile SDK Deployment
  • 19 Aug 2024
  • 6 Minutes to read
  • Contributors
  • Dark
    Light

Mobile SDK Deployment

  • Dark
    Light

Article summary

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.

image.png
Option 1: Add a step to your API endpoint to process SDK profiling data automatically

image.png
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:

image.png
Once in the preferences screen, click SDK Access and then click Generate Token
image.png
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.
image.png

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:
Screenshot 2023-12-11 at 2.51.06 PM.png

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:

Profile Blob size

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
Tracking Journeys with the SDK

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

Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.
ESC

Eddy AI, facilitating knowledge discovery through conversational intelligence