|
| 1 | +package io.customer.location |
| 2 | + |
| 3 | +import io.customer.location.store.LocationPreferenceStore |
| 4 | +import io.customer.location.sync.LocationSyncFilter |
| 5 | +import io.customer.sdk.core.pipeline.DataPipeline |
| 6 | +import io.customer.sdk.core.pipeline.IdentifyHook |
| 7 | +import io.customer.sdk.core.util.Logger |
| 8 | +import io.customer.sdk.util.EventNames |
| 9 | + |
| 10 | +/** |
| 11 | + * Coordinates all location state management: persistence, restoration, |
| 12 | + * identify context enrichment, and sending location track events. |
| 13 | + * |
| 14 | + * Location reaches the backend through two independent paths: |
| 15 | + * |
| 16 | + * 1. **Identify context enrichment** — implements [IdentifyHook]. |
| 17 | + * Every identify() call enriches the event context with the latest |
| 18 | + * location coordinates. This is unfiltered — a new user always gets |
| 19 | + * the device's current location on their profile immediately. |
| 20 | + * |
| 21 | + * 2. **"Location Update" track event** — sent via [DataPipeline.track]. |
| 22 | + * Gated by a userId check and a sync filter (24h / 1km threshold) |
| 23 | + * to avoid redundant events. This creates a discrete event in the |
| 24 | + * user's activity timeline for journey/segment triggers. |
| 25 | + * |
| 26 | + * Profile switch handling is intentionally not tracked here. |
| 27 | + * On clearIdentify(), [resetContext] clears all state (cache, persistence, |
| 28 | + * sync filter) synchronously during analytics.reset(). On identify(), the |
| 29 | + * new user's profile receives the location via path 1 regardless of the |
| 30 | + * sync filter's state. |
| 31 | + */ |
| 32 | +internal class LocationTracker( |
| 33 | + private val dataPipeline: DataPipeline?, |
| 34 | + private val locationPreferenceStore: LocationPreferenceStore, |
| 35 | + private val locationSyncFilter: LocationSyncFilter, |
| 36 | + private val logger: Logger |
| 37 | +) : IdentifyHook { |
| 38 | + |
| 39 | + @Volatile |
| 40 | + private var lastLocation: LocationCoordinates? = null |
| 41 | + |
| 42 | + override fun getIdentifyContext(): Map<String, Any> { |
| 43 | + val location = lastLocation ?: return emptyMap() |
| 44 | + return mapOf( |
| 45 | + "location_latitude" to location.latitude, |
| 46 | + "location_longitude" to location.longitude |
| 47 | + ) |
| 48 | + } |
| 49 | + |
| 50 | + /** |
| 51 | + * Called synchronously by analytics.reset() during clearIdentify. |
| 52 | + * Clears all location state: in-memory cache, persisted coordinates, |
| 53 | + * and sync filter — similar to how device tokens and other per-user |
| 54 | + * state are cleared on reset. This runs before ResetEvent is published, |
| 55 | + * guaranteeing no stale data is available for a subsequent identify(). |
| 56 | + */ |
| 57 | + override fun resetContext() { |
| 58 | + lastLocation = null |
| 59 | + locationPreferenceStore.clearCachedLocation() |
| 60 | + locationSyncFilter.clearSyncedData() |
| 61 | + logger.debug("Location state reset") |
| 62 | + } |
| 63 | + |
| 64 | + /** |
| 65 | + * Reads persisted cached location from the preference store and sets the |
| 66 | + * in-memory cache so that identify events have location context |
| 67 | + * immediately after SDK restart. |
| 68 | + */ |
| 69 | + fun restorePersistedLocation() { |
| 70 | + val lat = locationPreferenceStore.getCachedLatitude() ?: return |
| 71 | + val lng = locationPreferenceStore.getCachedLongitude() ?: return |
| 72 | + lastLocation = LocationCoordinates(latitude = lat, longitude = lng) |
| 73 | + logger.debug("Restored persisted location: lat=$lat, lng=$lng") |
| 74 | + } |
| 75 | + |
| 76 | + /** |
| 77 | + * Processes an incoming location: caches in memory, persists |
| 78 | + * coordinates, and attempts to send a location track event. |
| 79 | + */ |
| 80 | + fun onLocationReceived(latitude: Double, longitude: Double) { |
| 81 | + logger.debug("Location update received: lat=$latitude, lng=$longitude") |
| 82 | + |
| 83 | + lastLocation = LocationCoordinates(latitude = latitude, longitude = longitude) |
| 84 | + locationPreferenceStore.saveCachedLocation(latitude, longitude) |
| 85 | + |
| 86 | + trySendLocationTrack(latitude, longitude) |
| 87 | + } |
| 88 | + |
| 89 | + /** |
| 90 | + * Called when a user is identified. Attempts to sync the cached |
| 91 | + * location as a track event for the newly identified user. |
| 92 | + * |
| 93 | + * The identify event itself already carries location via |
| 94 | + * [getIdentifyContext] — this method handles the supplementary |
| 95 | + * "Location Update" track event, subject to the sync filter. |
| 96 | + */ |
| 97 | + fun onUserIdentified() { |
| 98 | + syncCachedLocationIfNeeded() |
| 99 | + } |
| 100 | + |
| 101 | + /** |
| 102 | + * Re-evaluates the cached location for sending. |
| 103 | + * Called on identify (via [onUserIdentified]) and on cold start |
| 104 | + * (via replayed UserChangedEvent) to handle cases where a location |
| 105 | + * was cached but not yet sent for the current user. |
| 106 | + */ |
| 107 | + internal fun syncCachedLocationIfNeeded() { |
| 108 | + val lat = locationPreferenceStore.getCachedLatitude() ?: return |
| 109 | + val lng = locationPreferenceStore.getCachedLongitude() ?: return |
| 110 | + |
| 111 | + logger.debug("Re-evaluating cached location: lat=$lat, lng=$lng") |
| 112 | + trySendLocationTrack(lat, lng) |
| 113 | + } |
| 114 | + |
| 115 | + /** |
| 116 | + * Applies the userId gate and sync filter, then sends a location |
| 117 | + * track event via [DataPipeline] if both pass. |
| 118 | + */ |
| 119 | + private fun trySendLocationTrack(latitude: Double, longitude: Double) { |
| 120 | + val pipeline = dataPipeline ?: return |
| 121 | + if (!pipeline.isUserIdentified) return |
| 122 | + if (!locationSyncFilter.filterAndRecord(latitude, longitude)) return |
| 123 | + |
| 124 | + logger.debug("Sending location track: lat=$latitude, lng=$longitude") |
| 125 | + pipeline.track( |
| 126 | + name = EventNames.LOCATION_UPDATE, |
| 127 | + properties = mapOf( |
| 128 | + "latitude" to latitude, |
| 129 | + "longitude" to longitude |
| 130 | + ) |
| 131 | + ) |
| 132 | + } |
| 133 | +} |
| 134 | + |
| 135 | +/** |
| 136 | + * Internal location coordinate holder, replacing the cross-module Event.LocationData. |
| 137 | + */ |
| 138 | +internal data class LocationCoordinates( |
| 139 | + val latitude: Double, |
| 140 | + val longitude: Double |
| 141 | +) |
0 commit comments