react-native-nitro-background-geolocation 0.1.0

package/NitroBackgroundGeolocation.podspec

@@ -0,0 +1,29 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NitroBackgroundGeolocation"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/atoui-zahreddine/react-native-nitro-background-geolocation.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/**/*.{swift,h,m,mm}",
+    "cpp/**/*.{hpp,cpp}",
+  ]
+  s.public_header_files = "ios/common/BackgroundGeolocation/**/*.h"
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+
+  load 'nitrogen/generated/ios/NitroBackgroundGeolocation+autolinking.rb'
+  add_nitrogen_files(s)
+
+  install_modules_dependencies(s)
+end

package/android/CMakeLists.txt

@@ -0,0 +1,24 @@
+project(nitrobackgroundgeolocation)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME nitrobackgroundgeolocation)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED src/main/cpp/cpp-adapter.cpp)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/nitrobackgroundgeolocation+autolinking.cmake)
+
+# Set up local includes
+include_directories("src/main/cpp" "../cpp")
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,133 @@
+buildscript {
+  ext.NitroBackgroundGeolocation = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return NitroBackgroundGeolocation[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply from: '../nitrogen/generated/android/nitrobackgroundgeolocation+autolinking.gradle'
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.margelo.nitro.nitrobackgroundgeolocation"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+      "META-INF",
+      "META-INF/**",
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libfolly_json.so",
+      "**/libfolly_runtime.so",
+      "**/libglog.so",
+      "**/libhermes.so",
+      "**/libhermes-executor-debug.so",
+      "**/libhermes_executor.so",
+      "**/libreactnative.so",
+      "**/libreactnativejni.so",
+      "**/libturbomodulejsijni.so",
+      "**/libreact_nativemodule_core.so",
+      "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+repositories {
+  maven { url 'https://jitpack.io' }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation project(":react-native-nitro-modules")
+
+  // Background geolocation native dependencies
+  implementation "com.google.android.gms:play-services-location:21.3.0"
+  implementation "com.github.tony19:logback-android:2.0.1"
+  implementation "org.slf4j:slf4j-api:1.7.36"
+  implementation "androidx.appcompat:appcompat:1.7.0"
+  implementation "androidx.lifecycle:lifecycle-process:2.8.7"
+  implementation("io.github.nishkarsh:android-permissions:2.1.8") {
+    exclude group: 'com.android.support', module: 'appcompat-v7'
+  }
+  implementation "com.github.jparkie:promise:1.0.3"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,65 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+    <uses-permission android:name="android.permission.AUTHENTICATE_ACCOUNTS" />
+    <uses-permission android:name="android.permission.READ_SYNC_SETTINGS" />
+    <uses-permission android:name="android.permission.WRITE_SYNC_SETTINGS" />
+    <uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" />
+    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
+
+    <uses-feature android:name="android.hardware.location" android:required="false" />
+
+    <application>
+        <service
+            android:name="com.marianhello.bgloc.sync.SyncService"
+            android:exported="true"
+            android:process=":sync">
+            <intent-filter>
+                <action android:name="android.content.SyncAdapter"/>
+            </intent-filter>
+            <meta-data android:name="android.content.SyncAdapter"
+                android:resource="@xml/syncadapter"/>
+        </service>
+        <service
+            android:name="com.marianhello.bgloc.sync.AuthenticatorService"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="android.accounts.AccountAuthenticator"/>
+            </intent-filter>
+            <meta-data
+                android:name="android.accounts.AccountAuthenticator"
+                android:resource="@xml/authenticator" />
+        </service>
+        <provider
+            android:name="com.marianhello.bgloc.data.provider.LocationContentProvider"
+            android:authorities="${applicationId}.bgloc.provider"
+            android:exported="false"
+            android:syncable="true"/>
+        <service
+            android:name="com.marianhello.bgloc.service.LocationServiceImpl"
+            android:enabled="true"
+            android:exported="false"
+            android:foregroundServiceType="location" />
+        <receiver
+            android:name="com.marianhello.bgloc.BootCompletedReceiver"
+            android:enabled="true"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.BOOT_COMPLETED" />
+            </intent-filter>
+        </receiver>
+        <service
+            android:name="com.margelo.nitro.nitrobackgroundgeolocation.HeadlessTaskService"
+            android:enabled="true"
+            android:exported="false" />
+    </application>
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,11 @@
+#include <jni.h>
+#include "nitrobackgroundgeolocationOnLoad.hpp"
+
+#include <fbjni/fbjni.h>
+
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return facebook::jni::initialize(vm, []() {
+    margelo::nitro::nitrobackgroundgeolocation::registerAllNatives();
+  });
+}

package/android/src/main/java/com/margelo/nitro/nitrobackgroundgeolocation/ConfigMapper.kt

@@ -0,0 +1,332 @@
+package com.margelo.nitro.nitrobackgroundgeolocation
+
+import com.marianhello.bgloc.Config
+import com.marianhello.bgloc.data.BackgroundActivity
+import com.marianhello.bgloc.data.BackgroundLocation
+import com.marianhello.bgloc.data.HashMapLocationTemplate
+import com.marianhello.bgloc.data.LocationTemplateFactory
+import com.margelo.nitro.core.AnyMap
+import java.util.HashMap
+
+/**
+ * Maps between Nitrogen-generated data classes and the Java facade types.
+ */
+object ConfigMapper {
+
+    /**
+     * Apply a Nitrogen [ConfigureOptions] struct to a resolved Java [Config].
+     * Omitted fields are left unchanged, explicit `null` resets to defaults, and
+     * iOS-only fields are ignored on Android.
+     */
+        val defaults = Config.getDefault()
+    fun applyNativeConfig(config: Config, options: ConfigureOptions) {
+        applyDouble(options.stationaryRadius, onValue = { config.setStationaryRadius(it.toFloat()) }, onNull = {
+            config.setStationaryRadius(defaults.stationaryRadius ?: 50f)
+        })
+        applyDouble(options.distanceFilter, onValue = { config.setDistanceFilter(it.toInt()) }, onNull = {
+            config.setDistanceFilter(defaults.distanceFilter)
+        })
+        applyLocationAccuracy(options.desiredAccuracy, onValue = { config.setDesiredAccuracy(it.value) }, onNull = {
+            config.setDesiredAccuracy(defaults.desiredAccuracy)
+        })
+        applyBoolean(options.debug, onValue = { config.setDebugging(it) }, onNull = {
+            config.setDebugging(defaults.isDebugging)
+        })
+        applyBoolean(options.stopOnTerminate, onValue = { config.setStopOnTerminate(it) }, onNull = {
+            config.setStopOnTerminate(defaults.stopOnTerminate)
+        })
+        applyBoolean(options.startOnBoot, onValue = { config.setStartOnBoot(it) }, onNull = {
+            config.setStartOnBoot(defaults.startOnBoot)
+        })
+        applyBoolean(options.startForeground, onValue = { config.setStartForeground(it) }, onNull = {
+            config.setStartForeground(defaults.startForeground)
+        })
+        applyBoolean(options.notificationsEnabled, onValue = { config.setNotificationsEnabled(it) }, onNull = {
+            config.setNotificationsEnabled(defaults.notificationsEnabled)
+        })
+        applyLocationProvider(options.locationProvider, onValue = { config.setLocationProvider(it.value) }, onNull = {
+            config.setLocationProvider(defaults.locationProvider)
+        })
+        applyDouble(options.interval, onValue = { config.setInterval(it.toInt()) }, onNull = {
+            config.setInterval(defaults.interval)
+        })
+        applyDouble(options.fastestInterval, onValue = { config.setFastestInterval(it.toInt()) }, onNull = {
+            config.setFastestInterval(defaults.fastestInterval)
+        })
+        applyDouble(options.activitiesInterval, onValue = { config.setActivitiesInterval(it.toInt()) }, onNull = {
+            config.setActivitiesInterval(defaults.activitiesInterval)
+        })
+        applyBoolean(options.stopOnStillActivity, onValue = { config.setStopOnStillActivity(it) }, onNull = {
+            config.setStopOnStillActivity(defaults.stopOnStillActivity)
+        })
+        applyString(options.notificationTitle, onValue = { config.setNotificationTitle(it) }, onNull = {
+            config.setNotificationTitle(defaults.notificationTitle)
+        })
+        applyString(options.notificationText, onValue = { config.setNotificationText(it) }, onNull = {
+            config.setNotificationText(defaults.notificationText)
+        })
+        applyString(options.notificationIconColor, onValue = { config.setNotificationIconColor(it) }, onNull = {
+            config.setNotificationIconColor(defaults.notificationIconColor)
+        })
+        applyString(options.notificationIconLarge, onValue = { config.setLargeNotificationIcon(it) }, onNull = {
+            config.setLargeNotificationIcon(defaults.largeNotificationIcon)
+        })
+        applyString(options.notificationIconSmall, onValue = { config.setSmallNotificationIcon(it) }, onNull = {
+            config.setSmallNotificationIcon(defaults.smallNotificationIcon)
+        })
+        applyString(options.url, onValue = { config.setUrl(it) }, onNull = {
+            config.setUrl(defaults.url)
+        })
+        applyString(options.syncUrl, onValue = { config.setSyncUrl(it) }, onNull = {
+            config.setSyncUrl(defaults.syncUrl)
+        })
+        applyDouble(options.syncThreshold, onValue = { config.setSyncThreshold(it.toInt()) }, onNull = {
+            config.setSyncThreshold(defaults.syncThreshold)
+        })
+        applyHeaders(options.httpHeaders, onValue = { config.setHttpHeaders(HashMap(it)) }, onNull = {
+            config.setHttpHeaders(null as HashMap<String, String>?)
+        })
+        applyDouble(options.maxLocations, onValue = { config.setMaxLocations(it.toInt()) }, onNull = {
+            config.setMaxLocations(defaults.maxLocations)
+        })
+        applyAnyMap(options.postTemplate, onValue = {
+            config.setTemplate(LocationTemplateFactory.fromHashMap(it.toHashMap()))
+        }, onNull = {
+            config.setTemplate(null)
+        })
+    }
+
+    /**
+     * Convert a Java [Config] back to a Nitrogen [ConfigureOptions].
+     */
+    fun toJsConfig(config: Config): ConfigureOptions {
+        return ConfigureOptions(
+            locationProvider = config.locationProvider?.let { Variant_NullType_LocationProvider.Second(intToLocationProvider(it)) },
+            desiredAccuracy = config.desiredAccuracy?.let { Variant_NullType_LocationAccuracy.Second(intToLocationAccuracy(it)) },
+            stationaryRadius = config.stationaryRadius?.toDouble()?.let { Variant_NullType_Double.Second(it) },
+            debug = Variant_NullType_Boolean.Second(config.isDebugging),
+            distanceFilter = config.distanceFilter?.toDouble()?.let { Variant_NullType_Double.Second(it) },
+            stopOnTerminate = config.stopOnTerminate?.let { Variant_NullType_Boolean.Second(it) },
+            startOnBoot = config.startOnBoot?.let { Variant_NullType_Boolean.Second(it) },
+            interval = config.interval?.toDouble()?.let { Variant_NullType_Double.Second(it) },
+            fastestInterval = config.fastestInterval?.toDouble()?.let { Variant_NullType_Double.Second(it) },
+            activitiesInterval = config.activitiesInterval?.toDouble()?.let { Variant_NullType_Double.Second(it) },
+            stopOnStillActivity = config.stopOnStillActivity?.let { Variant_NullType_Boolean.Second(it) },
+            notificationsEnabled = config.notificationsEnabled?.let { Variant_NullType_Boolean.Second(it) },
+            startForeground = config.startForeground?.let { Variant_NullType_Boolean.Second(it) },
+            notificationTitle = config.notificationTitle?.let { Variant_NullType_String.Second(it) },
+            notificationText = config.notificationText?.let { Variant_NullType_String.Second(it) },
+            notificationIconColor = config.notificationIconColor?.let { Variant_NullType_String.Second(it) },
+            notificationIconLarge = config.largeNotificationIcon?.let { Variant_NullType_String.Second(it) },
+            notificationIconSmall = config.smallNotificationIcon?.let { Variant_NullType_String.Second(it) },
+            activityType = null,             // iOS-only
+            pauseLocationUpdates = null,     // iOS-only
+            saveBatteryOnBackground = null,  // iOS-only
+            url = config.url?.let { Variant_NullType_String.Second(it) },
+            syncUrl = config.syncUrl?.let { Variant_NullType_String.Second(it) },
+            syncThreshold = config.syncThreshold?.toDouble()?.let { Variant_NullType_Double.Second(it) },
+            httpHeaders = config.httpHeaders?.let { headers ->
+                @Suppress("UNCHECKED_CAST")
+                (headers as? HashMap<String, String>)?.toMap()?.let { Variant_NullType_Map_String__String_.Second(it) }
+            } ?: null,
+            maxLocations = config.maxLocations?.toDouble()?.let { Variant_NullType_Double.Second(it) },
+            postTemplate = extractPostTemplate(config)?.let { Variant_NullType_AnyMap.Second(it) }
+        )
+    }
+
+    /**
+     * Convert a [BackgroundLocation] to a Nitrogen [Location] struct.
+     */
+    fun toJsLocation(location: BackgroundLocation): Location {
+        return Location(
+            id = (location.locationId ?: 0L).toDouble(),
+            provider = location.provider ?: "",
+            locationProvider = (location.locationProvider ?: 0).toDouble(),
+            time = location.time.toDouble(),
+            latitude = location.latitude,
+            longitude = location.longitude,
+            accuracy = location.accuracy.toDouble(),
+            speed = location.speed.toDouble(),
+            altitude = location.altitude,
+            altitudeAccuracy = locationAltitudeAccuracy(location),
+            bearing = location.bearing.toDouble(),
+            isFromMockProvider = location.isFromMockProvider,
+            mockLocationsEnabled = location.areMockLocationsEnabled()
+        )
+    }
+
+    /**
+     * Convert a [BackgroundLocation] to a Nitrogen [StationaryLocation] struct.
+     */
+    fun toJsStationaryLocation(location: BackgroundLocation): StationaryLocation {
+        return StationaryLocation(
+            id = (location.locationId ?: 0L).toDouble(),
+            provider = location.provider ?: "",
+            locationProvider = (location.locationProvider ?: 0).toDouble(),
+            time = location.time.toDouble(),
+            latitude = location.latitude,
+            longitude = location.longitude,
+            accuracy = location.accuracy.toDouble(),
+            speed = location.speed.toDouble(),
+            altitude = location.altitude,
+            altitudeAccuracy = locationAltitudeAccuracy(location),
+            bearing = location.bearing.toDouble(),
+            isFromMockProvider = location.isFromMockProvider,
+            mockLocationsEnabled = location.areMockLocationsEnabled(),
+            radius = location.radius.toDouble()
+        )
+    }
+
+    /**
+     * Convert a [BackgroundActivity] to a Nitrogen [Activity] struct.
+     */
+    fun toJsActivity(activity: BackgroundActivity): Activity {
+        return Activity(
+            confidence = activity.confidence.toDouble(),
+            type = BackgroundActivity.getActivityString(activity.type)
+        )
+    }
+
+    /**
+     * Convert a Java [com.marianhello.logging.LogEntry] to a Nitrogen [LogEntry] struct.
+     */
+    fun toJsLogEntry(entry: com.marianhello.logging.LogEntry): LogEntry {
+        return LogEntry(
+            id = (entry.id ?: 0).toDouble(),
+            timestamp = (entry.timestamp ?: 0L).toDouble(),
+            level = entry.level ?: "",
+            message = entry.message ?: "",
+            stackTrace = entry.stackTrace ?: ""
+        )
+    }
+
+    // ---- private helpers ----
+
+    private fun intToLocationAccuracy(value: Int): LocationAccuracy {
+        return when (value) {
+            0 -> LocationAccuracy.HIGH
+            100 -> LocationAccuracy.MEDIUM
+            1000 -> LocationAccuracy.LOW
+            10000 -> LocationAccuracy.PASSIVE
+            else -> LocationAccuracy.MEDIUM
+        }
+    }
+
+    private fun intToLocationProvider(value: Int): LocationProvider {
+        return when (value) {
+            0 -> LocationProvider.DISTANCE_FILTER
+            1 -> LocationProvider.ACTIVITY
+            2 -> LocationProvider.RAW
+            else -> LocationProvider.DISTANCE_FILTER
+        }
+    }
+
+    @Suppress("UNCHECKED_CAST")
+    private fun extractPostTemplate(config: Config): AnyMap? {
+        if (!config.hasTemplate()) return null
+        val template = config.template
+        if (template is HashMapLocationTemplate) {
+            val map = template.toMap() as? Map<*, *> ?: return null
+            val result = mutableMapOf<String, Any?>()
+            for ((key, value) in map) {
+                if (key is String) {
+                    result[key] = value
+                }
+            }
+            return AnyMap.fromMap(result, false)
+        }
+        return null
+    }
+
+    private fun locationAltitudeAccuracy(location: BackgroundLocation): Double {
+        return if (location.hasVerticalAccuracy()) {
+            location.verticalAccuracy.toDouble()
+        } else {
+            0.0
+        }
+    }
+
+    private inline fun applyString(
+        option: Variant_NullType_String?,
+        onValue: (String) -> Unit,
+        onNull: () -> Unit
+    ) {
+        when (option) {
+            null -> Unit
+            is Variant_NullType_String.First -> onNull()
+            is Variant_NullType_String.Second -> onValue(option.value)
+        }
+    }
+
+    private inline fun applyDouble(
+        option: Variant_NullType_Double?,
+        onValue: (Double) -> Unit,
+        onNull: () -> Unit
+    ) {
+        when (option) {
+            null -> Unit
+            is Variant_NullType_Double.First -> onNull()
+            is Variant_NullType_Double.Second -> onValue(option.value)
+        }
+    }
+
+    private inline fun applyBoolean(
+        option: Variant_NullType_Boolean?,
+        onValue: (Boolean) -> Unit,
+        onNull: () -> Unit
+    ) {
+        when (option) {
+            null -> Unit
+            is Variant_NullType_Boolean.First -> onNull()
+            is Variant_NullType_Boolean.Second -> onValue(option.value)
+        }
+    }
+
+    private inline fun applyHeaders(
+        option: Variant_NullType_Map_String__String_?,
+        onValue: (Map<String, String>) -> Unit,
+        onNull: () -> Unit
+    ) {
+        when (option) {
+            null -> Unit
+            is Variant_NullType_Map_String__String_.First -> onNull()
+            is Variant_NullType_Map_String__String_.Second -> onValue(option.value)
+        }
+    }
+
+    private inline fun applyAnyMap(
+        option: Variant_NullType_AnyMap?,
+        onValue: (AnyMap) -> Unit,
+        onNull: () -> Unit
+    ) {
+        when (option) {
+            null -> Unit
+            is Variant_NullType_AnyMap.First -> onNull()
+            is Variant_NullType_AnyMap.Second -> onValue(option.value)
+        }
+    }
+
+    private inline fun applyLocationProvider(
+        option: Variant_NullType_LocationProvider?,
+        onValue: (LocationProvider) -> Unit,
+        onNull: () -> Unit
+    ) {
+        when (option) {
+            null -> Unit
+            is Variant_NullType_LocationProvider.First -> onNull()
+            is Variant_NullType_LocationProvider.Second -> onValue(option.value)
+        }
+    }
+
+    private inline fun applyLocationAccuracy(
+        option: Variant_NullType_LocationAccuracy?,
+        onValue: (LocationAccuracy) -> Unit,
+        onNull: () -> Unit
+    ) {
+        when (option) {
+            null -> Unit
+            is Variant_NullType_LocationAccuracy.First -> onNull()
+            is Variant_NullType_LocationAccuracy.Second -> onValue(option.value)
+        }
+    }
+}

package/android/src/main/java/com/margelo/nitro/nitrobackgroundgeolocation/HeadlessTaskRegistry.kt

@@ -0,0 +1,23 @@
+package com.margelo.nitro.nitrobackgroundgeolocation
+
+import android.content.Context
+
+internal object HeadlessTaskRegistry {
+    private const val PREFS_NAME = "NitroBackgroundGeolocation"
+    private const val KEY_TASK_NAME = "headlessTaskName"
+
+    @JvmStatic
+    fun setTaskName(context: Context, taskName: String?) {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            .edit()
+            .putString(KEY_TASK_NAME, taskName?.takeIf { it.isNotBlank() })
+            .apply()
+    }
+
+    @JvmStatic
+    fun getTaskName(context: Context): String? {
+        return context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            .getString(KEY_TASK_NAME, null)
+            ?.takeIf { it.isNotBlank() }
+    }
+}

package/android/src/main/java/com/margelo/nitro/nitrobackgroundgeolocation/HeadlessTaskService.kt

@@ -0,0 +1,66 @@
+package com.margelo.nitro.nitrobackgroundgeolocation
+
+import android.content.Context
+import android.content.Intent
+import com.facebook.react.HeadlessJsTaskService
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.jstasks.HeadlessJsTaskConfig
+
+/**
+ * A service that allows background JS execution for geolocation events
+ * when the React Activity is not in the foreground.
+ *
+ * It receives the headless task name, event name, and serialized event params
+ * via intent extras and delegates execution to React Native's HeadlessJsTaskService.
+ */
+class HeadlessTaskService : HeadlessJsTaskService() {
+
+    override fun getTaskConfig(intent: Intent?): HeadlessJsTaskConfig? {
+        val extras = intent?.extras ?: return null
+
+        val taskName = extras.getString(EXTRA_TASK_NAME) ?: return null
+        val eventName = extras.getString(EXTRA_EVENT_NAME) ?: ""
+        val eventParams = extras.getString(EXTRA_EVENT_PARAMS) ?: "{}"
+
+        val eventData = Arguments.createMap().apply {
+            putString("event", eventName)
+            putString("params", eventParams)
+        }
+
+        return HeadlessJsTaskConfig(
+            taskName,
+            eventData,
+            TASK_TIMEOUT_MS,
+            ALLOW_FOREGROUND
+        )
+    }
+
+    companion object {
+        private const val EXTRA_TASK_NAME = "taskName"
+        private const val EXTRA_EVENT_NAME = "eventName"
+        private const val EXTRA_EVENT_PARAMS = "eventParams"
+        private const val TASK_TIMEOUT_MS = 30000L
+        private const val ALLOW_FOREGROUND = true
+
+        /**
+         * Creates an Intent that can be used to start the [HeadlessTaskService].
+         *
+         * @param context Android context
+         * @param taskName the name of the JS headless task to execute
+         * @param eventName the geolocation event name (e.g. "location", "stationary")
+         * @param eventParams JSON-serialized event parameters
+         */
+        fun createIntent(
+            context: Context,
+            taskName: String,
+            eventName: String,
+            eventParams: String
+        ): Intent {
+            return Intent(context, HeadlessTaskService::class.java).apply {
+                putExtra(EXTRA_TASK_NAME, taskName)
+                putExtra(EXTRA_EVENT_NAME, eventName)
+                putExtra(EXTRA_EVENT_PARAMS, eventParams)
+            }
+        }
+    }
+}