Geolocation

Get the device's GPS position once or stream live location updates.

Get started

Readings are delivered on the location event as a "latitude,longitude" string or an object with latitude and longitude, so subscribe before you call. Request the location permission first.

import { createBdkNative } from "@bdk/native/browser";

const bdk = createBdkNative();

// Subscribe first — the position is delivered to this event, not the promise.
bdk.on("location", (info) => {
  if (typeof info === "string") {
    const [latitude, longitude] = info.split(",").map(Number);
    console.log(latitude, longitude);
  } else {
    console.log(info.latitude, info.longitude);
  }
});

await bdk.permissions.ask("location");

Get the current position

Read the device's latest fix. The reading arrives on the location event. Start tracking first — without it there's no fix to read yet.

bdk.on("location", (info) => {
  console.log("current position", info);
});

await bdk.location.getCurrentPosition();

Follow the device while the app is open

Start foreground tracking to keep the device's position up to date, then read it whenever you need it. Call stopForegroundTracking() to end it.

Tracking keeps the fix fresh; it doesn't push updates to your page. Poll getCurrentPosition() for each reading you want.

const off = bdk.on("location", (info) => {
  console.log("moving", info);
});

await bdk.location.startForegroundTracking();

// read the latest fix whenever you need it
const timer = setInterval(() => bdk.location.getCurrentPosition(), 3000);

// later, to stop:
clearInterval(timer);
off();

Stop a foreground stream

Stop an active foreground stream.

await bdk.location.stopForegroundTracking();

Keep tracking in the background

Keep receiving location updates while the app is backgrounded. On a successful start, backgroundLocationEnabled fires with { enabled, alreadyRunning, reason }.

Android only — wrap the call in try/catch.

bdk.on("backgroundLocationEnabled", ({ enabled, alreadyRunning, reason }) => {
  console.log({ enabled, alreadyRunning, reason });
});

try {
  await bdk.location.enableBackground({ id: "https://example.com/location", interval: 15 });
} catch {
}

Stop background tracking

Stop background updates. On a successful stop, backgroundLocationDisabled fires with { enabled }. Android only — wrap the call in try/catch.

bdk.on("backgroundLocationDisabled", ({ enabled }) => {
  console.log("background location enabled?", enabled);
});

try {
  await bdk.location.disableBackground();
} catch {
}

Events

All position data arrives on events. bdk.on(...) returns an unsubscribe function.

location — every position reading (one-shot or streamed): a "latitude,longitude" string or an object with latitude and longitude.
backgroundLocationEnabled — { enabled, alreadyRunning, reason }.
backgroundLocationDisabled — { enabled }.

const offs = [
  bdk.on("location", (info) => console.log("location", info)),
  bdk.on("backgroundLocationEnabled", (p) => console.log("bg on", p)),
  bdk.on("backgroundLocationDisabled", (p) => console.log("bg off", p))
];

// Clean up all listeners at once.
offs.forEach((off) => off());