60

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 Customer.io. 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 event to the person’s activity timeline, which you can use in journeys and segments. To balance location updates with battery and data usage, the SDK limits location updates once a day (at most)—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.

Install the location module

The Location module requires native dependencies on both iOS and Android. Follow the platform-specific steps below.

1. For iOS: add the location subspec to your Podfile. Open ios/Podfile in your Flutter project and add the following line alongside your existing customer_io pod:

   pod 'customer_io/location', :path => '.symlinks/plugins/customer_io/ios'

2. For Android: add the following property to your project’s android/gradle.properties file:

   customerio_location_enabled=true

Initialize the SDK with the location module

Add a locationConfig to your CustomerIOConfig to enable the module. The trackingMode property controls how and when the SDK captures location.

Tracking modes

CustomerIO.initialize(
  config: CustomerIOConfig(
    cdpApiKey: 'YOUR_CDP_API_KEY',
    // ...other config options
    locationConfig: LocationConfig(
      trackingMode: LocationTrackingMode.manual,
    ),
  ),
);

Location APIs

The module provides two methods to capture location. You can call either method as often as you like; the SDK always caches the latest coordinates for profile enrichment, but sends a Location Update event no more than once a day—and only if the person has moved a meaningful distance since the last update. No matter how frequently you call these methods, the SDK throttles the updates for you so as not to overwhelm your workspace with profile updates.

setLastKnownLocation

Pass coordinates directly from your app’s own location system. This doesn’t require any location permissions from the SDK. Your app manages location access independently of Customer.io.

// Pass coordinates from your app's location provider
CustomerIO.location.setLastKnownLocation(
  latitude: 37.7749,
  longitude: -122.4194,
);

requestLocationUpdate

Request a one-shot location from the native platform’s location services. Use this if your app doesn’t have its own location system. Your app must request location permission before calling this method—the SDK won’t prompt the user.

If a user doesn’t grant permission or location services are disabled, the request is ignored—no crash or exception. If a request is already in progress, additional calls are ignored until the current request completes.

1. Add the required key to your Info.plist:

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

2. (Optional) If you want more precise location, add ACCESS_FINE_LOCATION to your AndroidManifest.xml. The SDK already includes ACCESS_COARSE_LOCATION when the location module is enabled.

   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   

3. After your app requests and receives permission at runtime, call the SDK:

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

Profile switch behavior

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

Location persists across app restarts. When your app relaunches, the SDK restores the cached location so that the next identify() call includes it automatically.