@ajuarezso/capacitor-native-location-auth

Capacitor plugin to distinguish the 4 real levels of location authorization (notDetermined / whenInUse / always / denied) on iOS and Android. Fills the gap left by @capacitor/geolocation which only reports generic granted / denied. Free alternative to @transistorsoft/capacitor-background-geolocation ($300/year on Android).

🇪🇸 Versión en español: README.es.md

Capacitor plugin to distinguish the 4 real levels of location authorization (notDetermined / whenInUse / always / denied) on iOS and Android.

Fills the gap left by @capacitor/geolocation, which only reports generic granted / denied / prompt without distinguishing foreground vs background.

Designed for apps that need to build a 2-step educational permission flow:

1. Ask user for whenInUse first (foreground only) — iOS shows a simple dialog with no "Always" option mixed in.
2. After foreground granted, ask for always (background) — iOS shows a dedicated upgrade dialog ("Allow always" vs "Keep while using").

This is the UX flow Apple recommends and that apps like Uber, Rappi, and DoorDash use.

Install

npm install @ajuarezso/capacitor-native-location-auth
npx cap sync

iOS Setup

In ios/App/App/Info.plist, ensure you have both keys:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your app needs location to ...</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Your app needs background location to ...</string>

If you need background tracking, also add location to UIBackgroundModes.

Android Setup

In android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

ACCESS_BACKGROUND_LOCATION is only needed for Android 10+ (API 29+).

API

Types

type LocationAuthStatus = 'notDetermined' | 'whenInUse' | 'always' | 'denied';

interface LocationAuthStatusResult {
  status: LocationAuthStatus;
}

getStatus(): Promise<LocationAuthStatusResult>

Returns the current authorization level without prompting.

import { NativeLocationAuth } from '@ajuarezso/capacitor-native-location-auth';

const { status } = await NativeLocationAuth.getStatus();
// 'notDetermined' | 'whenInUse' | 'always' | 'denied'

requestWhenInUse(): Promise<LocationAuthStatusResult>

Requests foreground-only authorization ("While using the app").

• iOS: calls CLLocationManager.requestWhenInUseAuthorization(). Shows a system dialog with only whenInUse / oneTime / deny — not the combined 4-option dialog that Geolocation.requestPermissions() would show.
• Android: requests ACCESS_FINE_LOCATION.

If status is already whenInUse or always, resolves immediately without showing a dialog. If permanently denied, returns 'denied' and you should direct user to Settings.

const { status } = await NativeLocationAuth.requestWhenInUse();
if (status === 'whenInUse') {
  // Now you can ask for 'always' separately
}

requestAlways(): Promise<LocationAuthStatusResult>

Requests background authorization ("Always allow"). Call this after requestWhenInUse() succeeded.

• iOS: calls CLLocationManager.requestAlwaysAuthorization(). If status is whenInUse, iOS shows the upgrade dialog ("Allow always" vs "Keep while using"). If user already denied, no dialog is shown — only Settings can change it.
• Android 10+: requests ACCESS_BACKGROUND_LOCATION with its own runtime dialog ("Allow all the time" vs "Allow only while using").
• Android <10: resolves immediately with 'always' because background isn't a separate permission below API 29.

const { status } = await NativeLocationAuth.requestAlways();
if (status === 'always') {
  // Start background tracking
}

Complete 2-step Flow Example

import { NativeLocationAuth } from '@ajuarezso/capacitor-native-location-auth';

async function enableBackgroundLocation() {
  const initial = await NativeLocationAuth.getStatus();

  if (initial.status === 'always') {
    // Already authorized for background; start tracking
    return startTracking();
  }

  if (initial.status === 'denied') {
    // Permanently denied; direct user to Settings
    return openSettings();
  }

  // Step 1: ask for foreground
  await showEducationalModal({ title: 'Enable location', cta: 'Continue' });
  const fg = await NativeLocationAuth.requestWhenInUse();
  if (fg.status === 'denied') return openSettings();

  // Step 2: ask for background
  await showEducationalModal({ title: 'One more permission', cta: 'Continue' });
  const bg = await NativeLocationAuth.requestAlways();
  if (bg.status === 'always') {
    startTracking();
  } else {
    // User kept only whenInUse — start tracking anyway,
    // they'll just need to keep the app open
    startTracking({ foregroundOnly: true });
  }
}

Why This Plugin?

The official @capacitor/geolocation plugin reports permission as a generic granted / denied — you cannot tell whether the user has whenInUse or always. This is fine for apps that only need foreground location, but breaks for apps that need background tracking (delivery drivers, fitness apps, geofencing, etc.).

Other plugins:

| Plugin | Distinguishes whenInUse vs always? | Cost | |---|---|---| | @capacitor/geolocation | ❌ | Free | | @capacitor-community/background-geolocation | ❌ | Free | | @capgo/background-geolocation | ❌ | Free | | @transistorsoft/capacitor-background-geolocation | ✅ | $300/year for Android production | | @ajuarezso/capacitor-native-location-auth | ✅ | Free |

Platforms

• iOS 14+
• Android API 24+ (Android 7+)

Keywords for discoverability

This plugin solves: capacitor location permission whenInUse vs always, capacitor background location, capacitor foreground vs background geolocation, capacitor CLLocationManager requestWhenInUse, capacitor CLLocationManager requestAlways, capacitor 2-step location permission flow, capacitor Uber Rappi DoorDash style permission flow, capacitor location authorization status, ionic background location free alternative transistorsoft, capacitor Apple location permission flow, capacitor ACCESS_BACKGROUND_LOCATION runtime.

Related projects this is an alternative to or complements:

• @capacitor/geolocation (no distinguishes auth levels)
• @capacitor-community/background-geolocation (no distinguishes auth levels)
• @capgo/background-geolocation (use this for the actual tracking — pair with native-location-auth for the permission flow)
• @transistorsoft/capacitor-background-geolocation (paid alternative that has its own permission API)

Repository

• Source: https://github.com/anthonyjuarezsolis/capacitor-native-location-auth
• Issues: https://github.com/anthonyjuarezsolis/capacitor-native-location-auth/issues
• npm: https://www.npmjs.com/package/@ajuarezso/capacitor-native-location-auth
• Built and used in production by Master Pedidos

License

MIT — see LICENSE.