Track geolocation for mobile devices

Tracking mobile device geolocation enhances risk assessment and helps build a continuous risk profile that takes into account current and previous locations of the user, their travel patterns, etc.

Fraud Prevention SDKs enable you to get precise device location when a specific high-risk event is triggered (e.g., login or transaction) and report this data to Mosaic. The geolocation data then appears in recommendations returned by Mosaic and is taken into account for risk analysis.

Use cases

Сollecting precise device geolocation data can significantly enhance risk analytics for:

• Account takeover detection : Helps detect account takeover or credential compromise in real time. For example, a user attempts to log in from a location that deviates significantly from their usual behavior (e.g., logging in from Europe just minutes after accessing the app from the US) — could be a sign of an account compromise.
• High-risk actions monitoring : Helps assess the legitimacy of sensitive actions, such as high-value transactions. For example, a credit card charge from a foreign country immediately after a local transaction may indicate fraud.
• Location-aware access policies : Helps restrict access to app based on geographic rules. For example, allow access to the corporate app within the company premises only or restrict access to financial app to the compliant regions.

User consent & OS permissions

Precise device geolocation is considered Personally Identifiable Information (PII). To avoid legal and compliance issues, your app must explicitly obtain the user's consent before requesting OS permissions to collect geolocation data.

When requesting OS permissions, inform users about the purpose, i.e., why and when their location will be collected before requesting permission.

Android

Your app should request and grant OS permissions to collect location data. The permissions have to be added to AndroidManifest.xml inside the <manifest>.

• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_FINE_LOCATION : Optional, provides more precision

See more in Android documentation.

iOS

Your app should request and grant either of the following OS permissions to collect location data. The key has to be added to Info.plist along with description that explains the permission usage.

• NSLocationWhenInUseUsageDescription key: "Allow while using app", provides access to location data only when your app is in the foreground.
• NSLocationAlwaysAndWhenInUseUsageDescription key: "Allow always", provides access to location data even when your app is in the background (requires extra plist key and background mode).

See more in Apple developer documentation.

Geolocation data

Fraud Prevention SDKs accumulate geolocation data from Wi-Fi, GPS, cellular services, including latitude, longitude, and altitude.

The reported geolocation data can represent:

• Device last known location : the most recent location that was recorded. This location could be recorded by other apps.
• Device current location : the most up-to-date location of the device. This is done by actively querying the location services.

Configuration

By default, Fraud Prevention SDKs use the following configuration for collecting and reporting location data:

Mosaic fine-tunes default collection settings per each action type triggered by Fraud Prevention SDKs:

Report location when triggering events

Mobile SDKs support reporting device location when an action event is triggered. The location is reported based on the TSLocationCollectionMode object specified in the triggerAction() SDK call. The 'default' falls back to the default configuration.

In the example below, for a checkout event, the SDK reports a device location captured within the last 30 minutes.

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(
  "checkout",
  locationConfig,
  object : ITransmitSecurityTriggerActionEventCallback {
      override fun onResponse(transmitSecurityTriggerActionResponse: TransmitSecurityTriggerActionResponse) {
          // TODO
      }
      override fun onFailed(error: TransmitSecurityAccountProtectionError) {
          // TODO
      }
    }
  )

/* Can be one of the following modes:
* 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
*/
let collectionMode: TSLocationCollectionMode = .lastKnown(validFor: 30)

TSAccountProtection.triggerAction("[ACTION_TYPE]", locationConfig: .init(mode: collectionMode)) { result in
    switch result {
    case .success(let response):
        let token = response.actionToken
        // Handle response
    case .failure(_):
        // Handle error
        break
    }
}

Logic

SDK checks if the required OS permissions to collect location data were granted to the app. If not, the SDK initialization and action triggering will still succeed, but no geolocation data will be collected or reported to Mosaic.

When triggering an action, the SDK attempts to report geolocation based on the TSLocationCollectionMode specified in the triggerAction() call: the current location, the last known location, or a location obtained within the last X minutes.

If default is specified, the SDK first uses the default settings for the event type (e.g., login, transaction). For custom actions—or if no default is set for the event type—the SDK falls back to the general default settings.

Reporting the current location for an action event requires querying geolocation services in real time, which may delay the triggerAction() call to Mosaic.

The SDK applies the following logic when reporting location: if querying the current location takes longer than the query timeout (1,500 ms by default), the SDK falls back to reporting the last known location to Mosaic.