diff --git a/.changeset/tame-otters-sort.md b/.changeset/tame-otters-sort.md new file mode 100644 index 000000000..42498ec56 --- /dev/null +++ b/.changeset/tame-otters-sort.md @@ -0,0 +1,5 @@ +--- +"@telegram-apps/sdk": minor +--- + +Implement `locationManager.isSupported()`. diff --git a/apps/docs/.vitepress/packages.ts b/apps/docs/.vitepress/packages.ts index 41d7ee668..02a546beb 100644 --- a/apps/docs/.vitepress/packages.ts +++ b/apps/docs/.vitepress/packages.ts @@ -138,6 +138,7 @@ export const packagesLinksGenerator = (prefix: string = '') => { scope('haptic-feedback'), scope('init-data'), scope('invoice'), + scope('location-manager'), scope('main-button'), scope('mini-app'), scope('popup'), diff --git a/apps/docs/packages/telegram-apps-sdk/3-x/components/location-manager.md b/apps/docs/packages/telegram-apps-sdk/3-x/components/location-manager.md new file mode 100644 index 000000000..0e5be7fa2 --- /dev/null +++ b/apps/docs/packages/telegram-apps-sdk/3-x/components/location-manager.md @@ -0,0 +1,157 @@ +# Location Manager + +The 💠[component](../scopes.md) responsible for location tracking functionality for Telegram Mini +Apps. + +## Checking Support + +To check if location tracking is supported by the current Telegram Mini Apps version, use the +`isSupported` signal: + +::: code-group + +```ts [Variable] +import { locationManager } from '@telegram-apps/sdk'; + +locationManager.isSupported(); // boolean +``` + +```ts [Functions] +import { isLocationManagerSupported } from '@telegram-apps/sdk'; + +isLocationManagerSupported(); // boolean +``` + +::: + +## Mounting + +Before using the component, it must be mounted. + +This process is asynchronous, as location manager settings need to be requested from the Telegram +application. The `isMounting` signal will be set to `true` during the process and updated to `false` +when complete. + +If mounting is successful, the `isMounted` signal will be set to `true`. If errors occur, +the `mountError` signal will reflect the error. + +::: code-group + +```ts [Variable] +if (locationManager.mount.isAvailable()) { + try { + const promise = locationManager.mount(); + locationManager.isMounting(); // true + await promise; + locationManager.isMounting(); // false + locationManager.isMounted(); // true + } catch (err) { + locationManager.mountError(); // equals "err" + locationManager.isMounting(); // false + locationManager.isMounted(); // false + } +} +``` + +```ts [Functions] +import { + mountLocationManager, + isLocationManagerMounting, + isLocationManagerMounted, + locationManagerMountError, +} from '@telegram-apps/sdk'; + +if (mountLocationManager.isAvailable()) { + try { + const promise = mountLocationManager(); + isLocationManagerMounting(); // true + await promise; + isLocationManagerMounting(); // false + isLocationManagerMounted(); // true + } catch (err) { + locationManagerMountError(); // equals "err" + isLocationManagerMounting(); // false + isLocationManagerMounted(); // false + } +} +``` + +::: + +To unmount, use the `unmount` method: + +::: code-group + +```ts [Variable] +locationManager.unmount(); +locationManager.isMounted(); // false +``` + +```ts [Functions] +import { unmountLocationManager, isLocationManagerMounted } from '@telegram-apps/sdk'; + +unmountLocationManager(); +isLocationManagerMounted(); // false +``` + +::: + +## Requesting Location + +To request the current location, use the `requestLocation` method. It returns a cancelable promise +with an object, describing the current device location. + +The object contains the following numeric properties: + +| Property | Description | +|---------------------|----------------------------------------------------------------------| +| latitude | Latitude in degrees. | +| longitude | Longitude in degrees. | +| altitude | _Optional_. Altitude above sea level in meters. | +| course | _Optional_. The direction the device is moving in degrees. | +| speed | _Optional_. The speed of the device in m/s. | +| horizontal_accuracy | _Optional_. Accuracy of the latitude and longitude values in meters. | +| vertical_accuracy | _Optional_. Accuracy of the altitude value in meters. | +| course_accuracy | _Optional_. Accuracy of the course value in degrees. | +| speed_accuracy | _Optional_. Accuracy of the speed value in m/s. | + +::: code-group + +```ts [Variable] +if (locationManager.requestLocation.isAvailable()) { + const location = await locationManager.requestLocation(); +} +``` + +```ts [Functions] +import { requestLocation } from '@telegram-apps/sdk'; + +if (requestLocation.isAvailable()) { + const location = await requestLocation(); +} +``` + +::: + +## Opening Settings + +To open the location manager-related settings modal, use the `openSettings` method. This method can +only be triggered in response to user interaction. + +::: code-group + +```ts [Variable] +if (locationManager.openSettings.isAvailable()) { + locationManager.openSettings(); +} +``` + +```ts [Functions] +import { openLocationManagerSettings } from '@telegram-apps/sdk'; + +if (openLocationManagerSettings.isAvailable()) { + openLocationManagerSettings(); +} +``` + +::: diff --git a/packages/sdk/src/scopes/components/location-manager/exports.ts b/packages/sdk/src/scopes/components/location-manager/exports.ts index ff4280333..18900cb65 100644 --- a/packages/sdk/src/scopes/components/location-manager/exports.ts +++ b/packages/sdk/src/scopes/components/location-manager/exports.ts @@ -12,6 +12,7 @@ export { requestLocation, mountPromise as locationManagerMountPromise, isAvailable as isLocationManagerAvailable, + isSupported as isLocationManagerSupported, openSettings as openLocationManagerSettings, unmount as unmountLocationManager, } from './exports.variable.js'; diff --git a/packages/sdk/src/scopes/components/location-manager/exports.variable.ts b/packages/sdk/src/scopes/components/location-manager/exports.variable.ts index b26a0b699..70c40df58 100644 --- a/packages/sdk/src/scopes/components/location-manager/exports.variable.ts +++ b/packages/sdk/src/scopes/components/location-manager/exports.variable.ts @@ -12,6 +12,7 @@ export { requestLocation, mountPromise, isAvailable, + isSupported, openSettings, unmount, } from './location-manager.js'; \ No newline at end of file diff --git a/packages/sdk/src/scopes/components/location-manager/location-manager.ts b/packages/sdk/src/scopes/components/location-manager/location-manager.ts index aedf681cb..423edc6ea 100644 --- a/packages/sdk/src/scopes/components/location-manager/location-manager.ts +++ b/packages/sdk/src/scopes/components/location-manager/location-manager.ts @@ -13,6 +13,7 @@ import { defineNonConcurrentFn } from '@/scopes/defineNonConcurrentFn.js'; import { signalCancel } from '@/scopes/signalCancel.js'; import type { AsyncOptions } from '@/types.js'; import { createComputed, createSignal } from '@/signals-registry.js'; +import { createIsSupported } from '@/scopes/createIsSupported.js'; const COMPONENT_NAME = 'locationManager'; const CHECK_LOCATION_METHOD = 'web_app_check_location'; @@ -50,6 +51,11 @@ function fromState(key: K): Computed { return createComputed(() => state()[key]); } +/** + * Signal indicating whether the location data tracking is currently supported. + */ +export const isSupported = createIsSupported(CHECK_LOCATION_METHOD); + /** * Signal indicating whether the location data tracking is currently available. */