@retic/geofence-sdk

JavaScript SDK for Retic Geofence Pro — geofencing, IP geolocation, fraud detection, and location-based rules.

• Zero dependencies
• Works in any browser or bundler (ESM + UMD)
• Full TypeScript support
• Automatic device fingerprinting
• Browser geolocation with IP fallback

Install

npm install @retic/geofence-sdk

Or via CDN:

<script src="https://unpkg.com/@retic/geofence-sdk/dist/retic.umd.js"></script>

Quick Start

import { Retic } from '@retic/geofence-sdk'

const retic = Retic.initialize('your_publishable_key')

const result = await retic.trackOnce()
console.log(result.user.location)  // { latitude, longitude, city, country_code, ... }
console.log(result.user.fraud)     // { passed, vpn, proxy, tor, mocked }
console.log(result.events)         // [{ type: 'entry', geofence: { tag, ... } }]
console.log(result.rules)          // { allowed: true }

API Reference

Retic.initialize(key, options?)

Creates and returns the SDK singleton. Must be called before any other method.

const retic = Retic.initialize('retic_live_pk_...', {
  baseUrl: 'https://geofencepro.retic.co',  // default, can be omitted
  onEvents: (events) => { /* geofence entry/exit/dwell */ },
  onRuleAction: (action) => { /* location rule triggered */ },
  onError: (err) => { /* { code, message } */ },
})

Options

| Option | Type | Description | |---|---|---| | baseUrl | string | API base URL. Defaults to https://geofencepro.retic.co | | onEvents | (events: GeofenceEvent[]) => void | Called when geofence events are triggered | | onRuleAction | (action: RuleAction) => void | Called when a location rule blocks the user | | onError | (error: ReticError) => void | Called on any API error |

Retic.getInstance()

Returns the existing SDK instance. Throws if initialize() hasn't been called.

const retic = Retic.getInstance()

retic.trackOnce(location?)

Tracks the user's location and evaluates geofences and rules. Automatically requests browser geolocation; falls back to IP-based location if denied.

// Auto-detect location
const result = await retic.trackOnce()

// Or provide coordinates manually
const result = await retic.trackOnce({
  latitude: 40.7128,
  longitude: -74.0060,
  accuracy: 10,
})

Returns: TrackResponse

{
  events: GeofenceEvent[]  // geofence entry/exit/dwell events
  user: TrackedUser        // user info, location, and fraud check
  rules: RuleResult        // whether the user is allowed
}

retic.ipGeocode()

Returns geolocation data for the user's IP address without triggering geofence evaluation.

const geo = await retic.ipGeocode()
console.log(geo.city, geo.state, geo.country)

Returns: IpGeocodeResponse

{
  ip_address: string
  latitude?: number
  longitude?: number
  country_code?: string
  country?: string
  state_code?: string
  state?: string
  city?: string
  postal_code?: string
  timezone?: string
}

retic.searchGeofences(options)

Searches for geofences near a given point.

const geofences = await retic.searchGeofences({
  latitude: 40.7128,
  longitude: -74.0060,
  radius: 5000,  // meters, optional
  limit: 10,     // optional
})

Returns: GeofenceRef[]

{
  id: string
  tag: string
  external_id: string
  description?: string
}

retic.setUserId(userId)

Associates a user ID with subsequent tracking calls.

retic.setUserId('user_123')

retic.setMetadata(metadata)

Attaches custom key-value metadata to subsequent tracking calls.

retic.setMetadata({ plan: 'pro', source: 'checkout' })

Types

All types are exported for TypeScript users:

import type {
  ReticOptions,
  TrackResponse,
  GeofenceEvent,
  GeofenceRef,
  TrackedUser,
  UserLocation,
  FraudResult,
  RuleResult,
  RuleAction,
  IpGeocodeResponse,
  SearchGeofencesOptions,
  ReticError,
} from '@retic/geofence-sdk'

GeofenceEvent

{
  id: string
  type: 'entry' | 'exit' | 'dwell'
  confidence: number
  geofence: GeofenceRef
  created_at: string
}

FraudResult

{
  passed: boolean   // true if no fraud signals detected
  proxy: boolean
  vpn: boolean
  tor: boolean
  mocked: boolean   // spoofed GPS
}

RuleResult

{
  allowed: boolean       // false if a location rule blocks the user
  action?: string        // 'block' | 'redirect' | ...
  redirect_url?: string  // set when action is 'redirect'
}

Framework Examples

React

import { Retic } from '@retic/geofence-sdk'

// Initialize once at app entry
Retic.initialize('your_key', {
  onRuleAction: ({ action, redirect_url }) => {
    if (action === 'redirect') window.location.href = redirect_url
  },
})

function App() {
  useEffect(() => {
    Retic.getInstance().trackOnce()
  }, [])

  return <div>...</div>
}

Vanilla JS

<script src="https://unpkg.com/@retic/geofence-sdk/dist/retic.umd.js"></script>
<script>
  const retic = Retic.Retic.initialize('your_key')
  retic.trackOnce().then(result => {
    if (!result.rules.allowed) {
      document.body.innerHTML = '<h1>Access restricted in your region</h1>'
    }
  })
</script>

License

MIT