Android v1.0.1.x

val config = TSBehavioralConfig(
    appId = "your-app-id",
    baseUrl = "https://your-base-url/api",
    metadataConfig = MetaDataCollectionConfig(intervalMillis = 2000L),
)

val config = TSBehavioralConfig(
    appId = "your-app-id",
    baseUrl = "https://your-base-url/api",
    bootstrapKeyId = "key-id-issued-by-trustvision",
    bootstrapPublicKey = BOOTSTRAP_PUBLIC_KEY, // compiled into your app, see below
    metadataConfig = MetaDataCollectionConfig(intervalMillis = 2000L),
)

// Implicitly ended the previous session and opened a new one
TSBehavioralSDK.startCollect(context)

// Close the running session (if any) and open a new one in one call
val previous: TSFinalizeResult? = TSBehavioralSDK.switchJourney(context)

// ...or, equivalently, in two calls
TSBehavioralSDK.finalizeCollect()
TSBehavioralSDK.startCollect(context)

TSBehavioralSDK.startCollect(context)
TSBehavioralSDK.updateScreenTransition("main_screen")

TSBehavioralSDK.updateScreenTransition("main_screen") // from onResume, before or after startCollect
TSBehavioralSDK.startCollect(context)

your-project/
  repo/
    com/
      trustingsocial/
        behaviors/
          <version>/
            behaviors-<version>.aar
            behaviors-<version>.pom
            behaviors-<version>.module

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("${rootProject.projectDir}/repo")
        }
    }
}

dependencies {
    implementation("com.trustingsocial:behaviors:<version>")
}

object TSMetadataCollector {
    fun start(
        context: Context,
        config: MetaDataCollectionConfig,
        appId: String,
        excludeTypes: Set<MetaDataType> = emptySet(),
        logger: SdkLogger = LogcatSdkLogger(),
        onRecord: (Map<String, Any>) -> Unit,
    )

    fun stop()
}

TSMetadataCollector.start(
    context = this, // the current Activity
    config = MetaDataCollectionConfig(intervalMillis = 5_000L),
    appId = "your-app-id",
) { record ->
    // forward `record` to your own upload / event-log pipeline
}

// ...
TSMetadataCollector.stop()

import com.ts.behaviorsdk.external.TSBehavioralConfig
import com.ts.behaviorsdk.external.KeyboardConfig
import com.ts.behaviorsdk.external.TouchConfig
import com.ts.behaviorsdk.external.RetryConfig
import com.ts.behaviorsdk.devicemetadata.MetaDataCollectionConfig
import com.ts.behaviorsdk.sensor.SensorConfig
import com.ts.behaviorsdk.data.SensorType

val config = TSBehavioralConfig(
    appId = "your-app-id",                         // Your app's package name / application ID
    baseUrl = "https://your-base-url/api",         // Provided by TrustVision
    bootstrapKeyId = "key-id-issued-by-trustvision",
    bootstrapPublicKey = BOOTSTRAP_PUBLIC_KEY,     // Provided by TrustVision, compiled into your app
    metadataConfig = MetaDataCollectionConfig(
        intervalMillis = 2000L,
        enabled = true,
    ),
    uploadBlockSize = 10,
    sensorConfig = SensorConfig(
        samplingIntervalMs = 20L,
        sensorTypes = listOf(
            SensorType.Gyroscope,
            SensorType.Magnetometer,
            SensorType.Accelerometer,
            SensorType.Light,
        ),
        enabled = true,
    ),
    keyboardConfig = KeyboardConfig(
        trackRawText = false,
        enabled = true,
    ),
    touchConfig = TouchConfig(
        enabled = true,
    ),
    screenTransitionBlockSize = 1,
    appStateBlockSize = 1,
    batchExtra = mapOf("env" to "production"),
    retryConfig = RetryConfig(
        enabled = true,
        maxRetries = 2,
        retryDelayMs = 1000L,
        maxDelayMs = 5000L,
        maxRetryAttempts = 3,
        maxRetryStorageItems = 50,
        finalFlushTimeoutMs = 10000L,
        retryItemDelayMs = 500L,
    ),
)

