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 more than 1 kilometer 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

Add the CioLocation package to your project. If you use Swift Package Manager, add it the same way you added the other Customer.io packages. The CioLocation library is part of the customerio-ios package.

If you use CocoaPods, add the pod to your Podfile:

pod 'CustomerIO/Location'

Initialize the SDK with the location module

Register LocationModule when you initialize the SDK. The module takes a LocationConfig where you set the tracking mode.

Tracking modes

import CioDataPipelines
import CioLocation

let config = SDKConfigBuilder(cdpApiKey: "your-cdp-api-key")
    .addModule(LocationModule(config: LocationConfig(mode: .manual)))
    .build()

CustomerIO.initialize(withConfig: config)

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 more than 1 kilometer 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 a CLLocation 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.

import CoreLocation
import CioLocation

// From a CLLocationManager delegate callback
func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
    if let location = locations.last {
        CustomerIO.location.setLastKnownLocation(location)
    }
}

requestLocationUpdate

Request a one-shot location from the SDK using Core Location. 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.

Add the required key to your Info.plist:

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

Request permission at runtime, then call the SDK:

import CoreLocation
import CioLocation

let locationManager = CLLocationManager()

// Request permission first
locationManager.requestWhenInUseAuthorization()

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

Profile switch behavior

When you call CustomerIO.shared.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.