@aldegad/capacitor-geolocation

This is a capacitor plugin, let you receive geolocation updates either forground and background. Android and iOS platforms are suppoerted.

Install

npm install @aldegad/capacitor-geolocation
npx cap sync

Quick Example

typescript

import { Geolocation, GeolocationAlert, GeolocationConnect } from '@aldegad/capacitor-geolocation';

async startLocationUpdates() {
    const { state } = await Geolocation.requestPermission();

    if(state !== 'granted') return;

    Geolocation.startLocationUpdates(null, ({latitude, longitude}) => {
        console.log("location updates", `${latitude}/${longitude}`);
    });
}
stopLocationUpdates() {
    Geolocation.startLocationUpdates();
}

API

• requestPermission(...)
• startLocationUpdates(...)
• stopLocationUpdates()
• Interfaces
• Type Aliases
• Enums

requestPermission(...)

requestPermission(options?: GeolocationPermissionOptions | undefined) => Promise<{ state: GeolocationPermissionState; }>

Request and check geolocation permissions. You can define alert cotext.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------- | | options | GeolocationPermissionOptions |

Returns: Promise<{ state: GeolocationPermissionState; }>

Since: 0.0.1

startLocationUpdates(...)

startLocationUpdates(options?: GeololocationUpdatesOptions | undefined, callback?: GeolocationUpdatesCallback | undefined) => Promise<void>

Start location updates.

| Param | Type | | -------------- | ----------------------------------------------------------------------------------- | | options | GeololocationUpdatesOptions | | callback | GeolocationUpdatesCallback |

Since: 0.0.1

stopLocationUpdates()

stopLocationUpdates() => Promise<void>

Stop location updates.

Since: 0.0.1

Interfaces

GeolocationPermissionOptions

Geolocation permission options.

| Prop | Type | Description | Since | | ----------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----- | | promptAlert | GeolocationAlertOptions | Android only. If user ignore geolocation permission, notice why this application needs geolocation permissions. | 0.0.1 | | deniedAlert | GeolocationAlertOptions | If user denied geolocation permission, notice why this application needs geolocation permissions and tells how to reset permissions. | 0.0.1 |

GeolocationAlertOptions

Geolocation alert options.

| Prop | Type | Description | Since | | ---------------- | ------------------- | ----------------- | ----- | | header | string | Alert header | 0.0.1 | | message | string | Alert message | 0.0.1 | | okText | string | Alert ok text | 0.0.1 | | cancelText | string | Alert cancel text | 0.0.1 |

GeololocationUpdatesOptions

Geolocation updates options.

| Prop | Type | Description | Default | Since | | ------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | ----- | | background | boolean | Toggle background geolocation enable or not. | true | 0.0.1 | | notification | GeolocationNotificationOptions | This is Android forground notification option. If you need to run background geolocation on Android, you must define notification. | | 0.0.1 | | connect | GeolocationConnectOptions | After location updates, upload data to server. It uses multipart-formdata. | Nothing to do is default. | 0.0.1 |

GeolocationNotificationOptions

This is Android forground notification module. If you need to run background Geolocation on Android, you must define notification.

| Prop | Type | Description | Default | Since | | ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | ----- | | channelID | string | Android notification channel id | "LOCATION_SERVICE_CHANNEL" | 0.0.1 | | channelName | string | Android notification cannel name | "Geolocation tracking notification" | 0.0.1 | | header | string | Android notification header | "Geolocation tracker" | 0.0.1 | | message | string | Android notification message | "Geolocation tracking now." | 0.0.1 | | icon | string | Android notification icon. Icon's path should be in android/app/res folder. Do not use image mine-type like .png, .jpeg etc. | "mipmap/ic_launcher" | 0.0.1 |

GeolocationConnectOptions

After location updates, upload data to server. multipart-formdata

| Prop | Type | Description | Default | Since | | ---------- | -------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------- | ----- | | url | string | Update url | null | 0.0.1 | | body | { [name: string]: string | number; } | Update body. You can get latitude and longitude data as @latitude and @longitude. | null | 0.0.1 |

GeolocationUpdatesCallbackEvent

| Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------- | ----- | | longitude | number | User location longitude | 0.0.1 | | latitude | number | User location latitude | 0.0.1 |

Type Aliases

GeolocationUpdatesCallback

Each time Geolocation updates, It fires. It's only for forground state.

(data: GeolocationUpdatesCallbackEvent): void

Enums

GeolocationPermissionState

| Members | Value | Description | | ------------- | ---------------------- | --------------------------------- | | granted | "granted" | Geolocation permissions granted | | denied | "denied" | Geolocation permissions denied | | prompt | "prompt" | User has not yet set permissions. |

Full Example

import { Geolocation, GeolocationAlert, GeolocationConnect } from '@aldegad/capacitor-geolocation';

async startLocationUpdates() {
    const permissionOptions:GeolocationPermissionOptions = {
        promptAlert: null,
        deniedAlert: null
    }
    const promptAlert:GeolocationAlertOptions = {
        header: '위치권한 필요',
        message: '이 앱은 원활한 사용을 위해 위치권한을 필요로 합니다.\n위치 권한을 허용해주세요.',
        cancelText: '거부',
        okText: '확인'
    }
    const deniedAlert:GeolocationAlertOptions = {
        header: '위치권한 거부됨',
        message: '이 앱은 원활한 사용을 위해 위치권한을 필요로 합니다.\n[권한 -> 위치]로 이동하여 권한을 허용해주세요.',
        cancelText: '거부',
        okText: '이동'
    }
    permissionOptions.promptAlert = promptAlert;
    permissionOptions.deniedAlert = deniedAlert;
    const { state } = await Geolocation.requestPermission(permissionOptions);
    
    if(state !== 'granted') return;
    
    const updatesOptions:GeololocationUpdatesOptions = {
        background: null,
        notification: null,
        connect: null
    }
    const background:boolean = true;
    const notification:GeolocationNotificationOptions = {
        channelID: 'LOCATION_SERVICE_CHANNEL',
        channelName: '근로자 안전 위치 관리',
        header: '근로자 안전 관리 시스템',
        message: '안전한 근무를 위해 위치관리 시스템을 작동 중 입니다.',
        icon: 'drawable/default_dark'
    }
    const connect:GeolocationConnectOptions = {
        url: 'https://devmonster.co.kr/api/test_log',
        body: {
            user_id: 'ef34f3f3',
            user_position: 'User position is @latitude and @longitude'
        }
    }
    updatesOptions.background = background;
    updatesOptions.notification = notification;
    updatesOptions.connect = connect;
    Geolocation.startLocationUpdates(updatesOptions, ({latitude, longitude}) => {
        console.log();
    });
}
stopLocationUpdates() {
    Geolocation.startLocationUpdates();
}