val config = TSBehavioralConfig(
    appId = "com.example.app",
    baseUrl = "https://api.trustingsocial.com",
    bootstrapKeyId = "key-id-issued-by-trustvision",
    bootstrapPublicKey = BOOTSTRAP_PUBLIC_KEY,
    metadataConfig = MetaDataCollectionConfig(intervalMillis = 2000),
    sslCertificates = listOf(R.raw.my_server_cert),
)

suspend fun initialize(context: Context, config: TSBehavioralConfig): TSDeviceInitInfo

lifecycleScope.launch {
    try {
        val initInfo = TSBehavioralSDK.initialize(applicationContext, config)

        Log.d("BehavioralSDK", "Device ID: ${initInfo.deviceId}")
        Log.d("BehavioralSDK", "Already registered: ${initInfo.isRegistered}")
    } catch (e: TSSessionError.InvalidConfiguration) {
        Log.e("BehavioralSDK", "Invalid ${e.field}: ${e.reason}")
    } catch (e: TSSessionError.KeystoreError) {
        Log.e("BehavioralSDK", "Keystore error: ${e.message}")
    } catch (e: TSSessionError.CryptoError) {
        Log.e("BehavioralSDK", "Crypto error: ${e.message}")
    }
}

suspend fun setCusUserId(cusUserId: String?)

suspend fun getRegistrationStatus(): TSRegistrationStatus

suspend fun markDeviceRegistered(
    isRegistered: Boolean,
    customerUserDeviceId: String,
    cusUserId: String? = null,
)

lifecycleScope.launch {
    TSBehavioralSDK.initialize(applicationContext, config)
    TSBehavioralSDK.setCusUserId("your-user-id")

    when (val status = TSBehavioralSDK.getRegistrationStatus()) {
        is TSRegistrationStatus.Required -> {
            try {
                // Your backend calls TrustVision API: POST /v1/register_device
                val userDeviceId = yourBackend.registerDevice(
                    deviceId = status.deviceId,
                    keyPairId = status.bootstrapKeyId,
                    devicePublicKey = status.encryptedDevicePublicKeyPayload,
                    encryptedSecretKey = status.encryptedSecretKey,
                    cusUserId = status.cusUserId,
                )
                TSBehavioralSDK.markDeviceRegistered(
                    isRegistered = true,
                    customerUserDeviceId = userDeviceId,
                    cusUserId = status.cusUserId,
                )
            } catch (e: YourHttpException) {
                TSBehavioralSDK.reportRegistrationFailed(e.statusCode, status.cusUserId)
                return@launch
            }
        }
        TSRegistrationStatus.CoolingDown -> return@launch // try again later
        TSRegistrationStatus.Registered -> Unit
    }

    TSBehavioralSDK.startCollect(this@MainActivity)
}

suspend fun reportRegistrationFailed(statusCode: Int?, cusUserId: String? = null)

suspend fun startCollect(context: Context? = null)

lifecycleScope.launch {
    try {
        TSBehavioralSDK.startCollect(this@MainActivity)
        Log.d("BehavioralSDK", "Collection started")
    } catch (e: TSSessionError.DeviceNotRegistered) {
        Log.e("BehavioralSDK", "Register device first")
    } catch (e: TSSessionError.NetworkError) {
        Log.e("BehavioralSDK", "Network error: ${e.httpCode} ${e.message}")
    }
}

suspend fun switchJourney(context: Context? = null): TSFinalizeResult?

// Start each flow with switchJourney so an abandoned flow is not merged into the next one
lifecycleScope.launch {
    try {
        val previous = TSBehavioralSDK.switchJourney(this@MainActivity)
        previous?.challengeId?.let { yourBackend.computeBehaviorScore(it) }
    } catch (e: TSSessionError) {
        Log.e("BehavioralSDK", "Switch error: ${e.name} - ${e.message}")
    }
}

