Kade React Native SDK

Overview

The package exports a GeoFenceSDK class, public TypeScript types, and a Permissions namespace. React Native autolinking connects the JavaScript wrapper to the native modules.

Install

The package is published to the Kade project package registry on GitLab, not the public npm registry. Configure the @videntrix scope and an authorized registry token before installing.

Configure npm

Add this project-level .npmrc. Supply NPM_TOKEN through your local environment or CI secret store; do not commit the token.

@videntrix:registry=https://gitlab.com/api/v4/projects/geofence1%2Freact-native-sdk/packages/npm/
//gitlab.com/api/v4/projects/geofence1%2Freact-native-sdk/packages/npm/:_authToken=${NPM_TOKEN}

Use a GitLab personal, project, deploy, or CI job token that can read this project's package registry. A deploy token needs read_package_registry; a personal or project access token commonly uses the api scope.

Install the package

npm install @videntrix/react-native-geofence-sdk@0.4.0

# Or with Yarn after the same registry configuration
yarn add @videntrix/react-native-geofence-sdk@0.4.0

Bare React Native setup

iOS

The podspec supports iOS 13 or newer and autolinks both the native core and React Native bridge. Keep the deployment target at 13.0 or higher, add the foreground location usage text, then install pods.

# ios/Podfile
platform :ios, '13.0'

target 'YourApp' do
  config = use_native_modules!
  use_react_native!(path: config[:reactNativePath])
end

<!-- ios/YourApp/Info.plist -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>We verify your location to confirm you are in a licensed region.</string>

cd ios
pod install
cd ..

The pod uses Swift 5.7. No manual pod 'GeoFenceSdk' entry is needed when React Native autolinking is enabled.

Android

The included React Native configuration points autolinking at the package's bridge class. The library manifest declares:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

You do not need to register the package manually or duplicate these permissions in the app manifest. Before a location-enabled ping() or startContinuousPing(), the wrapper requests runtime location permission and gives Android an opportunity to upgrade coarse access to precise access.

Expo setup

The bundled config plugin writes the iOS foreground location description and ensures the Android location and network permissions are present.

{
  "expo": {
    "plugins": [
      [
        "@videntrix/react-native-geofence-sdk",
        {
          "locationUsageDescription": "We verify your location to confirm you are in a licensed region."
        }
      ]
    ]
  }
}

npx expo prebuild

# Build and install a native development client
eas build --profile development

Quick start

Create one instance, attach an error observer, initialize it, and run a ping. Public operations initialize the native client automatically, but explicit startup makes initialization failures easier to handle.

import GeoFenceSDK from '@videntrix/react-native-geofence-sdk';

const sdk = new GeoFenceSDK({
  apiToken: 'your-api-token',
  regionId: 123,
  locationAccuracy: 'high',
  debug: __DEV__,
  permissionRationale: {
    title: 'Location access',
    message: 'Kade uses your location to confirm your licensed region.',
  },
});

sdk.onError((error, context) => {
  console.warn(`Kade SDK error in ${context}`, error);
});

await sdk.init();

const response = await sdk.ping({
  userId: 'player-123',
  source: 'login',
  email: 'player@example.com',
});

if (response.blocked) {
  handleBlocked(response.code, response.message);
} else {
  console.log(response.inside, response.area?.name);
}

Omit skipLocation for normal GPS-backed verification. Pass skipLocation: true when the flow intentionally relies on server-side network location and must not request device location.

Configuration

apiToken is the only required constructor option. serverUrl defaults to https://api.videntrix.com.

Core API

Email evaluation

await sdk.evaluateEmail({
  email: 'new.user@example.com',
  firstName: 'New',
  lastName: 'User',
  userId: 'player-123',
});

// The promise resolves without a client-visible verdict.

Location permissions

Import the package-level Permissions namespace when your UI needs to inspect or request location access before a ping.

import {
  Permissions,
  type PermissionStatus,
} from '@videntrix/react-native-geofence-sdk';

const current: PermissionStatus = await Permissions.getLocationStatus();

if (current !== 'granted') {
  const result = await Permissions.requestLocation({
    title: 'Location access',
    message: 'Location is required to verify your licensed region.',
  });

  if (result !== 'granted') {
    showLocationSettingsHelp(result);
  }
}

Normal ping() and startContinuousPing() calls perform this permission flow automatically unless skipLocation: true is set.

Continuous ping and lifecycle

The native loop pings immediately, then schedules each subsequent check using the server's response.interval.

await sdk.startContinuousPing(
  {
    userId: 'player-123',
    source: 'gameplay',
    regionId: 123,
  },
  (response, error) => {
    if (error) {
      console.warn('Continuous ping failed', error);
      return;
    }

    if (response.blocked) {
      handleBlocked(response.code);
      return;
    }

    updateLocationState(response.inside, response.distanceToBorder);
  },
);

// Await this when the protected flow ends.
await sdk.stopContinuousPing();

The native loop stops after a blocked response or HTTP status 403/451. It also adapts location watching to the server interval and disables the watcher for skipLocation.

Types and responses

PingOptions

interface PingOptions {
  userId?: string;
  silent?: boolean;
  skipLocation?: boolean;
  source?: string;
  regionId?: number;
  email?: string;
  firstName?: string;
  lastName?: string;
}

• silent asks the server to process the request without returning the normal verdict payload.
• skipLocation suppresses the runtime permission request and device GPS collection for that operation.
• source is a free-form flow tag such as login, deposit, or gameplay.
• regionId overrides the constructor's region for the ping or entire continuous session.
• Identity fields associate the server-side client record with the app's account data.

PingResponse

interface PingArea {
  id: number;
  name: string;
}

interface PingResponse {
  inside: boolean;
  status: number;
  message?: string;
  code?: GeoFenceResponseCode;
  interval: number;
  distanceToBorder: number;
  regionId?: number;
  area?: PingArea;
  blocked?: boolean;
  requestLocation?: boolean;
  deviceTrustTtl?: number;
}

requestLocation lets the server ask the native client to escalate toward GPS on a later ping. deviceTrustTtl is a server-provided millisecond window in which the native client may skip expensive integrity probes.

Fingerprint results

interface FingerprintResult {
  visitorId: string;
}

interface FingerprintServerResponse {
  clientId: string;
  fingerprintRequestCount: number;
  visitorId?: string;
  confidence: {
    score: number;
    comment: string;
  };
  ip: string;
  ja3?: string;
  ja4?: string;
  device: {
    userAgent?: string;
    browser?: string;
    os?: string;
  };
}

Mobile block codes

Branch on blocked === true first. The code union permits future strings, so unknown codes must still be treated as blocked.

Web and mobile differences

On React Native, use Permissions.getLocationStatus() and Permissions.requestLocation() for explicit UI flows. For the normal case, call ping() or startContinuousPing() and let the SDK perform automatic foreground permission handling.