@kubesense/kubesense-browser-core

Foundation utilities shared across the Kubesense Browser SDK: session management, transport and batching, configuration, context managers, telemetry, and browser helpers.

Internal package. This is a building block consumed by the other Kubesense Browser SDK packages — it is not a product SDK on its own and has no standalone initialization. You normally do not install it directly.

To instrument your application, use one of:

• @kubesense/kubesense-browser-rum — Real User Monitoring
• @kubesense/kubesense-browser-rum-slim — RUM without Session Replay
• @kubesense/kubesense-browser-logs — Log collection

Geolocation

The SDK provides utilities to collect user geolocation data using the browser's Geolocation API.

Note: Collecting geolocation requires explicit user permission. The browser will prompt the user to allow location access.

API

import { canUseGeoLocation, getCurrentPosition, watchPosition, clearWatch } from '@kubesense/kubesense-browser-core'

// Check if geolocation is supported
if (canUseGeoLocation()) {
  // Get position once
  getCurrentPosition(
    (position) => {
      console.log(position.latitude, position.longitude, position.accuracy)
    },
    (error) => {
      console.error(error.message)
    },
    { enableHighAccuracy: true, timeout: 10000 }
  )

  // Or watch position continuously
  const watchId = watchPosition(
    (position) => {
      console.log(position.latitude, position.longitude)
    },
    (error) => {
      console.error(error.message)
    }
  )

  // Stop watching
  clearWatch(watchId)
}

Using with RUM

Add location data to all RUM events via global context:

import { getCurrentPosition, canUseGeoLocation } from '@kubesense/kubesense-browser-core'
import { kubsenseRum } from '@kubesense/kubesense-browser-rum'

if (canUseGeoLocation()) {
  getCurrentPosition((position) => {
    kubsenseRum.setGlobalContextProperty('geo', {
      latitude: position.latitude,
      longitude: position.longitude,
      accuracy: position.accuracy,
    })
  })
}

Or use the beforeSend hook to add location to individual events:

kubsenseRum.init({
  beforeSend: (event) => {
    if (canUseGeoLocation()) {
      getCurrentPosition(
        (position) => {
          event.context.geo = {
            latitude: position.latitude,
            longitude: position.longitude,
          }
        },
        () => {} // Ignore errors
      )
    }
  }
})

Reverse Geocoding

Convert coordinates to location names (city, country, etc.) using reverse geocoding:

import { getCurrentPosition, reverseGeocodeWithPosition, getLocationName } from '@kubesense/kubesense-browser-core'

getCurrentPosition((position) => {
  reverseGeocodeWithPosition(position, (result) => {
    console.log(result.city)      // "San Francisco"
    console.log(result.state)     // "California"
    console.log(result.country)   // "United States of America"
    console.log(getLocationName(result)) // "San Francisco, California, United States of America"
  })
})

API

// Sync callback style
reverseGeocode(lat, lon, onSuccess, onError)

// Async style
const result = await reverseGeocodeAsync(lat, lon)

// With position object
reverseGeocodeWithPosition(position, onSuccess, onError)
const result = await reverseGeocodeWithPositionAsync(position)

Response Type

interface GeoLocationResult {
  city?: string           // "San Francisco"
  state?: string          // "California"
  stateCode?: string      // "CA"
  country?: string        // "United States of America"
  countryCode?: string    // "US"
  continent?: string      // "North America"
  timezone?: string       // "America/Los_Angeles"
  locality?: string       // Neighborhood or suburb
  postalCode?: string     // "94102"
  raw?: GeocodingResponse // Raw API response
}

Note: By default, this uses OpenStreetMap's Nominatim API (free, no API key required). You can provide your own baseUrl for other geocoding services.

License

Apache-2.0