Create Geofence events

Examples/KlaviyoSwiftExamples/SPMExample/SPMExample/Info.plist

@@ -26,6 +26,8 @@
 	<key>UIBackgroundModes</key>
 	<array>
 		<string>remote-notification</string>
+		<string>location</string>
+        <string>fetch</string>
 	</array>
 </dict>
 </plist>

Sources/KlaviyoCore/Networking/KlaviyoEndpoint.swift

@@ -17,7 +17,7 @@ public enum KlaviyoEndpoint: Equatable, Codable {
     case aggregateEvent(_ apiKey: String, _ payload: AggregateEventPayload)
     case resolveDestinationURL(trackingLink: URL, profileInfo: ProfilePayload)
     case logTrackingLinkClicked(trackingLink: URL, clickTime: Date, profileInfo: ProfilePayload)
-    case fetchGeofences
+    case fetchGeofences(_ apiKey: String)
 
     private enum HeaderKey {
         static let profileInfo = "X-Klaviyo-Profile-Info"
@@ -50,9 +50,10 @@ public enum KlaviyoEndpoint: Equatable, Codable {
              let .createEvent(apiKey, _),
              let .registerPushToken(apiKey, _),
              let .unregisterPushToken(apiKey, _),
-             let .aggregateEvent(apiKey, _):
+             let .aggregateEvent(apiKey, _),
+             let .fetchGeofences(apiKey):
             return [URLQueryItem(name: "company_id", value: apiKey)]
-        case .resolveDestinationURL, .logTrackingLinkClicked, .fetchGeofences:
+        case .resolveDestinationURL, .logTrackingLinkClicked:
             return []
         }
     }
@@ -114,7 +115,7 @@ public enum KlaviyoEndpoint: Equatable, Codable {
         case let .resolveDestinationURL(trackingLink, _), let .logTrackingLinkClicked(trackingLink, _, _):
             return trackingLink.path
         case .fetchGeofences:
-            return "/geofences"
+            return "/client/geofences"
         }
     }
 

Sources/KlaviyoCore/Networking/NetworkSession.swift

@@ -28,7 +28,7 @@ public struct NetworkSession {
         self.data = data
     }
 
-    fileprivate static let currentApiRevision = "2025-07-15"
+    fileprivate static let currentApiRevision = "2025-10-15.pre"
     fileprivate static let applicationJson = "application/json"
     fileprivate static let acceptedEncodings = ["br", "gzip", "deflate"]
     fileprivate static let mobileHeader = "1"

Sources/KlaviyoLocation/GeofenceService.swift

@@ -10,12 +10,12 @@ import KlaviyoCore
 import KlaviyoSwift
 import OSLog
 
