https://github.com/livotovlabs/anchor
Anchor is a native, Kotlin-first background geolocation library for Kotlin Multiplatform, designed for high performance and seamless integration in modern Android and iOS applications.
https://github.com/livotovlabs/anchor
android-library geolocation geolocation-tracking ios kmp kmp-library kotlin-multiplatform kotlin-multiplatform-library location location-services location-tracker
Last synced: 4 months ago
JSON representation
Anchor is a native, Kotlin-first background geolocation library for Kotlin Multiplatform, designed for high performance and seamless integration in modern Android and iOS applications.
- Host: GitHub
- URL: https://github.com/livotovlabs/anchor
- Owner: LivotovLabs
- License: apache-2.0
- Created: 2025-12-11T18:36:36.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-02-02T17:40:49.000Z (4 months ago)
- Last Synced: 2026-02-03T03:19:14.507Z (4 months ago)
- Topics: android-library, geolocation, geolocation-tracking, ios, kmp, kmp-library, kotlin-multiplatform, kotlin-multiplatform-library, location, location-services, location-tracker
- Language: Kotlin
- Homepage: https://anchorkmp.io
- Size: 1.16 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
⚓️ Anchor
Background Geolocation for Kotlin Multiplatform
Reliable. Battery-Conscious. Native Performance.
[](https://central.sonatype.com/artifact/io.anchorkmp/core)
[](https://opensource.org/licenses/Apache-2.0)
[](https://anchorkmp.io)
[](https://github.com/LivotovLabs/anchor)
> **Anchor** is a native, Kotlin-first background geolocation library for **Kotlin Multiplatform**, designed for high performance and seamless integration in modern Android and iOS applications.
>
> ⚠️ **Note:** The product is currently in its final stages of development and testing. The official **v1.0 release** is expected during **February 2026**.
---
## ✨ Features
- 🔋 **Always Background:** Architected specifically for reliable, long-running background tracking.
- 🎯 **Platform Tuned:** Granular control over Android Priority/Interval and iOS Accuracy/Activity Type.
- 🚀 **Modern API:** Built with Kotlin DSL, Coroutines, and Flow.
- 📱 **Cross-Platform:** Single shared API for Android and iOS.
---
## 📦 Installation
Add the dependency to your `commonMain` source set in `build.gradle.kts`:
```kotlin
commonMain.dependencies {
implementation("io.anchorkmp:core:0.0.1")
}
```
---
## 🛠 Platform Setup
🤖 Android Setup
No manual initialization code is required. However, you must declare the foreground service type in your manifest if you are targeting Android 14+.
The library automatically includes the following permissions:
- `ACCESS_COARSE_LOCATION`
- `ACCESS_FINE_LOCATION`
- `ACCESS_BACKGROUND_LOCATION`
- `FOREGROUND_SERVICE_LOCATION`
- `POST_NOTIFICATIONS`
- `ACTIVITY_RECOGNITION`
🍎 iOS Setup
Add the following keys to your `Info.plist` (typically in `iosApp/iosApp/Info.plist`):
```xml
NSLocationWhenInUseUsageDescription
We need your location to track your journey.
NSLocationAlwaysAndWhenInUseUsageDescription
We need your location to track your journey even in the background.
NSLocationAlwaysUsageDescription
We need your location to track your journey even in the background.
NSMotionUsageDescription
We need access to motion data to detect if you are walking, running, or driving.
UIBackgroundModes
location
fetch
processing
```
---
## 🚀 Quick Start
### 1. Configuration
Initialize Anchor in your application startup logic.
```kotlin
import io.anchorkmp.core.*
import kotlin.time.Duration.Companion.seconds
val config = AnchorConfig.build {
// Shared Options
trackActivity = true // Enable activity recognition (walking, driving, etc.)
minUpdateDistanceMeters = 10.0 // Minimum distance before an update is triggered
// Android Specifics
android {
updateInterval = 10.seconds // Desired frequency of updates
priority = AndroidPriority.BALANCED // Balance between battery and accuracy
notification {
title = "Tracking Active" // Persistent notification title
body = "Location tracking is on" // Persistent notification body
iconName = "ic_tracker" // Drawable resource name
}
}
// iOS Specifics
ios {
desiredAccuracy = IosAccuracy.BEST // kCLLocationAccuracyBest
autoPause = true // Allow system to pause updates to save battery
activityType = IosActivityType.OTHER // CLActivityType
displayBackgroundLocationIndicator = true // Show blue pill in status bar
}
}
Anchor.init(config)
```
### 2. Permissions & Tracking
Anchor provides a simple coroutine-based API for permission management.
```kotlin
scope.launch {
// 1. Request permissions (suspends until user decides)
// Suggest asking for Notifications & Motion first
Anchor.requestPermission(PermissionScope.NOTIFICATIONS)
Anchor.requestPermission(PermissionScope.MOTION)
// 2. Request Background Location
val status = Anchor.requestPermission(PermissionScope.BACKGROUND)
if (status == PermissionStatus.GRANTED) {
// 3. Start Tracking
Anchor.startTracking()
} else {
println("Permission denied")
}
}
```
### 3. Observe Updates
```kotlin
scope.launch {
Anchor.locationFlow.collect { location ->
println("📍 Location: ${location.latitude}, ${location.longitude}")
println("🏃 Activity: ${location.activity}")
}
}
```
---
## 📱 Demo Application
Check out the `sample/` directory for a complete Compose Multiplatform app demonstrating background tracking and native maps.
### Running on Android
1. Create `local.properties` in the project root.
2. Add your Google Maps API Key: `MAPS_API_KEY=AIzaSy...`
3. Run: `./gradlew :sample:composeApp:installDebug`
### Running on iOS
1. Open `sample/iosApp/iosApp.xcodeproj` in Xcode.
2. Select your target device and run. (Uses native Apple Maps, no key required).
---