chore: add core location types, config, and EventBus event (#654)

Shahroz16 · web-flow · commit 572819ffe805 · 2026-02-17T15:16:01.000+05:00
diff --git a/core/api/core.api b/core/api/core.api
@@ -16,6 +16,19 @@ public final class io/customer/sdk/communication/Event$DeleteDeviceTokenEvent :
 	public fun <init> ()V
 }
 
+public final class io/customer/sdk/communication/Event$LocationData {
+	public fun <init> (DD)V
+	public final fun component1 ()D
+	public final fun component2 ()D
+	public final fun copy (DD)Lio/customer/sdk/communication/Event$LocationData;
+	public static synthetic fun copy$default (Lio/customer/sdk/communication/Event$LocationData;DDILjava/lang/Object;)Lio/customer/sdk/communication/Event$LocationData;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getLatitude ()D
+	public final fun getLongitude ()D
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
 public final class io/customer/sdk/communication/Event$RegisterDeviceTokenEvent : io/customer/sdk/communication/Event {
 	public fun <init> (Ljava/lang/String;)V
 	public final fun component1 ()Ljava/lang/String;
@@ -58,6 +71,17 @@ public final class io/customer/sdk/communication/Event$TrackInAppMetricEvent : i
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class io/customer/sdk/communication/Event$TrackLocationEvent : io/customer/sdk/communication/Event {
+	public fun <init> (Lio/customer/sdk/communication/Event$LocationData;)V
+	public final fun component1 ()Lio/customer/sdk/communication/Event$LocationData;
+	public final fun copy (Lio/customer/sdk/communication/Event$LocationData;)Lio/customer/sdk/communication/Event$TrackLocationEvent;
+	public static synthetic fun copy$default (Lio/customer/sdk/communication/Event$TrackLocationEvent;Lio/customer/sdk/communication/Event$LocationData;ILjava/lang/Object;)Lio/customer/sdk/communication/Event$TrackLocationEvent;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getLocation ()Lio/customer/sdk/communication/Event$LocationData;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
 public final class io/customer/sdk/communication/Event$TrackPushMetricEvent : io/customer/sdk/communication/Event {
 	public fun <init> (Ljava/lang/String;Lio/customer/sdk/events/Metric;Ljava/lang/String;)V
 	public final fun component1 ()Ljava/lang/String;
diff --git a/core/src/main/kotlin/io/customer/sdk/communication/Event.kt b/core/src/main/kotlin/io/customer/sdk/communication/Event.kt
@@ -51,4 +51,23 @@ sealed class Event {
     ) : Event()
 
     class DeleteDeviceTokenEvent : Event()
+
+    /**
+     * Event emitted when a location update should be tracked.
+     * Published by the Location module and consumed by DataPipeline
+     * to send location data to Customer.io servers.
+     */
+    data class TrackLocationEvent(
+        val location: LocationData
+    ) : Event()
+
+    /**
+     * Location data in a framework-agnostic format.
+     * Used to pass location information between modules without
+     * requiring Android location framework imports.
+     */
+    data class LocationData(
+        val latitude: Double,
+        val longitude: Double
+    )
 }
diff --git a/core/src/main/kotlin/io/customer/sdk/util/EventNames.kt b/core/src/main/kotlin/io/customer/sdk/util/EventNames.kt
@@ -11,4 +11,7 @@ object EventNames {
 
     // Event name fired by AndroidLifecyclePlugin when app enters background
     const val APPLICATION_BACKGROUNDED = "Application Backgrounded"
+
+    // Event name for location updates tracked by the Location module
+    const val LOCATION_UPDATE = "Location Update"
 }
diff --git a/datapipelines/src/main/kotlin/io/customer/sdk/CustomerIO.kt b/datapipelines/src/main/kotlin/io/customer/sdk/CustomerIO.kt
@@ -151,6 +151,21 @@ class CustomerIO private constructor(
         eventBus.subscribe<Event.RegisterDeviceTokenEvent> {
             registerDeviceToken(deviceToken = it.token)
         }
+        eventBus.subscribe<Event.TrackLocationEvent> {
+            trackLocation(it)
+        }
+    }
+
+    private fun trackLocation(event: Event.TrackLocationEvent) {
+        val location = event.location
+        logger.debug("tracking location update: lat=${location.latitude}, lng=${location.longitude}")
+        track(
+            name = EventNames.LOCATION_UPDATE,
+            properties = mapOf(
+                "lat" to location.latitude,
+                "lng" to location.longitude
+            )
+        )
     }
 
     private fun migrateTrackingEvents() {
diff --git a/location/api/location.api b/location/api/location.api
@@ -1,16 +1,21 @@
 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 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 class io/customer/location/ModuleLocation : io/customer/sdk/core/module/CustomerIOModule {
 	public static final field Companion Lio/customer/location/ModuleLocation$Companion;
 	public static final field MODULE_NAME Ljava/lang/String;
+	public fun <init> ()V
 	public fun <init> (Lio/customer/location/LocationModuleConfig;)V
+	public synthetic fun <init> (Lio/customer/location/LocationModuleConfig;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun getModuleConfig ()Lio/customer/location/LocationModuleConfig;
 	public synthetic fun getModuleConfig ()Lio/customer/sdk/core/module/CustomerIOModuleConfig;
 	public fun getModuleName ()Ljava/lang/String;
diff --git a/location/src/main/kotlin/io/customer/location/LocationModuleConfig.kt b/location/src/main/kotlin/io/customer/location/LocationModuleConfig.kt
@@ -6,11 +6,33 @@ import io.customer.sdk.core.module.CustomerIOModuleConfig
  * Location module configurations that can be used to customize
  * location tracking behavior based on the provided configurations.
  */
-class LocationModuleConfig private constructor() : CustomerIOModuleConfig {
+class LocationModuleConfig private constructor(
+    /**
+     * Whether location tracking is enabled.
+     *
+     * When false, the location module is effectively disabled and all location
+     * tracking operations will no-op silently.
+     */
+    val enableLocationTracking: Boolean
+) : CustomerIOModuleConfig {
 
     class Builder : CustomerIOModuleConfig.Builder<LocationModuleConfig> {
+        private var enableLocationTracking: Boolean = true
+
+        /**
+         * Sets whether location tracking is enabled.
+         * When disabled, all location operations will no-op silently.
+         * Default is true.
+         */
+        fun setEnableLocationTracking(enable: Boolean): Builder {
+            this.enableLocationTracking = enable
+            return this
+        }
+
         override fun build(): LocationModuleConfig {
-            return LocationModuleConfig()
+            return LocationModuleConfig(
+                enableLocationTracking = enableLocationTracking
+            )
         }
     }
 }
diff --git a/location/src/main/kotlin/io/customer/location/ModuleLocation.kt b/location/src/main/kotlin/io/customer/location/ModuleLocation.kt
@@ -7,15 +7,28 @@ import io.customer.sdk.core.module.CustomerIOModule
  * Location module for Customer.io SDK.
  *
  * This module provides location tracking capabilities including:
- * - Permission and consent management
- * - One-shot location capture
- * - Continuous location tracking
+ * - Manual location setting from host app's existing location system
+ * - One-shot SDK-managed location capture
+ *
+ * Usage:
+ * ```
+ * val config = CustomerIOConfigBuilder(appContext, "your-api-key")
+ *     .addCustomerIOModule(
+ *         ModuleLocation(
+ *             LocationModuleConfig.Builder()
+ *                 .setEnableLocationTracking(true)
+ *                 .build()
+ *         )
+ *     )
+ *     .build()
+ *
+ * CustomerIO.initialize(config)
+ * ```
  */
-class ModuleLocation(
-    config: LocationModuleConfig
+class ModuleLocation @JvmOverloads constructor(
+    override val moduleConfig: LocationModuleConfig = LocationModuleConfig.Builder().build()
 ) : CustomerIOModule<LocationModuleConfig> {
     override val moduleName: String = MODULE_NAME
-    override val moduleConfig: LocationModuleConfig = config
 
     override fun initialize() {
         // Module initialization will be implemented in future PRs
diff --git a/location/src/main/kotlin/io/customer/location/provider/LocationProvider.kt b/location/src/main/kotlin/io/customer/location/provider/LocationProvider.kt
@@ -0,0 +1,29 @@
+package io.customer.location.provider
+
+import io.customer.location.type.AuthorizationStatus
+import io.customer.location.type.LocationGranularity
+import io.customer.location.type.LocationSnapshot
+
+/**
+ * Abstracts system location services. Implementations wrap platform-specific
+ * location providers (e.g. FusedLocationProviderClient).
+ *
+ * This component does not request location permission. The host app must handle
+ * runtime permission requests and only call location APIs once authorized.
+ */
+internal interface LocationProvider {
+    /**
+     * One-shot location request. Returns the location result directly.
+     *
+     * @param granularity desired accuracy level for the request
+     * @return the captured location snapshot
+     * @throws LocationRequestException if location could not be obtained
+     */
+    suspend fun requestLocation(granularity: LocationGranularity): LocationSnapshot
+
+    /**
+     * Current authorization state for location access.
+     * Used for pre-checks before requesting location.
+     */
+    suspend fun currentAuthorizationStatus(): AuthorizationStatus
+}
diff --git a/location/src/main/kotlin/io/customer/location/provider/LocationRequestException.kt b/location/src/main/kotlin/io/customer/location/provider/LocationRequestException.kt
@@ -0,0 +1,13 @@
+package io.customer.location.provider
+
+import io.customer.location.type.LocationProviderError
+
+/**
+ * Exception thrown when a location request fails.
+ * Wraps [LocationProviderError] to provide structured error information.
+ */
+internal class LocationRequestException(
+    val error: LocationProviderError,
+    message: String = "Location request failed: $error",
+    cause: Throwable? = null
+) : Exception(message, cause)
diff --git a/location/src/main/kotlin/io/customer/location/type/AuthorizationStatus.kt b/location/src/main/kotlin/io/customer/location/type/AuthorizationStatus.kt
@@ -0,0 +1,25 @@
+package io.customer.location.type
+
+/**
+ * Authorization status for location access.
+ * Maps Android runtime permission states to SDK-level values
+ * without depending on Android framework classes.
+ *
+ * Note: On Android, [DENIED] covers both "never asked" and "explicitly denied"
+ * because [android.content.pm.PackageManager.checkPermission] cannot distinguish
+ * between the two without an Activity context.
+ */
+internal enum class AuthorizationStatus {
+    /** Permission not granted (either never asked or explicitly denied). */
+    DENIED,
+
+    /** Foreground-only location access granted. */
+    AUTHORIZED_FOREGROUND,
+
+    /** Background + foreground location access granted. */
+    AUTHORIZED_BACKGROUND;
+
+    /** Whether the app is authorized to use location (foreground or background). */
+    val isAuthorized: Boolean
+        get() = this == AUTHORIZED_FOREGROUND || this == AUTHORIZED_BACKGROUND
+}
diff --git a/location/src/main/kotlin/io/customer/location/type/LocationGranularity.kt b/location/src/main/kotlin/io/customer/location/type/LocationGranularity.kt
@@ -0,0 +1,17 @@
+package io.customer.location.type
+
+/**
+ * Semantic accuracy for location requests.
+ * Mapped internally to system accuracy settings (e.g. FusedLocationProviderClient priority).
+ */
+internal enum class LocationGranularity {
+    /**
+     * Reduced precision (city or timezone level).
+     * Maps to [com.google.android.gms.location.Priority.PRIORITY_LOW_POWER] (~10 km accuracy).
+     */
+    COARSE_CITY_OR_TIMEZONE;
+
+    companion object {
+        val DEFAULT: LocationGranularity = COARSE_CITY_OR_TIMEZONE
+    }
+}
diff --git a/location/src/main/kotlin/io/customer/location/type/LocationProviderError.kt b/location/src/main/kotlin/io/customer/location/type/LocationProviderError.kt
@@ -0,0 +1,15 @@
+package io.customer.location.type
+
+/**
+ * Reason location was not delivered. Returned from a location request on failure.
+ */
+internal enum class LocationProviderError {
+    /** Location permission not granted (denied or never requested). */
+    PERMISSION_DENIED,
+
+    /** Location services are disabled in device settings. */
+    SERVICES_DISABLED,
+
+    /** Location request timed out or failed due to a transient error. */
+    TIMEOUT
+}
diff --git a/location/src/main/kotlin/io/customer/location/type/LocationSnapshot.kt b/location/src/main/kotlin/io/customer/location/type/LocationSnapshot.kt
@@ -0,0 +1,15 @@
+package io.customer.location.type
+
+import java.util.Date
+
+/**
+ * Framework-agnostic location details. Built from system location inside the provider.
+ * Decouples modules from Android's [android.location.Location] class.
+ */
+internal data class LocationSnapshot(
+    val latitude: Double,
+    val longitude: Double,
+    val timestamp: Date,
+    val horizontalAccuracy: Double,
+    val altitude: Double? = null
+)

Original file line number	Diff line number	Diff line change
`@@ -11,4 +11,7 @@ object EventNames {`
`11`	`11`
`12`	`12`	`// Event name fired by AndroidLifecyclePlugin when app enters background`
`13`	`13`	`const val APPLICATION_BACKGROUNDED = "Application Backgrounded"`
	`14`	`+`
	`15`	`+ // Event name for location updates tracked by the Location module`
	`16`	`+ const val LOCATION_UPDATE = "Location Update"`
`14`	`17`	`}`