-internal protocol GeofenceServiceProvider {
+protocol GeofenceServiceProvider {
     func fetchGeofences() async -> Set<Geofence>
 }
 
-internal struct GeofenceService: GeofenceServiceProvider {
-    internal func fetchGeofences() async -> Set<Geofence> {
+struct GeofenceService: GeofenceServiceProvider {
+    func fetchGeofences() async -> Set<Geofence> {
         do {
             let data = try await fetchGeofenceData()
             return try await parseGeofences(from: data)
@@ -29,36 +29,28 @@ internal struct GeofenceService: GeofenceServiceProvider {
 
     /// Fetches raw geofence data from the API
     private func fetchGeofenceData() async throws -> Data {
-        // FIXME: Temporarily override the environment's API URL for this mock request
-        let originalAPIURL = environment.apiURL
-        environment.apiURL = {
-            var components = URLComponents()
-            components.scheme = "https"
-            components.host = "mock-api.com"
-            return components
-        }
-
-        let endpoint = KlaviyoEndpoint.fetchGeofences
+        let apiKey = try await KlaviyoInternal.fetchAPIKey()
+        let endpoint = KlaviyoEndpoint.fetchGeofences(apiKey)
         let klaviyoRequest = KlaviyoRequest(endpoint: endpoint)
         let attemptInfo = try RequestAttemptInfo(attemptNumber: 1, maxAttempts: 1)
         let result = await environment.klaviyoAPI.send(klaviyoRequest, attemptInfo)
 
-        // FIXME: Restore the original API URL
-        environment.apiURL = originalAPIURL
-
         switch result {
         case let .success(data):
+            if #available(iOS 14.0, *) {
+                Logger.geoservices.info("Successfully fetched geofences")
+            }
             return data
         case let .failure(error):
             if #available(iOS 14.0, *) {
-                Logger.geoservices.error("Failed to fetch geofences from mock endpoint https://mock-api.com/geofences")
+                Logger.geoservices.error("Failed to fetch geofences; error: \(error, privacy: .public)")
             }
             throw error
         }
     }
 
     /// Parses raw geofence data and transforms it into Geofence objects with the companyId prepended to the id
-    internal func parseGeofences(from data: Data) async throws -> Set<Geofence> {
+    func parseGeofences(from data: Data) async throws -> Set<Geofence> {
         do {
             let response = try JSONDecoder().decode(GeofenceJSONResponse.self, from: data)
             let companyId = try await KlaviyoInternal.fetchAPIKey()

Sources/KlaviyoLocation/KlaviyoGeofenceManager.swift

@@ -7,16 +7,17 @@
 
 import CoreLocation
 import KlaviyoCore
+import KlaviyoSwift
 import OSLog
 
-internal class KlaviyoGeofenceManager {
+class KlaviyoGeofenceManager {
     private let locationManager: LocationManagerProtocol
 
-    internal init(locationManager: LocationManagerProtocol) {
+    init(locationManager: LocationManagerProtocol) {
         self.locationManager = locationManager
     }
 
-    internal func setupGeofencing() {
+    func setupGeofencing() {
         guard CLLocationManager.isMonitoringAvailable(for: CLCircularRegion.self) else {
             if #available(iOS 14.0, *) {
                 Logger.geoservices.warning("Geofencing is not supported on this device")
@@ -32,11 +33,18 @@ internal class KlaviyoGeofenceManager {
         }
 
         Task {
+            guard let _ = try? await KlaviyoInternal.fetchAPIKey() else {
+                if #available(iOS 14.0, *) {
+                    Logger.geoservices.info("SDK is not initialized, skipping geofence refresh")
+                }
+                return
+            }
+
             await updateGeofences()
         }
     }
 
-    internal func destroyGeofencing() {
+    func destroyGeofencing() {
         if #available(iOS 14.0, *) {
             if !locationManager.monitoredRegions.isEmpty {
                 Logger.geoservices.info("Stop monitoring for all regions")
@@ -85,3 +93,32 @@ internal class KlaviyoGeofenceManager {
         }
     }
 }
+
+// MARK: Data Type Conversions
+
+extension Geofence {
+    /// Converts this geofence to a Core Location circular region
+    /// - Returns: A CLCircularRegion instance
+    func toCLCircularRegion() -> CLCircularRegion {
+        let region = CLCircularRegion(
+            center: CLLocationCoordinate2D(latitude: latitude, longitude: longitude),
+            radius: radius,
+            identifier: id
+        )
+        return region
+    }
+}
+
+extension CLCircularRegion {
+    func toKlaviyoGeofence() throws -> Geofence {
+        try Geofence(id: identifier, longitude: center.longitude, latitude: center.latitude, radius: radius)
+    }
+
+    var klaviyoLocationId: String? {
+        do {
+            return try toKlaviyoGeofence().locationId
+        } catch {
+            return nil
+        }
+    }
+}

Sources/KlaviyoLocation/KlaviyoLocationManager.swift

@@ -12,20 +12,20 @@ import KlaviyoCore
 import KlaviyoSwift
 import OSLog
 
-public class KlaviyoLocationManager: NSObject {
+class KlaviyoLocationManager: NSObject {
     static let shared = KlaviyoLocationManager()
 
     private var locationManager: LocationManagerProtocol
     private let geofenceManager: KlaviyoGeofenceManager
-    private let geofencePublisher: PassthroughSubject<String, Never> = .init()
 
-    internal init(locationManager: LocationManagerProtocol? = nil, geofenceManager: KlaviyoGeofenceManager? = nil) {
+    init(locationManager: LocationManagerProtocol? = nil, geofenceManager: KlaviyoGeofenceManager? = nil) {
         self.locationManager = locationManager ?? CLLocationManager()
         self.geofenceManager = geofenceManager ?? KlaviyoGeofenceManager(locationManager: self.locationManager)
 
         super.init()
         self.locationManager.delegate = self
         self.locationManager.allowsBackgroundLocationUpdates = true
+        self.locationManager.startMonitoringSignificantLocationChanges()
     }
 
     deinit {
@@ -36,14 +36,14 @@ public class KlaviyoLocationManager: NSObject {
     }
 
     @MainActor
-    internal func setupGeofencing() {
+    func setupGeofencing() {
         if environment.getLocationAuthorizationStatus() == .authorizedAlways {
             geofenceManager.setupGeofencing()
         }
     }
 
     @MainActor
-    internal func destroyGeofencing() {
+    func destroyGeofencing() {
         geofenceManager.destroyGeofencing()
     }
 }
@@ -90,43 +90,53 @@ extension KlaviyoLocationManager: CLLocationManagerDelegate {
     // MARK: Geofencing
 
     public func locationManager(_ manager: CLLocationManager, didEnterRegion region: CLRegion) {
-        guard let region = region as? CLCircularRegion else { return }
+        guard let region = region as? CLCircularRegion,
+              let klaviyoLocationId = region.klaviyoLocationId else {
+            if #available(iOS 14.0, *) {
+                Logger.geoservices.info("Received non-Klaviyo geofence notification. Skipping.")
+            }
+            return
+        }
         if #available(iOS 14.0, *) {
-            Logger.geoservices.info("🌎 User entered region \"\(region.identifier)\"")
+            Logger.geoservices.info("🌎 User entered region \"\(klaviyoLocationId, privacy: .public)\"")
         }
 
         let enterEvent = Event(
-            name: .locationEvent(.enteredBoundary),
+            name: .locationEvent(.geofenceEnter),
             properties: [
-                "boundaryIdentifier": region.identifier
+                "geofence_id": klaviyoLocationId
             ]
         )
 
         Task {
             await MainActor.run {
                 KlaviyoInternal.create(event: enterEvent)
-                geofencePublisher.send("Entered \(region.identifier)")
             }
         }
     }
 
     public func locationManager(_ manager: CLLocationManager, didExitRegion region: CLRegion) {
-        guard let region = region as? CLCircularRegion else { return }
+        guard let region = region as? CLCircularRegion,
+              let klaviyoLocationId = region.klaviyoLocationId else {
+            if #available(iOS 14.0, *) {
+                Logger.geoservices.warning("Received non-Klaviyo geofence notification. Skipping.")
+            }
+            return
+        }
         if #available(iOS 14.0, *) {
-            Logger.geoservices.info("🌎 User exited region \"\(region.identifier)\"")
+            Logger.geoservices.info("🌎 User exited region \"\(klaviyoLocationId, privacy: .public)\"")
         }
 
         let exitEvent = Event(
-            name: .locationEvent(.exitedBoundary),
+            name: .locationEvent(.geofenceExit),
             properties: [
-                "boundaryIdentifier": region.identifier
+                "geofence_id": klaviyoLocationId
             ]
         )
 
         Task {
             await MainActor.run {
                 KlaviyoInternal.create(event: exitEvent)
-                geofencePublisher.send("Exited \(region.identifier)")
             }
         }
     }

Sources/KlaviyoLocation/KlaviyoSDK+Location.swift

@@ -5,6 +5,7 @@
 //  Created by Isobelle Lim on 8/27/25.
 //
 
+import CoreLocation
 import Foundation
 import KlaviyoSwift
 
@@ -20,6 +21,11 @@ extension KlaviyoSDK {
         }
     }
 
+    /// To be called in didFinishLaunchingWithOptions to ensure geofence events that happen in a backgrounded/terminated state are processed.
+    public func monitorGeofencesFromBackground() {
+        _ = KlaviyoLocationManager.shared
+    }
+
     /// Unregisters app for geofencing. Stops monitoring for geofences and cleans up resources.
     @MainActor
     public func unregisterGeofencing() {