Location

Permission settings are required

getCurrentLocationYou need to set location permission before using it. Please check the permission setup guide first.

---

1. Get current location

SDK function: getCurrentLocation

A function that retrieves the device's current location information only once. Useful for showing the user's location on a map or searching for nearby stores.

Signature

function getCurrentLocation(options: { accuracy: Accuracy }): Promise<Location>;

Parameters

• options · Required · object

  An options object used when retrieving location information.

  • options.accuracy · Required · Accuracy

    It is the accuracy level for location information. For detailed values, please refer to the type below. Accuracy type below.

Return value

• Promise<Location>

  Returns an object containing the device's location information. For details, see the Location below. Location type below.

Permission methods

• getCurrentLocation.getPermission

  Returns the current status of location permission. allowed · denied · notDetermined · osPermissionDenied returns one of
• getCurrentLocation.openPermissionDialog

  Shows a dialog to request location permission again. If allowed allowed, if denied deniedis returned.

Error

If permission is denied GetCurrentLocationPermissionErroroccurs.

class GetCurrentLocationPermissionError extends PermissionError {
  constructor();
}

Example

Web (JS)

import { Accuracy, getCurrentLocation, GetCurrentLocationPermissionError } from '@apps-in-toss/web-framework';

async function handleGetCurrentLocation() {
  try {
    const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
    console.log(`Location: ${response.coords.latitude}, ${response.coords.longitude}`);
  } catch (error) {
    if (error instanceof GetCurrentLocationPermissionError) {
      console.log('No location permission');
    }
  }
}

Web (React)

import { Accuracy, getCurrentLocation, GetCurrentLocationPermissionError, Location } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function CurrentPosition() {
  const [position, setPosition] = useState<Location | null>(null);

  const handlePress = async () => {
    try {
      const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
      setPosition(response);
    } catch (error) {
      if (error instanceof GetCurrentLocationPermissionError) {
        // No location permission
      }
    }
  };

  return (
    <div>
      {position ? (
        <span>
          Location: {position.coords.latitude}, {position.coords.longitude}
        </span>
      ) : (
        <span>Location information has not been retrieved yet</span>
      )}
      <input type="button" value="Get current location" onClick={handlePress} />
      <input
        type="button"
        value="Check permission"
        onClick={async () => alert(await getCurrentLocation.getPermission())}
      />
      <input
        type="button"
        value="Request permission"
        onClick={async () => alert(await getCurrentLocation.openPermissionDialog())}
      />

  );
}

React Native

import { Accuracy, getCurrentLocation, GetCurrentLocationPermissionError, Location } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

function CurrentPosition() {
  const [position, setPosition] = useState<Location | null>(null);

  const handlePress = async () => {
    try {
      const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
      setPosition(response);
    } catch (error) {
      if (error instanceof GetCurrentLocationPermissionError) {
        // No location permission
      }
    }
  };

  return (
    <View>
      {position ? (
        <Text>
          Location: {position.coords.latitude}, {position.coords.longitude}
        </Text>
      ) : (
        <Text>Location information has not been retrieved yet</Text>
      )}
      <Button title="Get current location" onPress={handlePress} />
      <Button title="Check permission" onPress={async () => Alert.alert(await getCurrentLocation.getPermission())} />
      <Button
        title="Request permission"
        onPress={async () => Alert.alert(await getCurrentLocation.openPermissionDialog())}
      />
    </View>
  );
}

---

2. Track location in real time

SDK function: startUpdateLocation

A function that runs a callback every time the location changes. Use it in a fitness app to record travel distance or to update the location on a map in real time. Tracking stops when you call the returned cleanup function.

Signature

function startUpdateLocation(options: {
  onError: (error: unknown) => void;
  onEvent: (location: Location) => void;
  options: StartUpdateLocationOptions;
}): () => void;

Parameters

• onEvent · Required · (location: Location) => void

  Callback function called when location information changes.
• onError · Required · (error: unknown) => void

  Callback function called when location detection fails.
• options · Required · StartUpdateLocationOptions

  Configuration object needed for location detection.

  • options.accuracy · Accuracy

    Sets the location accuracy.
  • options.timeInterval · number

    The minimum interval for updating location information. Unit is milliseconds (ms).
  • options.distanceInterval · number

    Sets the location change distance in meters (m).

