Location Tracking

How it works

The Location module captures location (with user consent) from your app and attaches it to a person’s profile in Zixflow. You can use this data for geo-aware messaging and audience segmentation with more accuracy than IP-based geolocation. When you identify a person, the SDK includes the latest location in the identify call. The SDK also sends a location update to the person’s activity timeline (ZIXFLOW Location Update), which you can use in campaigns and segments. To balance location updates with battery and data usage, the SDK limits location updates (at most once a day)—and only sends that update when the person has moved a meaningful distance since the last update. The SDK does not request location permission on its own—your app must handle the permission flow.

Add the dependency

dependencies {
    implementation("com.zixflow.com.android:datapipelines:1.1.3")
    implementation("com.zixflow.com.android:location:1.1.3")
}

Add permissions

Add location permissions to AndroidManifest.xml:

<manifest>
    <!-- For foreground location -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

    <!-- For background location (optional, Android 10+) -->
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
</manifest>

Request location permission

import android.Manifest
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity

class MainActivity : AppCompatActivity() {

    private val requestLocationPermission = registerForActivityResult(
        ActivityResultContracts.RequestMultiplePermissions()
    ) { permissions ->
        when {
            permissions[Manifest.permission.ACCESS_FINE_LOCATION] == true -> {
                // Precise location granted
            }
            permissions[Manifest.permission.ACCESS_COARSE_LOCATION] == true -> {
                // Approximate location granted
            }
            else -> {
                // Location permission denied
            }
        }
    }

    private fun requestLocationPermission() {
        requestLocationPermission.launch(
            arrayOf(
                Manifest.permission.ACCESS_FINE_LOCATION,
                Manifest.permission.ACCESS_COARSE_LOCATION
            )
        )
    }
}

Initialize with location config

Add ModuleLocation to your ZixflowConfigBuilder. The trackingMode property controls how and when the SDK captures location.

Option	Type	Default	Description
`trackingMode`	`LocationTrackingMode`	`MANUAL`	Controls how and when the SDK captures location

Tracking modes

Mode	Description
`LocationTrackingMode.MANUAL`	Your app controls when location is captured. Call `setLastKnownLocation()` or `requestLocationUpdate()`. Use this when your app already tracks location or you want full control.
`LocationTrackingMode.ON_APP_START`	The SDK captures a one-shot location once per app launch when the app enters the foreground. You can still call the location APIs alongside automatic capture.
`LocationTrackingMode.OFF`	Disables location tracking. Location calls become silent no-ops and location is not included in identify calls.

import com.zixflow.sdk.Zixflow
import com.zixflow.sdk.ZixflowConfigBuilder
import com.zixflow.location.LocationModuleConfig
import com.zixflow.location.LocationTrackingMode
import com.zixflow.location.ModuleLocation

val locationConfig = LocationModuleConfig.Builder()
    .setLocationTrackingMode(LocationTrackingMode.MANUAL)
    .build()

Zixflow.initialize(
    ZixflowConfigBuilder(this, "YOUR_API_KEY")
        .addZixflowModule(ModuleLocation(moduleConfig = locationConfig))
        .build()
)

Using ModuleLocation() without a config uses MANUAL mode by default.

Location APIs

Access location services through the location module:

val locationServices = ModuleLocation.instance().locationServices

You can call these methods as often as you like. The SDK caches the latest coordinates for profile enrichment, but throttles outbound location updates so you do not overwhelm your workspace.

`setLastKnownLocation`

Pass coordinates from your app’s own location system. This does not require the SDK to manage location permissions—your app manages access independently.

import android.location.Location
import com.zixflow.location.ModuleLocation

// Pass a Location object
val location: Location = // from LocationManager or FusedLocationProviderClient
ModuleLocation.instance().locationServices.setLastKnownLocation(location)

// Or pass latitude / longitude directly
ModuleLocation.instance().locationServices.setLastKnownLocation(
    latitude = 37.7749,
    longitude = -122.4194
)

Parameter	Type	Description
`latitude`	`Double`	Latitude in degrees. Must be between -90 and 90.
`longitude`	`Double`	Longitude in degrees. Must be between -180 and 180.
`location`	`Location`	Android `Location` object from your provider

`requestLocationUpdate`

Request a one-shot location from Play Services location APIs. Use this if your app does not have its own location system. Your app must request location permission before calling this method—the SDK will not prompt the user. If permission is denied or location services are disabled, the request is ignored (no crash).

// After location permission is granted
ModuleLocation.instance().locationServices.requestLocationUpdate()

Profile switch behavior

When you call Zixflow.instance().clearIdentify(), the SDK clears cached location data so one person’s location does not carry over to another profile. The next person you identify starts with a clean slate.

Getting Started

Features

Advanced

Reference

How it works

Add the dependency

Add permissions

Request location permission

Initialize with location config

Tracking modes

Location APIs

`setLastKnownLocation`

`requestLocationUpdate`

Profile switch behavior

​How it works

​Add the dependency

​Add permissions

​Request location permission

​Initialize with location config

​Tracking modes

​Location APIs

​setLastKnownLocation

​requestLocationUpdate

​Profile switch behavior

How it works

Add the dependency

Add permissions

Request location permission

Initialize with location config

Tracking modes

Location APIs

`setLastKnownLocation`

`requestLocationUpdate`

Profile switch behavior