npm package: @sency/react-native-smkit-ui
Description: React Native library for SMKit UI - Advanced fitness assessments and workout programs with AI-powered motion detection and real-time performance tracking
Author: Sency AI
Latest version: 2.1.7

# React Native SMKit UI Library

AI-powered fitness assessments, custom workouts, and workout programs with real-time motion detection for React Native apps.

## Table of Contents

1. [Features](#features)
2. [Requirements](#requirements)
3. [Installation](#installation)
4. [Platform Setup](#platform-setup)
5. [Getting Started](#getting-started)
6. [Core Features](#core-features)
7. [API Reference](#api-reference)
8. [Examples](#examples)
9. [Troubleshooting](#troubleshooting)
10. [Support](#support)

---

## Features

- **Fitness Assessments** - AI-driven fitness evaluations tailored to user fitness levels
- **Workout Programs** - Multi-week customizable workout plans with progression tracking
- **Motion Detection** - Real-time motion capture and analysis with pose detection
- **Multiple Assessment Types** - Fitness, Body360, Strength, Cardio, and custom assessments
- **Cross-Platform** - Native support for iOS and Android
- **Configurable Workouts** - Customize by body zone, difficulty, and duration
- **Intelligent Model Selection** (Android) - Automatically selects the best pose estimation model based on device capabilities for optimal performance

---

## Requirements

### General
- **Node.js** 18+
- **npm** or **yarn**

### iOS
- **iOS 13+**
- **Xcode 14+**
- **CocoaPods**

### Android
- **Android API 26+**
- **Android Studio** with SDK tools
- **JDK 11+**

---

## Installation

Install the package via npm:

```bash
npm install @sency/react-native-smkit-ui
```

Or with yarn:

```bash
yarn add @sency/react-native-smkit-ui
```

Then install native dependencies:

```bash
cd ios && pod install && cd ..
```

---

## Platform Setup

### iOS Setup

1. Add the required CocoaPods sources to your `ios/Podfile`:

```ruby
source 'https://bitbucket.org/sencyai/ios_sdks_release.git'
source 'https://github.com/CocoaPods/Specs.git'
```

2. Add `use_frameworks!` to your target:

```ruby
target 'YourApp' do
  use_frameworks!
  # ... other pods
end
```

3. Add the post-install hook at the end of your Podfile:

```ruby
post_install do |installer|
  react_native_post_install(
    installer,
    :mac_catalyst_enabled => false
  )
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
    end
  end
  __apply_Xcode_12_5_M1_post_install_workaround(installer)
end
```

4. Install pods:

```bash
cd ios
NO_FLIPPER=1 pod install
cd ..
```

5. Add camera permission to `Info.plist`:

```xml
<key>NSCameraUsageDescription</key>
<string>Camera access is needed for fitness assessments and motion detection</string>
```

### Android Setup

1. Update your project-level `build.gradle`:

```gradle
buildscript {
    ext {
        minSdkVersion = 26
        // ... other settings
    }
}

allprojects {
    maven {
        url "https://artifacts.sency.ai/artifactory/release/"
    }
}
```

2. Ensure your app's `build.gradle` targets Android API 26+:

```gradle
android {
    compileSdkVersion 35
    defaultConfig {
        minSdkVersion 26
        targetSdkVersion 35
    }
}
```

3. **Pose Estimation Model Selection** (v2.0.5+)

The SMKit SDK automatically selects the best pose estimation model based on device capabilities:
- **Pro Model** - High-end devices for maximum accuracy and detailed pose detection
- **Lite Model** - Mid-range devices for balanced performance and accuracy
- **UltraLite Model** - Lower-end devices for smooth real-time performance

This automatic selection ensures optimal performance and accuracy across a wide range of Android devices without requiring manual configuration.

---

## Getting Started

### 1. Initialize the Library

Call `configure()` as early as possible in your app (e.g., on app launch):

```typescript
import { configure } from '@sency/react-native-smkit-ui';

try {
  await configure('YOUR_API_KEY');
} catch (error) {
  console.error('Failed to configure SMKit UI:', error);
}
```

> **⚠️ Important:** The library will not function until `configure()` is called successfully.

### 2. Request Camera Permissions

Ensure your app has camera permissions granted before starting assessments or workouts:

```typescript
import { request, PERMISSIONS, RESULTS } from 'react-native-permissions';

const cameraPermission = await request(
  Platform.OS === 'ios' 
    ? PERMISSIONS.IOS.CAMERA 
    : PERMISSIONS.ANDROID.CAMERA
);

if (cameraPermission === RESULTS.GRANTED) {
  // Ready to start assessments/workouts
}
```

---

## Core Features

### Assessment Types

| Type | Purpose | Use Case |
|------|---------|----------|
| **Fitness** | Comprehensive fitness evaluation | General fitness assessment for all levels |
| **Body360** | Full-body movement and posture analysis | Preventative health screening |
| **Strength** | Core and endurance strength testing | Evaluate strength capabilities |
| **Cardio** | Cardiovascular capacity assessment | Assess aerobic fitness |
| **Custom** | Custom assessment (provided by Sency) | Specialized evaluations |

### Workout Configuration

Customize workouts with:
- **Body Zones**: Full Body, Upper Body, Lower Body, Core
- **Difficulty**: Low, Medium, High
- **Duration**: Short, Medium, Long
- **Week Number**: For multi-week programs

---

## API Reference

### Core Methods

#### `configure(apiKey: string): Promise<void>`

Initialize the SMKit UI library with your API key.

```typescript
import { configure } from '@sency/react-native-smkit-ui';

await configure('YOUR_API_KEY');
```

---

#### `startAssessment(type: AssessmentType, options?: AssessmentOptions): Promise<AssessmentResult>`

Start a fitness assessment.

```typescript
import { startAssessment, AssessmentType } from '@sency/react-native-smkit-ui';

const result = await startAssessment(AssessmentType.Fitness, {
  showSummary: true,
  customId: 'user-123'
});
```

**Parameters:**
- `type` - The assessment type (Fitness, Body360, Strength, Cardio, Custom)
- `options` - Optional configuration object
  - `showSummary` - Display summary after completion (default: true)
  - `customId` - Custom identifier for the assessment

---

#### `startWorkoutProgram(config: WorkoutConfig): Promise<WorkoutResult>`

Start a workout program with customization options.

```typescript
import { startWorkoutProgram, WorkoutConfig, BodyZone, Difficulty, Duration } from '@sency/react-native-smkit-ui';

const config = new WorkoutConfig(
  week: 1,
  bodyZone: BodyZone.FullBody,
  difficulty: Difficulty.Medium,
  duration: Duration.Medium,
  programId: 'program-123'
);

const result = await startWorkoutProgram(config);
```

---

#### `startCustomAssessment(config: CustomAssessmentConfig): Promise<AssessmentResult>`

Start a custom assessment (assessment configured by Sency for your specific needs).

```typescript
import { startCustomAssessment } from '@sency/react-native-smkit-ui';

const result = await startCustomAssessment({
  customId: 'assessment-123',
  showSummary: true
});
```

---

### Configuration Methods

#### `setPauseTypes(types: PauseType[]): Promise<void>`

Configure which buttons appear in the pause menu during workouts and assessments.

```typescript
import { setPauseTypes, PauseType } from '@sency/react-native-smkit-ui';

await setPauseTypes([
  PauseType.Resume,
  PauseType.Skip,
  PauseType.Quit
]);
```

**Parameters:**
- `types` - Array of pause button types to display. Available types: `Resume`, `Skip`, `StartOver`, `Quit`, `Rest`, `Switch`

---

#### `setSkeletonSettings(config: SkeletonConfig): Promise<void>`

Customize the skeleton visualization style during exercises.

```typescript
import { setSkeletonSettings, SkeletonPreset, SkeletonConnectionStyle } from '@sency/react-native-smkit-ui';

await setSkeletonSettings({
  preset: SkeletonPreset.NeonGlow,
  connectionStyle: SkeletonConnectionStyle.Solid,
  dotsOpacity: 1,
  connectionsOpacity: 0.8
});
```

---

#### `setInstructionVideoConfig(config: VideoInstructionConfig): Promise<void>`

Configure how instruction videos are displayed.

```typescript
import { setInstructionVideoConfig } from '@sency/react-native-smkit-ui';

await setInstructionVideoConfig({
  displayMode: 'mediumCycle',
  mediumSizeCycles: 2
});
```

---

#### `setAllowAudioMixing(enabled: boolean): Promise<void>`

Allow SDK audio to mix with external app audio. **(iOS only)**

```typescript
import { setAllowAudioMixing } from '@sency/react-native-smkit-ui';

await setAllowAudioMixing(true);
```

---

#### `setShowExternalAudioControl(enabled: boolean): Promise<void>`

Show an in-session button to switch audio source. **(iOS only)**

```typescript
import { setShowExternalAudioControl } from '@sency/react-native-smkit-ui';

await setShowExternalAudioControl(true);
```

---

#### `setAccuratePoseEstimation(enabled: boolean): Promise<void>`

Enable higher-accuracy pose estimation at the cost of performance. **(iOS only)**

```typescript
import { setAccuratePoseEstimation } from '@sency/react-native-smkit-ui';

await setAccuratePoseEstimation(true);
```

---

## Examples

### Complete Setup Example

```typescript
import React, { useEffect, useState } from 'react';
import { View, TouchableOpacity, Text } from 'react-native';
import {
  configure,
  startAssessment,
  startWorkoutProgram,
  AssessmentType,
  BodyZone,
  Difficulty,
  Duration,
  WorkoutConfig
} from '@sency/react-native-smkit-ui';

export default function FitnessApp() {
  const [isConfigured, setIsConfigured] = useState(false);

  useEffect(() => {
    initializeApp();
  }, []);

  const initializeApp = async () => {
    try {
      await configure('YOUR_API_KEY');
      setIsConfigured(true);
    } catch (error) {
      console.error('Configuration failed:', error);
    }
  };

  const handleFitnessAssessment = async () => {
    try {
      const result = await startAssessment(AssessmentType.Fitness, {
        showSummary: true
      });
      console.log('Assessment completed:', result);
    } catch (error) {
      console.error('Assessment failed:', error);
    }
  };

  const handleWorkout = async () => {
    try {
      const config = new WorkoutConfig(
        1,
        BodyZone.FullBody,
        Difficulty.Medium,
        Duration.Medium
      );
      const result = await startWorkoutProgram(config);
      console.log('Workout completed:', result);
    } catch (error) {
      console.error('Workout failed:', error);
    }
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <TouchableOpacity
        onPress={handleFitnessAssessment}
        disabled={!isConfigured}
      >
        <Text>Start Fitness Assessment</Text>
      </TouchableOpacity>

      <TouchableOpacity
        onPress={handleWorkout}
        disabled={!isConfigured}
      >
        <Text>Start Workout</Text>
      </TouchableOpacity>
    </View>
  );
}
```

### Body360 Assessment Example

```typescript
const startBody360Assessment = async () => {
  try {
    const result = await startAssessment(AssessmentType.Body360, {
      showSummary: true,
      customId: `user-${Date.now()}`
    });
    
    if (result.success) {
      console.log('Body360 assessment completed');
      console.log('Results:', result.data);
    }
  } catch (error) {
    console.error('Body360 assessment error:', error);
  }
};
```

### Customized Workout Example

```typescript
const startCustomizedWorkout = async () => {
  try {
    const config = new WorkoutConfig(
      week: 2,
      bodyZone: BodyZone.UpperBody,
      difficulty: Difficulty.High,
      duration: Duration.Long
    );
    
    const result = await startWorkoutProgram(config);
    console.log('Workout program completed:', result);
  } catch (error) {
    console.error('Workout error:', error);
  }
};
```

---

## Troubleshooting

### "Configuration Failed" Error

**Problem:** `configure()` throws an error or returns false.

**Solutions:**
- Verify your API key is correct
- Check your internet connection
- Ensure the SMKit backend service is available
- Call `configure()` before using any other library functions

### Camera Permissions Not Granted

**Problem:** Assessment or workout fails with camera permission error.

**Solutions:**
- Request camera permissions before starting assessments
- Check that permissions are granted in device settings
- On iOS, verify `NSCameraUsageDescription` is in `Info.plist`
- On Android, ensure runtime permissions are requested

### iOS Pod Installation Issues

**Problem:** `pod install` fails or shows version conflicts.

**Solutions:**
```bash
cd ios
rm -rf Pods
rm Podfile.lock
pod cache clean --all
pod install
cd ..
```

### Android Build Failures

**Problem:** Gradle build fails with native dependency errors.

**Solutions:**
```bash
# Clean Gradle caches
rm -rf ~/.gradle/caches/

# Clean project
cd android
./gradlew clean
cd ..

# Rebuild
npm install
yarn android
```

### Motion Detection Not Working

**Problem:** Assessment starts but motion detection fails.

**Solutions:**
- Ensure adequate lighting in the environment
- Position user fully in camera frame
- Verify camera lens is clean
- Check that device camera is not in use by another app

### Library Not Initializing

**Problem:** Features don't work even after calling `configure()`.

**Solutions:**
- Verify `configure()` was called and completed successfully
- Check for error messages in console logs
- Ensure you're not calling library methods before `configure()` completes
- Test with a fresh app start

---

## Additional Resources

- **[API Documentation](API.md)** - Complete API reference with detailed parameters
- **[Changelog](CHANGELOG.md)** - Version history and release notes
- **[Example App](example/)** - Working demonstration app with source code

---

## Support

Need help?

- **Documentation**: See [API.md](API.md) for detailed API documentation
- **Issues**: Check our [GitHub Issues](https://github.com/sency-ai/smkit-sdk/issues)
- **Email**: [support@sency.ai](mailto:support@sency.ai)

---

## License

MIT

---

## Repository

- **GitHub**: [sency-ai/smkit-sdk](https://github.com/sency-ai/smkit-sdk)
- **NPM Package**: [@sency/react-native-smkit-ui](https://www.npmjs.com/package/@sency/react-native-smkit-ui)