Return value

• () => void

  A cleanup function that stops location tracking. Be sure to call it when the component unmounts.

Permission methods

• startUpdateLocation.getPermission

  Returns the current status of location permission.
• startUpdateLocation.openPermissionDialog

  Shows a dialog to request location permission again.

Error

If permission is denied StartUpdateLocationPermissionErroroccurs. error instanceof StartUpdateLocationPermissionErrorYou can check it with

const StartUpdateLocationPermissionError: typeof GetCurrentLocationPermissionError;

Example

Web (JS)

import { Accuracy, startUpdateLocation, StartUpdateLocationPermissionError } from '@apps-in-toss/web-framework';

let cleanup;

function handleStartUpdateLocation() {
  cleanup?.();

  cleanup = startUpdateLocation({
    options: { accuracy: Accuracy.Balanced, timeInterval: 3000, distanceInterval: 10 },
    onEvent: (location) => {
      console.log(`Latitude: ${location.coords.latitude}, Longitude: ${location.coords.longitude}`);
    },
    onError: (error) => {
      if (error instanceof StartUpdateLocationPermissionError) {
        console.log('No location permission');
      }
    },
  });
}

window.addEventListener('pagehide', () => cleanup?.());

Web (React)

import {
  Accuracy,
  Location,
  startUpdateLocation,
  StartUpdateLocationPermissionError,
} from '@apps-in-toss/web-framework';
import { useCallback, useState } from 'react';

function LocationWatcher() {
  const [location, setLocation] = useState<Location | null>(null);

  const handlePress = useCallback(() => {
    startUpdateLocation({
      options: { accuracy: Accuracy.Balanced, timeInterval: 3000, distanceInterval: 10 },
      onEvent: (location) => setLocation(location),
      onError: (error) => {
        if (error instanceof StartUpdateLocationPermissionError) {
          // No location permission
        }
      },
    });
  }, []);

  return (
    <div>
      {location != null && (
        <>
          <span>Latitude: {location.coords.latitude}</span>
          <span>Longitude: {location.coords.longitude}</span>
        </>
      )}
      <input type="button" value="Start location tracking" onClick={handlePress} />

  );
}

React Native

import { Accuracy, Location, startUpdateLocation, StartUpdateLocationPermissionError } from '@apps-in-toss/framework';
import { useCallback, useState } from 'react';
import { Button, Text, View } from 'react-native';

function LocationWatcher() {
  const [location, setLocation] = useState<Location | null>(null);

  const handlePress = useCallback(() => {
    startUpdateLocation({
      options: { accuracy: Accuracy.Balanced, timeInterval: 3000, distanceInterval: 10 },
      onEvent: (location) => setLocation(location),
      onError: (error) => {
        if (error instanceof StartUpdateLocationPermissionError) {
          // No location permission
        }
      },
    });
  }, []);

  return (
    <View>
      {location != null && (
        <>
          <Text>Latitude: {location.coords.latitude}</Text>
          <Text>Longitude: {location.coords.longitude}</Text>
        </>
      )}
      <Button title="Start location tracking" onPress={handlePress} />
    </View>
  );
}

---

Types · Objects

Location accuracy options (Accuracy)

An enum for setting the location accuracy level.

enum Accuracy {
  Lowest = 1, // within a 3KM margin of error
  Low = 2, // within a 1KM margin of error
  Balanced = 3, // within a few hundred meters margin of error
  High = 4, // within a 10M margin of error
  Highest = 5, // highest accuracy
  BestForNavigation = 6, // highest accuracy for navigation
}

---

Location information object (Location)

An object that represents location information.

interface Location {
  accessLocation?: 'FINE' | 'COARSE'; // Android only. FINE: precise location, COARSE: approximate location
  timestamp: number; // Unix timestamp when the location was updated
  coords: LocationCoords; // detailed coordinate information
}

---

Detailed location coordinate information (LocationCoords)

An object that represents detailed location coordinate information.

interface LocationCoords {
  latitude: number; // latitude
  longitude: number; // longitude
  altitude: number; // altitude
  accuracy: number; // location accuracy
  altitudeAccuracy: number; // altitude accuracy
  heading: number; // direction
}