fun updateScreenTransition(value: String)
fun updateScreenTransition(value: ScreenTransitionCollectorListener)

// Report the screen; it is replayed into the session when startCollect() opens it
TSBehavioralSDK.updateScreenTransition("main_screen")
TSBehavioralSDK.startCollect(context)

// Then call again on every screen navigation
TSBehavioralSDK.updateScreenTransition("payment_screen")

class PaymentActivity : AppCompatActivity(), ScreenTransitionCollectorListener {

    override fun getScreenName() = "payment_screen"

    override fun onResume() {
        super.onResume()
        TSBehavioralSDK.updateScreenTransition(this)
    }
}

suspend fun startKeyboardTracking(activity: Activity)
suspend fun startKeyboardTracking(view: View)
suspend fun startKeyboardTracking(editText: EditText)

// In your Activity's onResume — tracks all EditTexts
override fun onResume() {
    super.onResume()
    lifecycleScope.launch {
        TSBehavioralSDK.startKeyboardTracking(this@MyActivity)
    }
}

// In a Fragment — tracks all EditTexts in the fragment's view
lifecycleScope.launch {
    TSBehavioralSDK.startKeyboardTracking(fragment.requireView())
}

// Track a specific EditText
lifecycleScope.launch {
    TSBehavioralSDK.startKeyboardTracking(emailEditText)
}

suspend fun stopKeyboardTracking()
suspend fun stopKeyboardTracking(editText: EditText)

lifecycleScope.launch {
    TSBehavioralSDK.stopKeyboardTracking()
}

fun addKeyboardTrackingData(data: KeyboardData)

TSBehavioralSDK.addKeyboardTrackingData(
    KeyboardData(
        timestamp = System.currentTimeMillis(),
        type = KeyboardDataType.LowerText,
        textLength = 5,
        viewId = "email_field",
    )
)

fun trackTextChange(oldText: String, newText: String, viewId: String)

var email by remember { mutableStateOf("") }

TextField(
    value = email,
    onValueChange = { newValue ->
        TSBehavioralSDK.trackTextChange(
            oldText = email,
            newText = newValue,
            viewId = "email_field",
        )
        email = newValue
    },
    label = { Text("Email") }
)

fun trackTouchEvent(event: MotionEvent, activity: WeakReference<Activity>)
fun trackTouchEvent(event: PointerEventDto, activity: WeakReference<Activity>)

class MyActivity : AppCompatActivity() {

    override fun dispatchTouchEvent(event: MotionEvent): Boolean {
        TSBehavioralSDK.trackTouchEvent(event, WeakReference(this))
        return super.dispatchTouchEvent(event)
    }
}

TSBehavioralSDK.trackTouchEvent(
    PointerEventDto(
        actionName = "ACTION_DOWN",
        actionMasked = MotionEvent.ACTION_DOWN,
        pointerId = 0,
        globalX = 150.0,
        globalY = 300.0,
    ),
    WeakReference(this)
)

suspend fun finalizeCollect(): TSFinalizeResult

lifecycleScope.launch {
    try {
        val result = TSBehavioralSDK.finalizeCollect()

        Log.d("BehavioralSDK", "Challenge ID: ${result.challengeId}")
        Log.d("BehavioralSDK", "Last seq: ${result.lastSeq}")

        if (result.droppedBatchCount > 0) {
            Log.w(
                "BehavioralSDK",
                "Dropped ${result.droppedBatchCount} batches. Last error: ${result.lastUploadError}",
            )
        }

        // Send challengeId to your backend for scoring
        result.challengeId?.let { yourBackend.computeBehaviorScore(it) }
    } catch (e: TSSessionError) {
        Log.e("BehavioralSDK", "Finalize error: ${e.name} - ${e.message}")
    }
}

