# Android SDK quick start
This guide describes how to quickly integrate Fraud Prevention into your Android application to get started. This includes both the client-side integration, as well as the backend API integration required to complete the flow.
Note
Client-side integrations are recommended for POCs and testing. For production environments, consider implementing [Backend integration](/guides/risk/quick_start_backendapi). Learn more about integration options: [Client-side integration vs Backend integration](/guides/risk/integration_clientside_vs_backend).
## How it works
The flow starts with the user navigating to the Android app (1). The SDK gets initialized and starts sending telemetry to Mosaic (2). When a user performs an action, for example, clicks a login button (3), the SDK triggers an action event (4) and obtains an action token (5) which then forwards to the backend (6). Having received an action token, the application backend uses it to fetch recommendation from Mosaic (7 & 8) and instructs the client to act accordingly (9) in order to complete the login procedure (10). Upon successful login, the client sets the user (11).
## Requirements
- Android 5+ (API level 21+)
## Step 1: Get client credentials
div
div
Admin Portal
Client credentials are used to identify your app and generate access tokens for authorizing Mosaic requests. To obtain them, you'll need to create an application in the [Admin Portal](https://portal.transmitsecurity.io/) (if you don’t have one yet).
1. From **Applications**, click **Add application**.
2. Add the friendly application name to display in the Admin Portal.
3. Add an OIDC client, specify the client secret as an authentication method, and your website URL as a redirect URI (e.g., `https://your-domain.com`).
Note
These fields are required for all Mosaic apps, but won’t be used for Fraud Prevention.
1. Click **Add** to create your application. This will automatically generate your client credentials.
## Step 2: Add SDK to project
div
div
Client
Add the following lines in the shared build.gradle file ("allprojects" scope):
```groovy
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
maven {
url('https://transmit.jfrog.io/artifactory/transmit-security-gradle-release-local/')
}
mavenCentral()
google()
}
}
```
Add the following in the module build.gradle file (project scope):
```groovy
dependencies {
implementation("com.ts.sdk:accountprotection:2.2.+")
}
```
## Step 3: Initialize SDK
div
div
Client
Start monitoring your end-user risk levels by initializing and configuring the SDK.
details
summary
b
Initialize using strings.xml configuration (recommended)
To do this, update the strings.xml file in your Application with the following content. The `[CLIENT_ID]` should be replaced with your client ID from step 1.
```xml
"CLIENT_ID"
https://api.transmitsecurity.io/
```
Note
The SDK can be configured to work with different cluster by setting a third initialization parameter to `baseUrl : 'https://api.transmitsecurity.io/risk-collect/'` for US, or `'https://api.eu.transmitsecurity.io/'` for EU, `baseUrl : 'https://api.ca.transmitsecurity.io/'` for Canada, or `baseUrl : 'https://api.au.transmitsecurity.io/'` for Australia, or `baseUrl : 'https://'` if you're using one.
Add the code below to your Application class.
Kotlin
```kotlin
class Application : Application() {
override fun onCreate() {
super.onCreate()
TSAccountProtection.initializeSDK(this)
}
}
```
Java
```java
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
TSAccountProtection.initializeSDK(this);
}
}
```
details
summary
b
Initialize using SDK parameters
Add the code below to your Application Class. The `[CLIENT_ID]` should be replaced with your client ID from step 1.
Kotlin
```kotlin
class Application : Application() {
override fun onCreate() {
super.onCreate()
TSAccountProtection.initialize(this, "CLIENT_ID")
}
}
```
Java
```java
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
TSAccountProtection.initialize(this, "CLIENT_ID");
}
}
```
Note
The SDK can be configured to work with different cluster by setting a third initialization parameter to `baseUrl : 'https://api.transmitsecurity.io/risk-collect/'` for US, or `'https://api.eu.transmitsecurity.io/'` for EU, `baseUrl : 'https://api.ca.transmitsecurity.io/'` for Canada, or `baseUrl : 'https://api.au.transmitsecurity.io/'` for Australia, , or `baseUrl : 'https://'` if you're using one.
SDK session
Start an SDK session and obtain a device session token after SDK initialization and prior to triggering events, and persist it on your backend. This step is optional for client-side integration but **strongly recommended** as it allows to transition to the [backend integration](/guides/risk/quick_start_backendapi)—a device session token is needed to trigger events from the backend and binds user's interactions to their device.
```kotlin
TSAccountProtection.getSessionToken(object : ISessionTokenCallback {
override fun onSessionToken(sessionToken: String) {
}
})
```
## Step 4: Trigger actions
div
div
Client
To obtain risk recommendations for sensitive actions, your application should report these actions using the SDK. To do this, add the code below to relevant user interactions (e.g., the Login button `click` event handler). Replace `[ACTION_TYPE]` with the appropriate action type from our [list of actions](/guides/risk/recommendations#action-types).
`ActionEventOptions` and `TransactionData` objects are optional and can be set to null. To improve Fraud Prevention, optionally pass the correlation ID, and claimed user ID (for users that haven't authenticated yet).
To report precise device location, add `locationConfig` to the call (the user has to consent to sharing location in advance, see [Track geolocation](/guides/risk/report_geolocation)).
`customAttributes` is an optional object which add context to an action but must match the schema defined in the Portal. Invalid attributes are ignored (see [Custom Attributes](/guides/risk/action-attributes))
This call returns `actionToken`, make sure to pass it to your backend to obtain the recommendation in the next step.
Note
For an alternative approach that directly utilizes our backend API instead, refer to our [Backend API implementation](/guides/risk/quick_start_backendapi#step-4-trigger-actions) guide.
Kotlin
```kotlin
// Optional, pass 'null' if not used
val payer = PayerData(
name = "PAYER_NAME",
bankIdentifier = "PAYER_BANK_IDENTIFIER",
branchIdentifier = "PAYER_BRANCH_IDENTIFIER",
accountNumber = "PAYER_ACCOUNT_NUMBER"
)
val payee = PayeeData(
name = "PAYEE_NAME",
bankIdentifier = "PAYEE_BANK_IDENTIFIER",
branchIdentifier = "PAYEE_BRANCH_IDENTIFIER",
accountNumber = "PAYEE_ACCOUNT_NUMBER"
)
// Optional, pass 'null' if not used
val customAttributes : Map? = mapOf(
"accountAgeInDays" to 12,
"customerSegment" to "VIP",
"hasCompletedKYC" to true
)
// Optional, pass 'null' if not used
val locationCollectionMode: TSLocationCollectionMode = TSLocationCollectionMode.LastKnown(validFor = 30)
/* Can be one of the following:
* Default: falls back to default configuration
* Disabled: doesn't report location
* ForceCurrent: real-time retrieval
* ForceLastKnown: reports the last captured location
* LastKnown(validFor: Int): reports last known location if captured within last X minites
*/
val locationConfig: TSLocationConfig = TSLocationConfig(mode = locationCollectionMode)
TSAccountProtection.triggerAction(
"[ACTION_TYPE]",
// Optional, pass 'null' if not used
object : ActionEventOptions {
override val correlationId: String?
get() = correlationIdStr
override val claimUserId: String?
get() = claimUserIdStr
override val referenceUserId: String?
get() = referenceUserIdStr
},
// Optional, pass 'null' if not used
object : TransactionData {
override val amount: Double?
get() = amount
override val currency: String?
get() = currencyStr
override val payer: PayerData?
get() = payer
override val payee: PayeeData?
get() = payee
override val reason: String?
get() = reasonStr
override val transactionDate: Long?
get() = transactionDate
},
// Optional,
customAttributes,
// Optional, pass 'null' if not used
locationConfig,
object : ITransmitSecurityTriggerActionEventCallback {
override fun onResponse(transmitSecurityTriggerActionResponse: TransmitSecurityTriggerActionResponse) {
val token = transmitSecurityTriggerActionResponse.token()
}
override fun onFailed(transmitSecurityAccountProtectionError: TransmitSecurityAccountProtectionError) {
val error = transmitSecurityAccountProtectionError.errorMessage
}
}
)
```
Java
```java
//optional, pass 'null' if not used
PayerData payer = new PayerData("PAYER_NAME", "PAYER_BANK_IDENTIFIER", "PAYER_BRANCH_IDENTIFIER", "PAYER_ACCOUNT_NUMBER");
PayeeData payee = new PayeeData("PAYEE_NAME", "PAYEE_BANK_IDENTIFIER", "PAYEE_BRANCH_IDENTIFIER", "PAYEE_ACCOUNT_NUMBER");
// Optional, pass 'null' if not used
// 'interval' can be -1, 0, any positive integer or 'null' if not used
int interval = 30;
TSLocationConfig enableLocation = new TSLocationConfig.Enable(interval);
TSLocationConfig disableLocation = TSLocationConfig.Disable.INSTANCE;
TSAccountProtection.triggerAction("[ACTION_TYPE]",
//Optional, pass 'null' if not used
new ActionEventOptions() {
@Nullable
@Override
public String getCorrelationId() {
return "CorrelationIdStr";
}
@Nullable
@Override
public String getClaimUserId() {
return "ClaimUserIdStr";
}
@Nullable
@Override
public String getReferenceUserId() {
return "ReferenceUserIdStr";
}
},
// Optional, pass 'null' if not used
new TransactionData() {
@Nullable
@Override
public Double getAmount() {
return amount;
}
@Nullable
@Override
public String getCurrency() {
return "currencyStr";
}
@Nullable
@Override
public PayerData getPayer() {
return payer;
}
@Nullable
@Override
public PayeeData getPayee() {
return payee;
}
@Nullable
@Override
public String getReason() {
return "reasonStr";
}
@Nullable
@Override
public Long getTransactionDate() {
return transactionDate;
}
},
// Optional, pass 'null' if not used
enableLocation, // or disableLocation
new ITransmitSecurityTriggerActionEventCallback() {
@Override
public void onResponse(@NonNull TransmitSecurityTriggerActionResponse transmitSecurityTriggerActionResponse) {
String token = transmitSecurityTriggerActionResponse.token();
}
@Override
public void onFailed(@NonNull TransmitSecurityAccountProtectionError transmitSecurityAccountProtectionError) {
String error = transmitSecurityAccountProtectionError.getErrorMessage();
}
});
```
## Step 5: Fetch recommendation
div
div
Backend
You can fetch recommendations from your **backend** for the reported action using the [Recommendation API](/openapi/risk/recommendations.openapi/other/getriskrecommendation). This is the same API that's also used for web integrations.
Mosaic APIs are authorized using an access token so you'll need to fetch a token using your client credentials (from step 1). To do this, send the following request:
```js
const { access_token } = await fetch(
`https://api.transmitsecurity.io/oidc/token`,
{
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded'
}
body: new URLSearchParams({
grant_type: client_credentials,
client_id: [CLIENT_ID],
client_secret: [CLIENT_SECRET]
})
}
);
```
From your backend, invoke the Recommendation API by sending a request like the one below. The `[ACCESS_TOKEN]` is the authorization token you obtained using your client credentials and `[ACTION_TOKEN]` is the `actionToken` received from the SDK in Step 4.
```js
const query = new URLSearchParams({
action_token: '[ACTION_TOKEN]',
}).toString();
const resp = await fetch(
`https://api.transmitsecurity.io/risk/v1/recommendation?${query}`,
{
method: 'GET',
headers: {
Authorization: 'Bearer [ACCESS_TOKEN]',
},
}
);
```
## Step 6: Set user
div
div
Client
A user identifier must be reported to Mosaic after you've fully authenticated the user (including, for example, any required 2FA that was done). This will set the user for all subsequent events in the current device session, or until the app prompts the user to re-login, or until the user is explicitly cleared.
To do this, add the code below after your application has authenticated a user (or after SDK initialization if you already have the user context for the authenticated user). The `[USER_ID]` is an opaque identifier for the user in your system and must not include personal user identifiers, such as email, in plain text.
Kotlin
```kotlin
TSAccountProtection.setUserID(userId)
```
Java
```java
TSAccountProtection.setUserID(userId);
```
Note
For an alternative approach that directly utilizes our backend API instead, refer to our [Backend API implementation](/guides/risk/quick_start_backendapi#step-6-report-action-result) guide.
## Step 7: Clear user
div
div
Client
The user gets automatically cleared once the device session expires or in case of a new login action. After the user logs out, you should clear the set user so they are not associated with future actions. To clear the user, call the `clearUser()` method:
Kotlin
```kotlin
TSAccountProtection.clearUser()
```
Java
```java
TSAccountProtection.clearUser();
```