Skip to main content

​
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.
OptionTypeDefaultDescription
trackingModeLocationTrackingModeMANUALControls how and when the SDK captures location

​
Tracking modes

ModeDescription
LocationTrackingMode.MANUALYour 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_STARTThe 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.OFFDisables 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
)
ParameterTypeDescription
latitudeDoubleLatitude in degrees. Must be between -90 and 90.
longitudeDoubleLongitude in degrees. Must be between -180 and 180.
locationLocationAndroid 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.