suspend fun stopCollect(): TSFinalizeResult

lifecycleScope.launch {
    try {
        val result = TSBehavioralSDK.stopCollect()
        Log.d("BehavioralSDK", "Stopped. Challenge ID: ${result.challengeId}")
    } catch (e: TSSessionError) {
        Log.e("BehavioralSDK", "Stop error: ${e.message}")
    }
}

suspend fun clearUser()

lifecycleScope.launch {
    val result = TSBehavioralSDK.finalizeCollect()
    result.challengeId?.let { yourBackend.computeBehaviorScore(it) }
    TSBehavioralSDK.clearUser()
}

suspend fun clearDeviceIdentity()

lifecycleScope.launch {
    try {
        TSBehavioralSDK.clearDeviceIdentity()
        Log.d("BehavioralSDK", "Device identity cleared")
        // Must call initialize() again before using SDK
    } catch (e: TSSessionError) {
        Log.e("BehavioralSDK", "Clear error: ${e.message}")
    }
}

fun getEnabledFlag(context: Context): Boolean?
fun setEnabledFlag(context: Context, enabled: Boolean?)

<exclude domain="sharedpref" path="behavior_sdk_flags.xml"/>

// On launch
if (TSBehavioralSDK.getEnabledFlag(applicationContext) != false) {
    lifecycleScope.launch { TSBehavioralSDK.initialize(applicationContext, config) }
}

// When your remote config answers — applies from the next launch
TSBehavioralSDK.setEnabledFlag(applicationContext, remoteConfig.behavioralEnabled)

try {
    TSBehavioralSDK.startCollect(context)
} catch (e: TSSessionError.DeviceNotRegistered) {
    // Server says the device is not registered — register via your backend first
} catch (e: TSSessionError.SslPinningError) {
    // Certificate pinning failed — the server cert did not match a pinned certificate
} catch (e: TSSessionError.NetworkError) {
    // Network issue: check e.httpCode, e.serverErrorCode, and e.message
} catch (e: TSSessionError) {
    // Any other SDK error: use e.name and e.message
}

import android.os.Bundle
import android.util.Log
import android.view.MotionEvent
import androidx.appcompat.app.AppCompatActivity
import androidx.lifecycle.lifecycleScope
import com.ts.behaviorsdk.TSBehavioralSDK
import com.ts.behaviorsdk.external.TSBehavioralConfig
import com.ts.behaviorsdk.external.TSRegistrationStatus
import com.ts.behaviorsdk.external.TSSessionError
import com.ts.behaviorsdk.devicemetadata.MetaDataCollectionConfig
import com.ts.behaviorsdk.sensor.SensorConfig
import com.ts.behaviorsdk.external.KeyboardConfig
import com.ts.behaviorsdk.external.TouchConfig
import com.ts.behaviorsdk.data.SensorType
import kotlinx.coroutines.launch
import java.lang.ref.WeakReference

class BehavioralActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_behavioral)

        lifecycleScope.launch {
            try {
                // 1. Configure SDK
                val config = TSBehavioralConfig(
                    appId = "your-app-id",
                    baseUrl = "https://your-base-url/api",
                    bootstrapKeyId = "key-id-issued-by-trustvision",
                    bootstrapPublicKey = BOOTSTRAP_PUBLIC_KEY,
                    metadataConfig = MetaDataCollectionConfig(
                        intervalMillis = 2000L,
                    ),
                    sensorConfig = SensorConfig(
                        samplingIntervalMs = 20L,
                        sensorTypes = listOf(
                            SensorType.Gyroscope,
                            SensorType.Magnetometer,
                            SensorType.Accelerometer,
                            SensorType.Light,
                        ),
                    ),
                    keyboardConfig = KeyboardConfig(
                        trackRawText = false,
                    ),
                    touchConfig = TouchConfig(
                        enabled = true,
                    ),
                )

                // 2. Initialize SDK
                TSBehavioralSDK.initialize(this@BehavioralActivity, config)

                // 3. Tell the SDK who signed in
                TSBehavioralSDK.setCusUserId("your-user-id")

                // 4. Register device if needed
                when (val status = TSBehavioralSDK.getRegistrationStatus()) {
                    is TSRegistrationStatus.Required -> {
                        // Your backend calls:
                        //   POST /v1/register_device
                        //   Body: {
                        //     "device_id": status.deviceId,
                        //     "key_pair_id": status.bootstrapKeyId,
                        //     "device_public_key": status.encryptedDevicePublicKeyPayload,
                        //     "encrypted_secret_key": status.encryptedSecretKey,
                        //     "cus_user_id": status.cusUserId,
                        //     "protocol": "encrypted"
                        //   }
                        //   Response: { "data": { "customer_user_device_id": "..." } }
                        val userDeviceId = try {
                            yourBackend.registerDevice(
                                deviceId = status.deviceId,
                                keyPairId = status.bootstrapKeyId,
                                devicePublicKey = status.encryptedDevicePublicKeyPayload,
                                encryptedSecretKey = status.encryptedSecretKey,
                                cusUserId = status.cusUserId,
                            )
                        } catch (e: YourHttpException) {
                            TSBehavioralSDK.reportRegistrationFailed(e.statusCode, status.cusUserId)
                            return@launch
                        }

                        TSBehavioralSDK.markDeviceRegistered(
                            isRegistered = true,
                            customerUserDeviceId = userDeviceId,
                            cusUserId = status.cusUserId,
                        )
                    }
                    TSRegistrationStatus.CoolingDown -> return@launch
                    TSRegistrationStatus.Registered -> Unit
                }

                // 5. Start data collection (idempotent)
                TSBehavioralSDK.startCollect(this@BehavioralActivity)
            } catch (e: TSSessionError) {
                Log.e("BehavioralSDK", "Error [${e.name}]: ${e.message}")
            }
        }
    }

    override fun onResume() {
        super.onResume()
        // 6. Record the screen — remembered and replayed if the session is not open yet
        TSBehavioralSDK.updateScreenTransition("main_screen")

        // 7. Start keyboard tracking — remembered and attached when the session opens
        lifecycleScope.launch {
            TSBehavioralSDK.startKeyboardTracking(this@BehavioralActivity)
        }
    }

    // 8. Track touch events via dispatchTouchEvent
    override fun dispatchTouchEvent(event: MotionEvent): Boolean {
        TSBehavioralSDK.trackTouchEvent(event, WeakReference(this))
        return super.dispatchTouchEvent(event)
    }

    // 9. Track screen transitions on navigation
    private fun navigateToPayment() {
        TSBehavioralSDK.updateScreenTransition("payment_screen")
        // ... navigate to payment screen
    }

    // 10. Finalize when the flow is complete
    private fun onFlowComplete() {
        lifecycleScope.launch {
            try {
                val result = TSBehavioralSDK.finalizeCollect()

                // Send challengeId to your backend to compute behavior score:
                //   POST /v1/behavior/score
                //   Body: { "challenge_id": result.challengeId }
                result.challengeId?.let { yourBackend.computeBehaviorScore(it) }

            } catch (e: TSSessionError) {
                Log.e("BehavioralSDK", "Finalize error: ${e.message}")
            }
        }
    }

    // 11. Forget the user on logout (device identity is kept)
    private fun onLogout() {
        lifecycleScope.launch {
            TSBehavioralSDK.finalizeCollect()
            TSBehavioralSDK.clearUser()
        }
    }
}

POST {baseUrl}/v1/register_device
Content-Type: application/json
Authorization: TV {accessKeyId}:{signature}
X-TV-Timestamp: {ISO8601 UTC timestamp}

