SEON Geofence Web SDK

SDK for integrating SEON's geofence functionality into web applications. This SDK provides automated geolocation monitoring with configurable scheduling and comprehensive error handling.

Working examples on StackBlitz.

Installation

NPM:

npm install @seontechnologies/seon-web-geofence-sdk
# or
yarn add @seontechnologies/seon-web-geofence-sdk
# or
pnpm install @seontechnologies/seon-web-geofence-sdk

CDN:

It is preferred to use one of our CDNs directly, because this way you will always receive the latest version.

<script src="https://cdn.dfsdk.com/geofence/v1/bundle.js"></script>
<!-- or -->
<script src="https://cdn.deviceinf.com/geofence/v1/bundle.js"></script>
<!-- or -->
<script src="https://cdn.seonintelligence.com/geofence/v1/bundle.js"></script>

<script>
    // Access the SDK from the global window object instead of using import
    const { initGeofence } = window.geofence;
    const { scheduler } = initGeofence();
</script>

Integration

Automated Geolocation Monitoring

import { initGeofence } from '@seontechnologies/seon-web-geofence-sdk';

// Initialize the SDK with an optional request timeout
const { scheduler } = initGeofence({ apiRequestTimeoutMs: 15000 });

// Start monitoring with a token
const controller = scheduler.start(
    { token: 'your-initial-jwt-token' },
    // Optional callback registrations
    {
        onStart: () => console.log('Geofence monitoring started'),
        onPingSuccess: () => console.log('Location check successful'),
        onError: (error) => console.error('Error:', error.message),
        onStop: () => console.log('Monitoring stopped'),
    }
);

// Stop monitoring when needed
controller.stop();

Manual Geolocation Checks

import { initGeofence } from '@seontechnologies/seon-web-geofence-sdk';

// Initialize the SDK
const { api, session } = initGeofence();

// Perform a manual geolocation check
try {
    let token = 'your-initial-jwt-token';
    const session = await session.getSession();
    const response = await api.ping({ session }, token);
    console.log('Geolocation check successful:', response);
    token = response.token;
} catch (error) {
    console.error('Geolocation check failed:', error);
}

API Reference

initGeofence(config)

Initializes the geofence SDK.

Parameters:

• config (GeofenceConfigInput, optional): Configuration for the SDK.

Returns: Geofence object containing scheduler, api, and session services.

Configuration Options

type GeofenceConfigInput = {
    apiRequestTimeoutMs?: number; // API request timeout in ms (default: 30000)
};

Geofence Object

The initGeofence function returns an object with the following services:

• api: ApiService for manual pings.
• scheduler: Scheduler for automated monitoring.
• session: SessionService for managing user sessions.

scheduler.start(config, callbacks)

Starts the geofence monitoring scheduler.

Parameters:

• config (SchedulerConfigInput): Scheduler configuration.
• callbacks (SchedulerEventCallback, optional): Event callbacks.

Returns: RecheckController for managing the scheduler.

SchedulerConfigInput

type SchedulerConfigInput = {
    token: string; // JWT token (required)
    geolocationTimeoutMs?: number; // Geolocation timeout in ms (default: 10000)
    retryConfig?: RetryConfig; // Retry configuration
};

type RetryConfig = {
    maxRetries: number; // Maximum retry attempts
    waitMs?: number; // Wait time between retries in ms
};

SchedulerEventCallback

type SchedulerEventCallback = {
    onStart?: () => void;
    onPingStart?: () => void;
    onPingSuccess?: () => void;
    onSchedule?: (nextRecheckTime: Date) => void;
    onError?: (error: GeofenceError) => void;
    onStop?: () => void;
};

RecheckController

The controller returned by scheduler.start() provides methods to manage monitoring:

interface RecheckController {
    stop(): void; // Stops monitoring
    isActive(): boolean; // Returns true if monitoring is active
    ping(): Promise<void>; // Forces an immediate location check
}

session.getSession(config)

Retrieves the session ID.

Parameters:

• config (GeoSDKOptions, optional): Configuration for the session.

Returns: Promise<string> containing the session ID.

GeoSDKOptions

type GeoSDKOptions = {
    region?: string;
    dnsResolverDomain?: string;
    networkTimeoutMs?: number;
    fieldTimeoutMs?: number;
    geolocationTimeoutMs?: number;
};

Errors

The SDK exports custom error classes to help with error handling:

• GeofenceError: Base error class.
• GeofenceApiError: For API-related errors (includes statusCode).
• GeofenceSchedulerError: For errors from the scheduler.
• GeofenceSessionError: For session-related errors.
• GeofencePermissionError: For geolocation permission errors.
• GeofencePositionUnavailableError: When the position is unavailable.
• GeofencePositionTimeoutError: For geolocation timeouts.
• GeofenceTokenError: For JWT token errors.
• GeofenceAbortError: When an operation is aborted.
• GeofenceFetchFailedError: For network fetch failures.
• GeofenceValidationError: For configuration validation errors.

Advanced Usage

Custom Retry Configuration

const controller = scheduler.start({
    token: 'your-token',
    retryConfig: {
        maxRetries: 5,
        waitMs: 2000, // 2 seconds between retries
    },
});

Forcing a Manual Ping

try {
    await controller.ping();
    console.log('Manual ping successful');
} catch (error) {
    console.error('Manual ping failed:', error);
}

Monitoring Scheduler Status

if (controller.isActive()) {
    console.log('Geofence monitoring is running');
} else {
    console.log('Geofence monitoring is stopped');
}

Security Considerations

• Always use HTTPS endpoints for production.
• Store authentication tokens securely.

Troubleshooting

"Failed to get geolocation"

• Ensure HTTPS is used (required for geolocation API)
• Check if user has granted location permissions
• Check if geolocation is enabled in the browser
• Check if the browser has geolocation permissions

Network timeouts

• Adjust apiRequestTimeoutMs in initGeofence.