@zenonhub/capacitor-background-geolocation

Coarse background geolocation, for example for weather apps.

Install

npm install @zenonhub/capacitor-background-geolocation
npx cap sync

API

• requestPermission(...)
• hasPermission()
• createNotificationChannel(...)
• start(...)
• stop()
• Type Aliases

requestPermission(...)

requestPermission(options: { background: boolean; }) => Promise<{ status: GeolocationPermissionStatus; }>

Requests permission. You should at first call it with background: false for foreground location, and if granted request again with background: true (for Google Play you might need to inform the user before this call). iOS handles the same flow gracefully, but will request with 'ALWAYS' directly.

| Param | Type | | ------------- | ------------------------------------- | | options | { background: boolean; } |

Returns: Promise<{ status: GeolocationPermissionStatus; }>

hasPermission()

hasPermission() => Promise<{ status: GeolocationPermissionStatus; }>

Returns the approval state of background geolocation.

Returns: Promise<{ status: GeolocationPermissionStatus; }>

createNotificationChannel(...)

createNotificationChannel(options: { channelName: string; channelDescription: string; }) => Promise<{ success: boolean; }>

ANDROID ONLY - iOS returns { success: true } always. Android requires a notification channel. Will request permissions first, and if granted create a channel.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | { channelName: string; channelDescription: string; } |

Returns: Promise<{ success: boolean; }>

start(...)

start(options: { url: string; android?: { updateInterval?: `${number}m` | `${number}h`; maximumLocationAgeMillis?: number; minimumMovementBeforeUpdate?: `${number}m` | `${number}mi` | `${number}km`; locationPriority?: 'PRIORITY_HIGH_ACCURACY' | 'PRIORITY_BALANCED_POWER_ACCURACY' | 'PRIORITY_LOW_POWER' | 'PRIORITY_PASSIVE'; notificationTitle?: string; notificationDescription?: string; }; }) => Promise<void>

Starts background geolocation.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | options | { url: string; android?: { updateInterval?: ${number}m | ${number}h; maximumLocationAgeMillis?: number; minimumMovementBeforeUpdate?: ${number}m | ${number}mi | ${number}km; locationPriority?: 'PRIORITY_HIGH_ACCURACY' | 'PRIORITY_BALANCED_POWER_ACCURACY' | 'PRIORITY_LOW_POWER' | 'PRIORITY_PASSIVE'; notificationTitle?: string; notificationDescription?: string; }; } |

stop()

stop() => Promise<void>

Stops background geolocation. You need to call start with an URL to start it again. All other configuration will be saved and isn't required to re-use.

Type Aliases

GeolocationPermissionStatus

NOT_REQUESTED - [iOS only] Permissions has not been requested GRANTED - Background geolocation has been granted GRANTED_WHEN_IN_USE - Background geolocation has NOT been granted, but foreground has DENIED - [Android] Geolocation has not been requested or denied [iOS] geolocation has been denied

'NOT_REQUESTED' | 'GRANTED' | 'GRANTED_WHEN_IN_USE' | 'DENIED'