{
  "device_id": "from status.deviceId",
  "key_pair_id": "from status.bootstrapKeyId",
  "device_public_key": "from status.encryptedDevicePublicKeyPayload",
  "encrypted_secret_key": "from status.encryptedSecretKey",
  "cus_user_id": "from status.cusUserId",
  "protocol": "encrypted"
}

{
  "data": {
    "customer_user_device_id": "server-assigned-id"
  }
}

{METHOD}\n{PATH}\n{TIMESTAMP}

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.request.*
import io.ktor.http.*
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import java.time.ZoneId
import java.time.ZonedDateTime
import java.time.format.DateTimeFormatter
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import android.util.Base64

@Serializable
data class RegisterDeviceRequest(
    @SerialName("key_pair_id") val keyPairId: String,
    @SerialName("device_public_key") val devicePublicKey: String,
    @SerialName("encrypted_secret_key") val encryptedSecretKey: String,
    @SerialName("cus_user_id") val cusUserId: String,
    @SerialName("device_id") val deviceId: String,
    val protocol: String = "encrypted",
)

@Serializable
data class RegisterDeviceResponse(
    val data: Data,
) {
    @Serializable
    data class Data(
        @SerialName("customer_user_device_id") val customerUserDeviceId: String,
    )
}

// --- API Client ---

suspend fun registerDevice(
    httpClient: HttpClient,
    request: RegisterDeviceRequest,
): String {
    val response: RegisterDeviceResponse = httpClient
        .post("/api/v1/register_device") {
            contentType(ContentType.Application.Json)
            setBody(request)
        }.body()
    return response.data.customerUserDeviceId
}

// --- HMAC-SHA256 Signing ---

private fun createSignature(
    method: String,
    path: String,
    accessKeySecret: String,
    timestamp: String,
): String {
    val stringToSign = "$method\n$path\n$timestamp"
    val sha256Hmac = Mac.getInstance("HmacSHA256")
    val secretKeySpec = SecretKeySpec(accessKeySecret.toByteArray(), "HmacSHA256")
    sha256Hmac.init(secretKeySpec)
    return Base64.encodeToString(
        sha256Hmac.doFinal(stringToSign.toByteArray()),
        Base64.NO_WRAP,
    )
}

// --- Usage with Ktor Auth Plugin ---

val formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ")
val timestamp = ZonedDateTime.now(ZoneId.of("UTC")).format(formatter)
val method = "POST"
val path = "/v1/register_device"
val signature = createSignature(method, path, accessKeySecret, timestamp)

// Set headers on request:
// "X-TV-Timestamp" to timestamp
// "Authorization" to "TV $accessKeyId:$signature"

// 1. Initialize SDK and set the signed-in user
TSBehavioralSDK.initialize(context, config)
TSBehavioralSDK.setCusUserId("your-user-id")

// 2. Register device via your backend when the SDK says so
val status = TSBehavioralSDK.getRegistrationStatus()
if (status is TSRegistrationStatus.Required) {
    val request = RegisterDeviceRequest(
        keyPairId = status.bootstrapKeyId,
        devicePublicKey = status.encryptedDevicePublicKeyPayload,
        encryptedSecretKey = status.encryptedSecretKey,
        cusUserId = status.cusUserId,
        deviceId = status.deviceId,
    )
    val customerUserDeviceId = try {
        registerDevice(httpClient, request)
    } catch (e: ResponseException) {
        // 3a. The backend rejected it: start the 10-minute cooldown
        TSBehavioralSDK.reportRegistrationFailed(e.response.status.value, status.cusUserId)
        return
    }

    // 3b. Mark device as registered in SDK
    TSBehavioralSDK.markDeviceRegistered(
        isRegistered = true,
        customerUserDeviceId = customerUserDeviceId,
        cusUserId = status.cusUserId,
    )
}

// 4. Now you can start collecting (skip while the status is CoolingDown)
if (status !is TSRegistrationStatus.CoolingDown) {
    TSBehavioralSDK.startCollect(context)
}