Fraud Android SDK
Guide for integrating your Forter Android SDK
This guide is for installing Forter's SDK for native Android applications! Note that you'll need a Forter portal account and your unique Forter credentials to complete an SDK integration. The steps below outline the high-level integration flow.
Step 1: Install the SDK
Forter SDK
is available in Forter's private Maven repository.
Get Forter SDK via Maven
Gradle version 7.0 and above
Inside your project's settings.gradle
file, append the following repository to your repositories
block under dependencyResolutionManagement
:
maven {
url "https://<forter-android-mobile-sdk-link>"
credentials {
username "<forter-user-name>"
password "<forter-password>"
}
}
Earlier Gradle versions
Inside your project's build.gradle
file, append the following repository to your repositories
block:
maven {
url "https://<forter-android-mobile-sdk-link>"
credentials {
username "<forter-user-name>"
password "<forter-password>"
}
}
The credentials should be specified and are available within your Forter portal. These credentials aren't sensitive but we keep these private to avoid caching by bots and search engines.
Add the Forter SDK as a dependency
Inside your application's build.gradle
file add your Forter SDK dependency in the dependencies
block:
implementation 'com.forter.mobile:fortersdk:2.5.1'
- Note the latest version listed in the repo is the latest stable version
Step 2: Add required permissions
Forter's Android SDK uses the common internet access permission. Even if you just started developing your app you've probably already added those permissions to your manifest. If you haven't, please add the following lines to your manifest file:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Step 3: Initiate the SDK ✨
Forter's Android SDK should be initialized from the main Application Context. If your app is not currently using an Application Class, please add one and register it in your app's Manifest.
Add the following lines to your application class's onCreate
method.
String mobileId = ForterIntegrationUtils.getDeviceUID(this);
// Get ForterClient instance and initiate it with the application context
IForterSDK ftr = ForterSDK.getInstance();
ftr.init(this,
AppConstants.FORTER_SITE_ID, // Include your unique Forter site ID
mobileId // Use our / provide your existing device identifier
);
🔥 The existing Android Device ID value is recommended as the value to pass to the
getDeviceId
method as it is a stable PII-compliant value 🔥
Register Lifecycle Callbacks
After initiating the Forter SDK, from your application class's onCreate
method, please register our built-in activity lifecycle callbacks:
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH)
{
registerActivityLifecycleCallbacks(ftr.getActivityLifecycleCallbacks());
}
Send your App Active Event
After initiating the SDK and registering the Activity Lifecycle callbacks, send your first track to Forter's servers by calling the trackAction
event. --> note the exact method is only available in our portal documentation
forter.trackAction(TrackType.APP_ACTIVE); // for sending 'app active' event
Re-Review your onCreate
method
onCreate
method@Override
public void onCreate() {
super.onCreate();
// Use our / provide your existing device identifier
String mobileId = ForterIntegrationUtils.getDeviceUID(this);
// Get ForterClient instance and initiate it with the application context
IForterSDK ftr = ForterSDK.getInstance();
ftr.init(this,
AppConstants.FORTER_SITE_ID,
mobileId // Provide your mobile device Unique ID
);
// Start generic activity-based navigation tracking
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH)
{
registerActivityLifecycleCallbacks(ftr.getActivityLifecycleCallbacks());
}
// Send the 'app active' event.
ftr.trackAction(TrackType.APP_ACTIVE);
}
Make sure you use your siteId found in your dedicated Forter portal from the appropriate environment and then initiate the SDK using the following command:
Step 4: Provide Your Own Unique Identifier (Optional) :person-with-pouting-face:
Forter's SDK requires a unique mobile device identifier to link the activity and behavioral data collected by the SDK to the specific device and user. This identifier should be:
- Specific to each device
- Does not mutate from a user's app session
- PII compliant
Forter recommends using the ANDROID_ID. To set the mobileUID use the following command:
ForterIntegrationUtils.getDeviceUID(this)
For Official Android Best Practices see the link here
important The value retrieved as. the DeviceIUID ("mobileUID") should be sent in the backend API requests as the value for the connectionInformation.forterMobileUID
key. backend API requests
Casing While Forter's system has no casing preference, the
mobileUID
generated via the SDK must match the casing of the mobileUID that is passed to the Validation API at the time of transaction in order for Forter's system to correctly connect the SDK data to the backend, Validation API's data.
Step 5: Send Event Data 🏬
In order to keep our SDK as lightweight as possible, Forter SDK does not collect navigation and custom activity events by default. These events should be called on relevant screens and actions. For instance, if a user searches for an item in the app and then proceeds to select a specific color, size, customization, a navigation event should be called with the FTRSDKNavigationTypeSearch
value. The method and type should only be called once and no additional details like size, color, brand, etc. need to be included.
Forter provides 2 methods for adding custom event:
- TrackAction - Actions performed by the user such as: removing items from cart, adding items to cart, logging into account, attempting to initiate a payment. The data included in this method can be a String or a Dictionary.
ForterSDK.getInstance().trackAction(TrackType.ADD_TO_CART, item_id); // add to cart event syntax
- TrackNavigation - Events where there's a context change like: navigating to a different product page or search result.
ForterSDK.getInstance().trackNavigation(TrackType.NavigationTypeCheckout); // nav to checkout
Step 6: Test/View your mobile events 📈
Once you've integrated the mobile SDK in sandbox (using your sandbox SiteId), you can look up events being passed to Forter for a specific mobileUID using our Sandbox Mobile Events Viewer. This gives developers visibility into how Forter is receiving and storing mobile events.
Step 7: Include mobileUID in backend and Forter API requests
Send the mobileUID generated by the Forter SDKs to your backend when an order is placed via your native mobile application.
This will allow Forter to connect behavioral and cyber data collected on the mobile applications to the order data sent from your backend. Merchants are in charge of how the mobileUID is passed and most will pass it securely via API request headers. In the case of native mobile app orders, make sure that the following fields are populated:
Step 8: Include UniqueId in your Forter API requests ✅
- orderType: "MOBILE", "iOS", or "ANDROID" depending on your OS (
"MOBILE"
can be used for either OS) - forterMobileUID: This should be populated instead of the
forterTokenCookie
if your app is fully native including your checkout page. If you use a webview for the checkout page, please review our Webview Integration. - mobileAppVersion: should reflect the version of the app the user is on
Example Android Request
{
"orderId": "Example_android123",
"orderType": "ANDROID",
"timeSentToForter": 1415287568000,
"checkoutTime": 1415273168,
"connectionInformation": {
"customerIP": "177.58.61.102",
"userAgent": "v2023.5.2 (Debug), Android 9",
"forterMobileUID": "2d43a0c77de616gggggafc6e5cd38b7b2581115e25"
},
"totalAmount": {
"amountUSD": "99.95"
}
...
}
Step 9: Deploy to Production 🚀
Merchants are in complete control of how and when they deploy Forter's SDK into their production environment. You'll work closely with your implementation team to ensure a seamless deployment of our SDK within your mobile app versions.
Updated 4 months ago