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, 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. Complete Quick Start (initialize + identify) before relying on location-based campaigns. Pods: Installation. Checklist: Example Applications.

Enable the location module

Location is an optional native module. Enable it on both platforms before calling location APIs.

iOS

Add the location subspec to your ios/Podfile, then run pod install:

pod 'zixflow-reactnative/location', :path => '../node_modules/zixflow-reactnative'

Android

Set the following flag in android/gradle.properties:

zixflow_location_enabled=true

If the module is not enabled, location calls no-op and a one-time development warning is logged.

Initialize with location config

Add a location object to your ZixflowConfig. The trackingMode property controls how and when the SDK captures location.

Option	Type	Default	Description
`trackingMode`	`ZixflowLocationTrackingMode`	`Manual`	Controls how and when the SDK captures location

Tracking modes

Mode	Description
`ZixflowLocationTrackingMode.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.
`ZixflowLocationTrackingMode.OnAppStart`	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.
`ZixflowLocationTrackingMode.Off`	Disables location tracking. Location calls become silent and location is not included in identify calls.

import {
  Zixflow,
  ZixflowConfig,
  ZixflowLocationTrackingMode,
} from 'zixflow-reactnative';

const config: ZixflowConfig = {
  apiKey: 'YOUR_API_KEY',
  location: {
    trackingMode: ZixflowLocationTrackingMode.Manual,
  },
};

Zixflow.initialize(config);

Request location permissions

Add the required platform keys, then request permission at runtime before calling SDK location APIs. iOS — Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to personalize your experience.</string>

Android — AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- Optional: for more precise location -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Request permission with a library such as react-native-permissions:

import { request, PERMISSIONS, RESULTS } from 'react-native-permissions';
import { Platform } from 'react-native';

const requestLocationPermission = async () => {
  const permission = Platform.select({
    ios: PERMISSIONS.IOS.LOCATION_WHEN_IN_USE,
    android: PERMISSIONS.ANDROID.ACCESS_FINE_LOCATION,
  });

  if (!permission) return false;

  const result = await request(permission);
  return result === RESULTS.GRANTED || result === RESULTS.LIMITED;
};

Location APIs

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 { Zixflow } from 'zixflow-reactnative';

// Pass coordinates from your app's location provider
Zixflow.location.setLastKnownLocation(37.7749, -122.4194);

Parameter	Type	Description
`latitude`	`number`	Latitude in degrees. Must be between -90 and 90.
`longitude`	`number`	Longitude in degrees. Must be between -180 and 180.

`requestLocationUpdate`

Request a one-shot location from the native platform’s location services. 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). If a request is already in progress, additional calls are ignored until it completes.

import { Zixflow } from 'zixflow-reactnative';

// After location permission is granted
Zixflow.location.requestLocationUpdate();

Profile switch behavior

When you call Zixflow.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. Location can persist across app restarts. When your app relaunches, the SDK may restore the cached location so the next identify() call includes it automatically.

Getting Started

Features

Advanced

Reference

How it works

Enable the location module

iOS

Android

Initialize with location config

Tracking modes

Request location permissions

Location APIs

`setLastKnownLocation`

`requestLocationUpdate`

Profile switch behavior

​How it works

​Enable the location module

​iOS

​Android

​Initialize with location config

​Tracking modes

​Request location permissions

​Location APIs

​setLastKnownLocation

​requestLocationUpdate

​Profile switch behavior

How it works

Enable the location module

iOS

Android

Initialize with location config

Tracking modes

Request location permissions

Location APIs

`setLastKnownLocation`

`requestLocationUpdate`

Profile switch behavior