chore: update Location tracking module config (#665)

Author: Shahroz16

core/src/main/kotlin/io/customer/sdk/core/util/MainThreadPoster.kt

@@ -0,0 +1,26 @@
+package io.customer.sdk.core.util
+
+import android.os.Handler
+import android.os.Looper
+import io.customer.base.internal.InternalCustomerIOApi
+
+/**
+ * Abstracts posting work to the main thread.
+ * Enables testability by allowing tests to mock or replace the implementation.
+ */
+@InternalCustomerIOApi
+interface MainThreadPoster {
+    fun post(block: () -> Unit)
+}
+
+/**
+ * Default implementation using Android [Handler] with the main [Looper].
+ */
+@InternalCustomerIOApi
+class HandlerMainThreadPoster : MainThreadPoster {
+    private val handler = Handler(Looper.getMainLooper())
+
+    override fun post(block: () -> Unit) {
+        handler.post(block)
+    }
+}

location/api/location.api

@@ -1,20 +1,28 @@
 public final class io/customer/location/LocationModuleConfig : io/customer/sdk/core/module/CustomerIOModuleConfig {
-	public synthetic fun <init> (ZLkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public final fun getEnableLocationTracking ()Z
+	public synthetic fun <init> (Lio/customer/location/LocationTrackingMode;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun getTrackingMode ()Lio/customer/location/LocationTrackingMode;
 }
 
 public final class io/customer/location/LocationModuleConfig$Builder : io/customer/sdk/core/module/CustomerIOModuleConfig$Builder {
 	public fun <init> ()V
 	public fun build ()Lio/customer/location/LocationModuleConfig;
 	public synthetic fun build ()Lio/customer/sdk/core/module/CustomerIOModuleConfig;
-	public final fun setEnableLocationTracking (Z)Lio/customer/location/LocationModuleConfig$Builder;
+	public final fun setLocationTrackingMode (Lio/customer/location/LocationTrackingMode;)Lio/customer/location/LocationModuleConfig$Builder;
 }
 
 public abstract interface class io/customer/location/LocationServices {
 	public abstract fun requestLocationUpdate ()V
 	public abstract fun setLastKnownLocation (DD)V
 	public abstract fun setLastKnownLocation (Landroid/location/Location;)V
-	public abstract fun stopLocationUpdates ()V
+}
+
+public final class io/customer/location/LocationTrackingMode : java/lang/Enum {
+	public static final field MANUAL Lio/customer/location/LocationTrackingMode;
+	public static final field OFF Lio/customer/location/LocationTrackingMode;
+	public static final field ON_APP_START Lio/customer/location/LocationTrackingMode;
+	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public static fun valueOf (Ljava/lang/String;)Lio/customer/location/LocationTrackingMode;
+	public static fun values ()[Lio/customer/location/LocationTrackingMode;
 }
 
 public final class io/customer/location/ModuleLocation : io/customer/sdk/core/module/CustomerIOModule {

location/build.gradle

@@ -44,6 +44,7 @@ dependencies {
     api project(":core")
 
     implementation Dependencies.googlePlayServicesLocation
+    implementation Dependencies.androidxProcessLifecycle
     implementation Dependencies.coroutinesCore
     implementation Dependencies.coroutinesAndroid
 }

location/src/main/kotlin/io/customer/location/LocationLifecycleObserver.kt

@@ -0,0 +1,39 @@
+package io.customer.location
+
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+
+/**
+ * Manages location lifecycle tied to app foreground/background transitions.
+ *
+ * Registered with [ProcessLifecycleOwner] during module initialization.
+ * - [onStart]: triggers a one-shot location request on the first foreground entry
+ *   when [trackingMode] is [LocationTrackingMode.ON_APP_START].
+ * - [onStop]: cancels any in-flight GPS request when the app enters background.
+ *
+ * Thread safety: all lifecycle callbacks are delivered on the main thread
+ * by [ProcessLifecycleOwner], so no synchronization is needed.
+ */
+internal class LocationLifecycleObserver(
+    private val locationServices: LocationServicesImpl,
+    private val trackingMode: LocationTrackingMode
+) : DefaultLifecycleObserver {
+
+    private var hasRequestedOnStart = false
+
+    override fun onStart(owner: LifecycleOwner) {
+        if (trackingMode == LocationTrackingMode.ON_APP_START && !hasRequestedOnStart) {
+            hasRequestedOnStart = true
+            locationServices.requestLocationUpdate()
+        }
+    }
+
+    override fun onStop(owner: LifecycleOwner) {
+        val wasCancelled = locationServices.cancelInFlightRequest()
+        // If the GPS request was still in flight when we backgrounded,
+        // allow onStart to retry on the next foreground entry.
+        if (wasCancelled) {
+            hasRequestedOnStart = false
+        }
+    }
+}

location/src/main/kotlin/io/customer/location/LocationModuleConfig.kt

@@ -8,30 +8,37 @@ import io.customer.sdk.core.module.CustomerIOModuleConfig
  */
 class LocationModuleConfig private constructor(
     /**
-     * Whether location tracking is enabled.
+     * The tracking mode for the location module.
      *
-     * When false, the location module is effectively disabled and all location
-     * tracking operations will no-op silently.
+     * - [LocationTrackingMode.OFF]: Location tracking is disabled; all operations no-op.
+     * - [LocationTrackingMode.MANUAL]: Host app controls when location is captured (default).
+     * - [LocationTrackingMode.ON_APP_START]: SDK auto-captures location on cold start,
+     *   caching it for identify context enrichment.
      */
-    val enableLocationTracking: Boolean
+    val trackingMode: LocationTrackingMode
 ) : CustomerIOModuleConfig {
 
+    /**
+     * Whether location tracking is enabled (any mode other than [LocationTrackingMode.OFF]).
+     */
+    internal val isEnabled: Boolean
+        get() = trackingMode != LocationTrackingMode.OFF
+
     class Builder : CustomerIOModuleConfig.Builder<LocationModuleConfig> {
-        private var enableLocationTracking: Boolean = true
+        private var trackingMode: LocationTrackingMode = LocationTrackingMode.MANUAL
 
         /**
-         * Sets whether location tracking is enabled.
-         * When disabled, all location operations will no-op silently.
-         * Default is true.
+         * Sets the location tracking mode.
+         * Default is [LocationTrackingMode.MANUAL].
          */
-        fun setEnableLocationTracking(enable: Boolean): Builder {
-            this.enableLocationTracking = enable
+        fun setLocationTrackingMode(mode: LocationTrackingMode): Builder {
+            this.trackingMode = mode
             return this
         }
 
         override fun build(): LocationModuleConfig {
             return LocationModuleConfig(
-                enableLocationTracking = enableLocationTracking
+                trackingMode = trackingMode
             )
         }
     }

location/src/main/kotlin/io/customer/location/LocationOrchestrator.kt

@@ -18,7 +18,7 @@ internal class LocationOrchestrator(
 ) {
 
     suspend fun requestLocationUpdate() {
-        if (!config.enableLocationTracking) {
+        if (!config.isEnabled) {
             logger.debug("Location tracking is disabled, ignoring requestLocationUpdate.")
             return
         }

location/src/main/kotlin/io/customer/location/LocationServices.kt

@@ -41,20 +41,12 @@ interface LocationServices {
     fun setLastKnownLocation(location: Location)
 
     /**
-     * Starts a single location update and sends the result to Customer.io.
+     * Requests a single location update and sends the result to Customer.io.
      *
      * No-ops if location tracking is disabled or permission is not granted.
-     * Only one request at a time; calling again cancels any in-flight request
-     * and starts a new one.
      *
      * The SDK does not request location permission. The host app must request
      * runtime permissions and only call this when permission is granted.
      */
     fun requestLocationUpdate()
-
-    /**
-     * Cancels any in-flight location request.
-     * No-op if nothing is in progress.
-     */
-    fun stopLocationUpdates()
 }

location/src/main/kotlin/io/customer/location/LocationServicesImpl.kt

@@ -2,8 +2,6 @@ package io.customer.location
 
 import android.location.Location
 import io.customer.sdk.core.util.Logger
-import java.util.concurrent.locks.ReentrantLock
-import kotlin.concurrent.withLock
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.launch
@@ -21,11 +19,11 @@ internal class LocationServicesImpl(
     private val scope: CoroutineScope
 ) : LocationServices {
 
-    private val lock = ReentrantLock()
+    @Volatile
     private var currentLocationJob: Job? = null
 
     override fun setLastKnownLocation(latitude: Double, longitude: Double) {
-        if (!config.enableLocationTracking) {
+        if (!config.isEnabled) {
             logger.debug("Location tracking is disabled, ignoring setLastKnownLocation.")
             return
         }
@@ -45,34 +43,33 @@ internal class LocationServicesImpl(
     }
 
     override fun requestLocationUpdate() {
-        lock.withLock {
-            // Cancel any previous in-flight request
-            currentLocationJob?.cancel()
+        // If a request is already in flight, ignore the new call
+        if (currentLocationJob?.isActive == true) return
 
-            currentLocationJob = scope.launch {
-                val thisJob = coroutineContext[Job]
-                try {
-                    orchestrator.requestLocationUpdate()
-                } finally {
-                    lock.withLock {
-                        if (currentLocationJob === thisJob) {
-                            currentLocationJob = null
-                        }
-                    }
+        currentLocationJob = scope.launch {
+            try {
+                orchestrator.requestLocationUpdate()
+            } finally {
+                // Only clear if this is still the current job — prevents
+                // a cancelled job's finally from nulling a newer job's reference
+                if (currentLocationJob === coroutineContext[Job]) {
+                    currentLocationJob = null
                 }
             }
         }
     }
 
-    override fun stopLocationUpdates() {
-        val job: Job?
-        lock.withLock {
-            job = currentLocationJob
-            currentLocationJob = null
-        }
-        // Cancelling the job triggers invokeOnCancellation in FusedLocationProvider's
-        // suspendCancellableCoroutine, which cancels the CancellationTokenSource.
-        job?.cancel()
+    /**
+     * Cancels any in-flight location request.
+     * Called when the app enters background to avoid unnecessary GPS work.
+     *
+     * @return true if an active request was cancelled, false if nothing was in flight.
+     */
+    internal fun cancelInFlightRequest(): Boolean {
+        val job = currentLocationJob ?: return false
+        currentLocationJob = null
+        job.cancel()
+        return true
     }
 
     companion object {

location/src/main/kotlin/io/customer/location/LocationTracker.kt

@@ -6,6 +6,7 @@ import io.customer.sdk.core.pipeline.DataPipeline
 import io.customer.sdk.core.pipeline.IdentifyHook
 import io.customer.sdk.core.util.Logger
 import io.customer.sdk.util.EventNames
+import java.lang.ref.WeakReference
 
 /**
  * Coordinates all location state management: persistence, restoration,
@@ -30,12 +31,18 @@ import io.customer.sdk.util.EventNames
  * sync filter's state.
  */
 internal class LocationTracker(
-    private val dataPipeline: DataPipeline?,
+    dataPipeline: DataPipeline?,
     private val locationPreferenceStore: LocationPreferenceStore,
     private val locationSyncFilter: LocationSyncFilter,
     private val logger: Logger
 ) : IdentifyHook {
 
+    // WeakReference prevents this hook (retained by IdentifyHookRegistry
+    // inside a Segment plugin) from keeping CustomerIO alive after SDK
+    // cleanup. The strong reference lives in CustomerIO.instance — as long
+    // as the SDK is initialized, the weak ref is valid.
+    private val dataPipelineRef = WeakReference(dataPipeline)
+
     @Volatile
     private var lastLocation: LocationCoordinates? = null
 
@@ -117,7 +124,7 @@ internal class LocationTracker(
      * track event via [DataPipeline] if both pass.
      */
     private fun trySendLocationTrack(latitude: Double, longitude: Double) {
-        val pipeline = dataPipeline ?: return
+        val pipeline = dataPipelineRef.get() ?: return
         if (!pipeline.isUserIdentified) return
         if (!locationSyncFilter.filterAndRecord(latitude, longitude)) return
 

location/src/main/kotlin/io/customer/location/LocationTrackingMode.kt

@@ -0,0 +1,28 @@
+package io.customer.location
+
+/**
+ * Defines the tracking mode for the location module.
+ */
+enum class LocationTrackingMode {
+    /**
+     * Location tracking is disabled.
+     * All location operations will no-op silently.
+     */
+    OFF,
+
+    /**
+     * Host app controls when location is captured.
+     * Use [LocationServices.setLastKnownLocation] or [LocationServices.requestLocationUpdate]
+     * to manually trigger location capture. This is the default mode.
+     */
+    MANUAL,
+
+    /**
+     * SDK automatically captures location on cold start.
+     *
+     * The captured location goes through the normal sync path
+     * (cache + 24h/1km filter + track event if filter passes).
+     * Manual location APIs remain fully functional.
+     */
+    ON_APP_START
+}