react-native-vetrix-games

SDK for Vetrix Games Hub — a collection of interactive mini-games (Millionaire Hunter, Fortune Wheel, Dice, Trivia, Raffle Draw, and more) for React Native apps.

Installation

npm install react-native-vetrix-games

iOS

cd ios && pod install

The SDK depends on lottie-ios 4.x (declared in the podspec as ~> 4.0). CocoaPods resolves this automatically. If your app already uses lottie-ios or lottie-react-native, it will share the same copy — no conflicts as long as you're on lottie-ios 4.x.

Android

No extra setup required. The SDK ships with Lottie 6.6.2 by default.

Overriding the Lottie version

If your app already uses a different version of Lottie (e.g. via lottie-react-native or a direct dependency), you can override the version used by the SDK. Add this to your root build.gradle (or build.gradle.kts):

// android/build.gradle
ext {
    lottieVersion = "6.4.0" // your preferred version (must be 6.x)
}

The SDK reads rootProject.ext.lottieVersion at build time. If not set, it falls back to its built-in default (6.6.2). This follows the same pattern used for kotlinVersion, compileSdkVersion, and other overridable properties.

Note: The SDK requires Lottie 6.x APIs. Versions below 6.0.0 are not supported.

Usage

Basic

import { VetrixGamesHub } from 'react-native-vetrix-games';

export default function App() {
  return (
    <VetrixGamesHub
      apiUrl="https://your-api.example.com/service"
      externalToken={userAuthToken}
      realtimeUrl="https://games-api.example.com"
    />
  );
}

With all options

import { VetrixGamesHub } from 'react-native-vetrix-games';

export default function App() {
  return (
    <VetrixGamesHub
      apiUrl="https://your-api.example.com/service"
      externalToken={userAuthToken}
      onExit={() => navigation.goBack()}
      onError={(error) => console.error('Session error:', error)}
      disableSound={false}
      enableHaptic={true}
      theme={{
        colors: {
          primary: '#6C63FF',
          accent: '#FFD700',
          background: '#0A0A2E',
        },
      }}
    />
  );
}

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | apiUrl | string | Yes | — | API endpoint URL. | | externalToken | string | Yes | — | Auth token from the host app, used to initialize a player session. | | realtimeUrl | string | No | — | REST API base URL for one-time-ticket-authenticated realtime wallet and game events. | | onExit | () => void | No | — | Called when the user taps "Logout" on the Profile screen. Use this to navigate away from the hub. | | onError | (error: Error \| string) => void | No | — | Called when session initialization fails. Receives the error. | | onDepositRequested | () => void | No | — | Called when the user initiates a deposit. | | onWithdrawRequested | () => void | No | — | Called when the user initiates a withdrawal. | | disableSound | boolean | No | false | Suppress all button/UI sound effects across the SDK. | | enableHaptic | boolean | No | true | Whether haptic feedback fires on press across the SDK. | | theme | Partial<VetrixTheme> | No | — | Theme color overrides. |

Note: Device analytics (OS, version, screen resolution, timezone, etc.) are collected automatically by the SDK — no configuration needed.

Sound & Haptics

Every clickable surface inside the SDK plays a short click sound and fires a light haptic tap by default. You can control this at three levels.

1. SDK-wide (via VetrixGamesHub props)

Simplest — flip the flags on the host component:

<VetrixGamesHub
  apiUrl="..."
  externalToken={token}
  disableSound          // all SDK buttons stay silent
  enableHaptic={false}  // all SDK buttons skip haptic
/>

These map onto the sounds and haptics singletons (see below), so the effect is immediate and global.

2. Programmatic (singletons)

The SDK exports two singletons for runtime control — e.g. reacting to the user's "Sound Off" toggle in your own settings screen:

import { sounds, haptics } from 'react-native-vetrix-games';

sounds.setMute(true);    // mute all SDK sounds
haptics.setMute(true);   // mute all SDK haptics

// Fire haptic manually (e.g. on your own custom button outside the SDK):
haptics.light();         // also: medium, heavy, selection, success, warning, error

3. Per-element (via VetrixPressable)

When you build your own clickable surfaces alongside the SDK, use the VetrixPressable primitive instead of TouchableOpacity — it inherits the SDK's sound + haptic behavior automatically.

import { VetrixPressable } from 'react-native-vetrix-games';

<VetrixPressable onPress={handlePress}>
  <Text>Tap me</Text>
</VetrixPressable>

// Override per-instance:
<VetrixPressable
  onPress={handleSelect}
  sound="select"          // 'click' (default) | 'select'
  haptic="selection"      // 'light' (default) | 'medium' | 'heavy' | 'selection' | 'success' | 'warning' | 'error'
  disableSound={disabled} // skip sound while in a disabled state
  enableHaptic={false}    // suppress haptic without touching sound
>
  <Text>Select option</Text>
</VetrixPressable>

For text buttons, use VetrixButton — it's built on top of VetrixPressable, so the same sound/haptic props apply:

import { VetrixButton } from 'react-native-vetrix-games';

<VetrixButton
  title="Continue"
  variant="primary"
  onPress={handleContinue}
  loading={submitting}
/>

Platform notes

• iOS uses UIImpactFeedbackGenerator / UISelectionFeedbackGenerator / UINotificationFeedbackGenerator for native haptic feedback.
• Android uses VibrationEffect.EFFECT_TICK / EFFECT_CLICK / EFFECT_HEAVY_CLICK on API 29+, with an amplitude-controlled createOneShot fallback on older devices or devices whose HAL doesn't implement a given predefined effect.
• The android.permission.VIBRATE permission is declared in the SDK's AndroidManifest.xml and is auto-merged into the host app's manifest — no action required.
• On Android, haptic feedback additionally respects the system-level Settings → Sound & vibration → Touch feedback toggle. If the user has disabled it, the SDK won't vibrate even with enableHaptic={true}.
• Sound effects on Android route through USAGE_ASSISTANCE_SONIFICATION so they mix with background media (Spotify, podcasts, etc.) instead of ducking it.

VetrixTheme

{
  colors: Partial<{
    background: string;
    surface: string;
    primary: string;
    secondary: string;
    accent: string;
    success: string;
    error: string;
    warning: string;
    textPrimary: string;
    textSecondary: string;
    textMuted: string;
    border: string;
    gold: string;
  }>;
}