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

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

​
Tracking modes

ModeDescription
ZixflowLocationTrackingMode.ManualYour app controls when location is captured. Call setLastKnownLocation() or requestLocationUpdate(). Use this when your app already tracks location or you want full control.
ZixflowLocationTrackingMode.OnAppStartThe 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.OffDisables 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);
ParameterTypeDescription
latitudenumberLatitude in degrees. Must be between -90 and 90.
longitudenumberLongitude 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.