LIG Scanner SDK for React Native

A React Native SDK for scanning LIG tags and computing 3D position/pose data with high accuracy. This SDK wraps the native LIG Scanner library to provide seamless integration for React Native applications.

Features

• High-Precision 3D Positioning: Get accurate position, rotation, and translation data for scanned LIG tags
• Real-time Scanning: Continuous scanning mode with status updates
• AR Player Integration: Native AR experience with scene loading and interaction
• Cross-Platform: Full iOS and Android support
• Event-Driven Architecture: React to tag detection and status changes
• TypeScript Support: Full type definitions included

Installation

npm install lig-scanner-sdk
# or
yarn add lig-scanner-sdk
# or
pnpm add lig-scanner-sdk

iOS Setup

Important: iOS requires manual setup of the LiGPlayerKit dependency via Swift Package Manager.

1. Clone the repository and navigate to your project:

   git clone <repository-url>
   cd your-project

2. Open your iOS project in Xcode:

   cd ios
   open YourProject.xcworkspace

3. Add LiGPlayerKit dependency:

   • In Xcode, go to File → Add Package Dependencies
   • Add this URL: https://gitlab.com/lig-corp/ios-player-sdk-sample
   • Select tag: 1.7.55 (custom made for React Native)
   • Click "Add Package"

4. Add camera and AR permissions to your ios/YourProject/Info.plist:

   <key>NSCameraUsageDescription</key>
   <string>This app needs camera access to scan LIG tags</string>
   <key>NSLocationWhenInUseUsageDescription</key>
   <string>This app needs location access for AR features</string>

Android Setup

Add camera permission to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />

Usage

Basic Scanner Usage

import { ScannerSDK, type LigTag } from 'lig-scanner-sdk';
import { NativeModules, NativeEventEmitter } from 'react-native';

// Set up event listeners first
const { LigScannerSdk } = NativeModules;
const scannerEventEmitter = new NativeEventEmitter(LigScannerSdk);

// Listen for status updates (important: set this up before initialize!)
const statusListener = scannerEventEmitter.addListener('onStatusReported', (status) => {
  console.log('Scanner status:', status);
  // Status codes during initialization:
  // 18: Device is supported
  // 20: Authentication successful
});

// Listen for tag detection
const tagListener = scannerEventEmitter.addListener('onLightIDFound', (tag: LigTag) => {
  console.log('Tag detected:', {
    deviceId: tag.deviceId,
    coordinates: { x: tag.x, y: tag.y },
    isReady: tag.isReady,
    position: tag.position,
    rotation: tag.rotation,
    translation: tag.translation
  });
});

// Initialize the scanner with your product key
await ScannerSDK.initialize('YOUR_PRODUCT_KEY');

// Start scanning
await ScannerSDK.startScanning();

// Stop scanning when done
await ScannerSDK.stopScanning();

// Clean up listeners
tagListener.remove();
statusListener.remove();

AR Player Usage

import { ARPlayerView } from 'lig-scanner-sdk';

function ARScreen({ route }) {
  const { lightTagId } = route.params;

  return (
    <ARPlayerView
      sceneId="your-scene-id"
      lightTagId={lightTagId}
      autoLoad={true}
      onSceneLoaded={() => console.log('Scene loaded')}
      onSceneLoadFailed={(error) => console.log('Scene load failed:', error)}
      onScreenshotTaken={(result) => console.log('Screenshot saved:', result)}
      onRecordingStarted={() => console.log('Recording started')}
      onRecordingStopped={() => console.log('Recording stopped')}
      style={{ flex: 1 }}
    />
  );
}

API Reference

ScannerSDK

initialize(productKey: string): Promise<string>

Initialize the scanner with your product key. Must be called before any other methods.

startScanning(): Promise<string>

Start the scanning process. The scanner will begin detecting LIG tags.

stopScanning(): Promise<string>

Stop the scanning process.

removeAllListeners(): void

Remove all event listeners.

ARPlayerView

Props

• sceneId: string - The ID of the AR scene to load
• lightTagId: string - The ID of the detected light tag
• autoLoad?: boolean - Whether to automatically load the scene (default: false)
• onSceneLoaded?: () => void - Called when the AR scene loads successfully
• onSceneLoadFailed?: (error: string) => void - Called when scene loading fails
• onScreenshotTaken?: (result: string) => void - Called when a screenshot is captured
• onRecordingStarted?: () => void - Called when video recording starts
• onRecordingStopped?: () => void - Called when video recording stops
• style?: ViewStyle - React Native style object

Methods

• loadScene() - Manually load the AR scene
• unloadScene() - Unload the current AR scene
• takeScreenshot() - Capture a screenshot of the AR view
• startRecording() - Start video recording
• stopRecording() - Stop video recording

Types

LigTag

interface LigTag {
  x: number;              // X coordinate (0-1)
  y: number;              // Y coordinate (0-1)
  isReady: boolean;       // Whether 3D data is available
  isDetected: boolean;    // Whether tag is detected
  deviceId: number;       // Unique tag identifier
  status: string;         // Current status
  detectionTime?: number; // Time to detect (ms)
  decodedTime?: number;   // Time to decode (ms)
  rotation?: Vector3;     // 3D rotation data
  translation?: Vector3;  // 3D translation data
  position?: Vector3;     // 3D position data
}

interface Vector3 {
  x: number;
  y: number;
  z: number;
}

Events

onLightIDFound

Emitted when a LIG tag is detected. Provides complete tag data including 3D positioning.

onStatusReported

Emitted when scanner status changes. Status codes include:

• 18: Device is supported
• 20: Authentication successful

Example App

Check out the example directory for a complete working example with visual overlay.

Building and Running

First, build the SDK:

pnpm install
pnpm run prepare  # Build the SDK library

Then run the example:

cd example
pnpm install
pnpm android  # For Android
pnpm ios      # For iOS (requires physical device)

Note: The SDK requires camera/AR functionality and cannot run on simulators. Use a physical device for testing.

Requirements

• React Native 0.71+
• iOS 12.0+ (for AR features)
• Android 7.0 (API 24) or higher
• Camera permission
• Physical device (simulators not supported)

Troubleshooting

iOS Setup Issues

• LiGPlayerKit not found: Ensure you've added the Swift Package Manager dependency with tag 1.7.55
• Build errors: Clean your build folder (Cmd+Shift+K) and rebuild
• AR view not loading: Verify all permissions are granted and you're using a physical device

Scanner not initializing

• Ensure you have a valid product key
• Check that camera permissions are granted
• Verify minimum platform versions (iOS 12.0+, Android API 24+)

No tags detected

• Ensure proper lighting conditions
• Check camera focus
• Verify LIG tags are within scanning range
• Confirm the scanner is initialized and running

AR Player Issues

• Black screen: Ensure the scene ID is valid and the scene is available
• Performance issues: Close other apps and ensure sufficient device memory
• Recording fails: Check storage permissions and available disk space

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library