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 mobile SDKs support geolocation reporting in two separate ways: initialization-based reporting, when location events are enabled during SDK initialization, and action-based reporting, when the app explicitly calls triggerAction(). These paths use different configuration points: the initialization-based path is configured at SDK startup, while the action-based path is configured in the triggerAction() call. In both flows, geolocation data is reported to Mosaic and taken into account for risk analysis.

Collecting 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 an app based on geographic rules. For example, allow access to the corporate app only within company premises or limit access to the financial app to compliant regions.

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.

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.

Your app should request and grant either of the following OS permissions to collect location data. Add the relevant key to Info.plist together with a usage description that explains why the app requests location access.

• 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.

Fraud Prevention mobile SDKs collect device geolocation using the device's Wi-Fi, GPS, and cellular signals. Reported data can include latitude, longitude, accuracy, altitude, provider, permissions, error, and recordedAt.

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 device's location APIs through the Fraud Prevention SDK.

By default, Fraud Prevention mobile SDKs use the following settings for collecting and reporting device geolocation:

For action-based reporting, use the table below as the default reference per action type. Mosaic fine-tunes default collection settings per action type triggered by Fraud Prevention mobile SDKs:

Use this path when location events are enabled during SDK initialization. It also supports backend-triggered mobile integrations that later use the device session. The location available to the backend-triggered action can come from the initial SDK startup or from a later foreground / active collection attempt.

The sequence below summarizes initialization-based reporting for both the initial SDK startup and later foreground / active collection attempts.

To use this pattern:

• Initialize the mobile SDK with enableLocationEvents set to true.
• Obtain a device session token from the SDK.
• Pass that session token to your backend, which then calls the Trigger action API, optionally with get_recommendation=true.

Any location collected during SDK initialization is stored in the device session and is available when the backend later triggers the action. This backend flow is the same session-token-based pattern described in the Backend API quick start.

Fraud Prevention mobile SDKs support reporting the device location during initialization. This flow is enabled only if the enableLocationEvents variable is set to true in the SDK initialization configuration. The collection method is determined by the defaultInterval value in the geolocation reporting configuration. The triggerAction() examples later in this guide use a separate, action-based configuration path.

For the full platform-specific SDK initialization steps, see the iOS quick start, Android quick start, and React Native quick start.

val enableLocationEvents: Boolean = true // If not set, default value is false
val configuration = TSInitSDKConfiguration(enableLocationEvents = enableLocationEvents)

TSAccountProtection.initialize(
    context = this,
    baseUrl = baseUrl,
    clientID = clientId,
    configuration = configuration
)

After initialization, location collection is lifecycle-based rather than interval-based. The SDK attempts a fresh location collection when the app returns to the foreground or becomes active, and it doesn't continue collecting location while the app is backgrounded. This path uses one-shot collection requests rather than continuous location monitoring.

At each collection attempt, the SDK checks the current location authorization state. If fresh location retrieval fails, the SDK falls back to the last known location when available; otherwise, it reports an error. If location permissions are missing, the SDK still sends the location event with an error and without coordinate data, and it doesn't fall back to a stale last known location. There is no automatic retry mechanism. Once permissions are restored, the next normal collection attempt succeeds.

If the user moves after initialization, the SDK picks up the updated location on the next foreground or active collection attempt. It doesn't use significant-location-change monitoring, geofencing, or motion-based triggers for this flow.

Fraud Prevention mobile SDKs also support reporting device location when an action event is triggered from the client. This section applies when your mobile app explicitly calls triggerAction(). The location is reported based on the TSLocationCollectionMode object specified in the triggerAction() SDK call. The default mode falls back to the default geolocation reporting configuration.

Reporting the current location for an action event requires the SDK to query the device's location APIs 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 (1500 ms by default), the SDK falls back to reporting the last known location to Mosaic.

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 minutes
*/
val locationConfig: TSLocationConfig = TSLocationConfig(mode = locationCollectionMode)

TSAccountProtection.triggerAction(
  "checkout",
  locationConfig,
  object : ITransmitSecurityTriggerActionEventCallback {
      override fun onResponse(transmitSecurityTriggerActionResponse: TransmitSecurityTriggerActionResponse) {
          // TODO
      }
      override fun onFailed(error: TransmitSecurityAccountProtectionError) {
          // TODO
      }
    }
  )

You can verify that device geolocation is being collected and sent without waiting for the recommendation response.

Look for SDK log lines similar to the following:

If you see these log lines, the SDK is collecting location data on the device and sending it to Mosaic.

If the logs don't appear, check the following:

• enableLocationEvents is set to true in the SDK initialization configuration.
• The app has the required OS location permissions.
• Location services are enabled on the device.
• The app has returned to the foreground or become active after initialization, or has triggered a client-side action that requests location.