React Native SMKit UI Library

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

Native compatibility and session lifecycle

Native dependencies are pinned to iOS SMBase/SMKit/SMKitUI 2.5.1 and Android SMKitUI 1.9.4.

Await each start call and handle rejected promises. Starting another assessment or workout while one is active or stopping rejects with E_SESSION_BUSY without affecting the first call. Results retain the { summary, didFinish } shape.

On iOS, successful resolution follows native teardown, dismissal, and session reset. Teardown failures reject; they are not a camera-stop success signal. On Android, results follow the native workout callback; the bridge remains busy until the SDK Activity closes, including its optional summary screen. An Android result is not a camera-stop completion signal.

Testing local iOS artifacts

After rebuilding all three native frameworks as 2.5.1, run node scripts/prepare-local-ios-pods.cjs <smkitui-checkout> <temporary-pod-directory>. Set SMKIT_LOCAL_IOS_ROOT to that output directory when installing pods in the demos. This selects the rebuilt binaries explicitly without changing published release metadata.

Table of Contents

1. Features
2. Requirements
3. Installation
4. Platform Setup
5. Getting Started
6. Core Features
7. API Reference
8. Examples
9. Troubleshooting
10. 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 15+ (your React Native version may require a higher minimum)
• Xcode 26 (validated toolchain for these native binary artifacts)
• CocoaPods

Android

• Android API 24+ (Android 7.0)
• Android Studio with SDK tools
• JDK 11+

Installation

Install the package via npm:

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

Or with yarn:

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

Then install native dependencies:

cd ios && pod install && cd ..

Platform Setup

iOS Setup

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

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

2. Add use_frameworks! to your target:

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

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

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:

cd ios
NO_FLIPPER=1 pod install
cd ..

5. Add camera permission to Info.plist:

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

Android Setup

1. Update your project-level build.gradle:

buildscript {
    ext {
        minSdkVersion = 24
        // ... other settings
    }
}

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

2. Ensure your app's build.gradle supports Android API 24+:

android {
    compileSdkVersion 36
    defaultConfig {
        minSdkVersion 24
        targetSdkVersion 36
    }
}

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):

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:

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
• Difficulty: Low, Mid, High
• Duration: Short, Long
• Week Number: For multi-week programs

API Reference

Core Methods

configure(apiKey: string, language?: SMWorkoutLibrary.Language): Promise<void>

Initialize the SMKit UI library with your API key. The configure language is optional and defaults to English.

import { configure, SMWorkoutLibrary } from '@sency/react-native-smkit-ui';

await configure('YOUR_API_KEY');
await configure('YOUR_API_KEY', SMWorkoutLibrary.Language.Hebrew);

startAssessment(type, showSummary, userData, forceShowUserDataScreen, customAssessmentID, modifications): Promise<{ summary: string; didFinish: boolean }>

Start a fitness assessment.

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

const userData = new SMWorkoutLibrary.UserData(
  SMWorkoutLibrary.Gender.Other,
  35,
  '[email protected]'
);

const result = await startAssessment(
  SMWorkoutLibrary.AssessmentTypes.Fitness,
  true,
  userData,
  false,
  '',
  null
);

Parameters:

• type - The assessment type (Fitness, Body360, Strength, Cardio, Custom)
• showSummary - Display summary after completion
• userData - Optional SMWorkoutLibrary.UserData; pass null when not needed
• forceShowUserDataScreen - Forces the user data screen even when user data is provided
• customAssessmentID - Custom assessment identifier, or an empty string
• modifications - Optional JSON string with exercise feedback parameter modifications

startWorkoutProgram(config: SMWorkoutLibrary.WorkoutConfig, modifications: string | null): Promise<{ summary: string; didFinish: boolean }>

Start a workout program with customization options.

import { startWorkoutProgram, SMWorkoutLibrary } from '@sency/react-native-smkit-ui';

const config = new SMWorkoutLibrary.WorkoutConfig(
  1,
  SMWorkoutLibrary.BodyZone.FullBody,
  SMWorkoutLibrary.WorkoutDifficulty.MidDifficulty,
  SMWorkoutLibrary.WorkoutDuration.Short,
  SMWorkoutLibrary.Language.English,
  'program-123',
  {
    shortIntro: true,
    phonePosition: SMWorkoutLibrary.PhonePosition.Floor,
  }
);

const result = await startWorkoutProgram(config, null);

startCustomAssessment(assessment, userData, forceShowUserDataScreen, showSummary, modifications): Promise<{ summary: string; didFinish: boolean }>

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

import { startCustomAssessment, SMWorkoutLibrary } from '@sency/react-native-smkit-ui';

const assessment = new SMWorkoutLibrary.SMWorkout(
  'assessment-123',
  'Mobility Check',
  null,
  null,
  [],
  null,
  null,
  null
);

const result = await startCustomAssessment(assessment, null, false, true, null);

Configuration Methods

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

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

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

await setPauseTypes([
  SMWorkoutLibrary.PauseType.Resume,
  SMWorkoutLibrary.PauseType.Skip,
  SMWorkoutLibrary.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.

import { setSkeletonSettings, SMWorkoutLibrary } from '@sency/react-native-smkit-ui';

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

setInstructionVideoConfig(config: VideoInstructionConfig): Promise<void>

Configure how instruction videos are displayed.

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. Supported on iOS and Android native SDKs that expose the control.

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. Supported on iOS and Android native SDKs that expose the control.

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)

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

await setAccuratePoseEstimation(true);

Advanced SDK controls

These setters are exported directly from the React Native package and return Promise<void> unless noted. Platform-specific methods validate their input and resolve as a no-op on unsupported platforms.

| Method | Purpose | |--------|---------| | setColorTheme(theme) | Applies a native SDK color theme. | | setPlayPhoneCalibrationAudio(enabled) | Enables phone calibration audio. | | setPlayBodyCalibrationAudio(enabled) | Enables body calibration audio. | | setStartTimerOnFirstActivity(enabled) | Starts exercise timers on first detected activity. | | setWorkoutContinuationTimerDuration(seconds) | Sets the continuation countdown duration. | | setPhoneMovementCountPreventionEnabled(enabled) | Prevents counting while phone movement is detected. | | setVariationMismatchFeedbackEnabled(enabled) | Enables variation mismatch feedback. | | setUseDefaultGuidanceMode(enabled) | Lets native SDK defaults drive guidance mode. | | setGuidanceModeSuggestionEnabled(enabled) | Android and iOS guidance suggestions. | | setGuidanceDebugLogging(enabled) | Enables native guidance debug logging where supported. | | setSmallBodyPartFocusEnabled(enabled) | Android and iOS small-body-part focus. | | setExerciseSummaryTimingMetricsEnabled(enabled) | Android configure-time and iOS runtime timing metrics. | | setIncludeAssessmentInsights(enabled) | Configure-time assessment insights on Android and iOS. | | setEnableButtonTutorial(enabled) | Shows the button tutorial overlay. | | setButtonTutorialCompletionAudioUri(uri) | Sets optional tutorial completion audio. | | setShowDebugBoundingBox(enabled) | iOS pose debug bounding-box control; Android no-op. | | setEnableWatchCompanion(enabled) | iOS Apple Watch companion control; Android no-op. | | setEnableHeartRateRest(enabled) | iOS Watch heart-rate-rest control; Android no-op. | | setHeartRateRestThreshold(bpm) | iOS Watch heart-rate-rest threshold; Android no-op. | | setShowRowingPhoneCalibration(enabled) | iOS rowing phone calibration control; Android no-op. | | setFeedbacksUIToExclude(values) | Hides selected native feedback types from UI. | | setExcludedFeedbacks(values) | Excludes selected feedbacks where supported. | | setConfigString(value) | Android native flat config string; iOS no-op. | | clearAdaptiveRomCache() | Clears adaptive ROM cache where supported. | | quitWorkout() | Quits the active workout where supported. | | pauseSDK() / resumeSDK() | iOS active-workout pause and resume; Android 1.9.4 rejects as unsupported. | | getSupportedMovements() | iOS supported movement names; Android 1.9.4 rejects as unsupported. | | getExerciseType(detector) | iOS exercise type lookup; Android 1.9.4 rejects as unsupported. | | setPoseModelChoice(choice) | Android pose model choice before configure; iOS no-op. | | configure(key, language, options) | Customer code, voices, feedback frequency and iOS model/download/audio options. | | getCustomerAssetPath(id) / requestCustomerAssetPath(id) | Local asset lookup and retrieval on both platforms. | | preloadModels(), skipCurrentExercise(), handleExternalCallback(url) | iOS-only controls; Android rejects as unsupported. The iOS callback entrypoint is deprecated and returns false. | | loadInstructionVideo(detector), setVideo(url, limitFps?) | iOS-only video APIs; Android rejects as unsupported. |

import {
  setColorTheme,
  setPlayPhoneCalibrationAudio,
  setPlayBodyCalibrationAudio,
  setPhoneMovementCountPreventionEnabled,
  setPoseModelChoice,
  SMWorkoutLibrary,
} from '@sency/react-native-smkit-ui';

await setColorTheme(SMWorkoutLibrary.ColorTheme.Green);
await setPlayPhoneCalibrationAudio(true);
await setPlayBodyCalibrationAudio(true);
await setPhoneMovementCountPreventionEnabled(true);
await setPoseModelChoice(SMWorkoutLibrary.PoseModelChoice.AdaptiveChoice);

For Android 1.9.4 configuration-only controls, set values before configure():

import {
  configure,
  setExerciseSummaryTimingMetricsEnabled,
  setGuidanceModeSuggestionEnabled,
  setIncludeAssessmentInsights,
  setPoseModelChoice,
  setSmallBodyPartFocusEnabled,
  SMWorkoutLibrary,
} from '@sency/react-native-smkit-ui';

await setPoseModelChoice(SMWorkoutLibrary.PoseModelChoice.AdaptiveChoice);
await setGuidanceModeSuggestionEnabled(true);
await setSmallBodyPartFocusEnabled(true);
await setExerciseSummaryTimingMetricsEnabled(true);
await setIncludeAssessmentInsights(true);
await configure('YOUR_API_KEY');

Interactive Talk to Jinni is intentionally not exposed by this React Native SDK.

Advanced custom workout options

SMExercise, SMAssessmentExercise, and WorkoutConfig keep their existing constructor arguments and accept optional trailing options objects for newer native SDK features.

import { startCustomWorkout, SMWorkoutLibrary } from '@sency/react-native-smkit-ui';

const exercise = new SMWorkoutLibrary.SMExercise(
  'Squat',
  45,
  'squat_instruction.mp4',
  'squat_intro.mp3',
  [
    SMWorkoutLibrary.UIElement.RepsCounter,
    SMWorkoutLibrary.UIElement.Skeleton,
    SMWorkoutLibrary.UIElement.CountdownTimer,
  ],
  'SquatRegular',
  null,
  new SMWorkoutLibrary.SMScoringParams(
    SMWorkoutLibrary.ScoringType.Reps,
    null,
    null,
    12,
    null,
    null
  ),
  {
    shortIntro: true,
    guidanceMode: true,
    guidanceVideoSegments: {
      introFreeze: SMWorkoutLibrary.GuidanceVideoSegment.freeze(1.2),
      demoLoop: SMWorkoutLibrary.GuidanceVideoSegment.play(2.0, 6.5),
    },
    playPreExerciseCountdown: true,
    playSoundOnEachRep: true,
    playRepMilestoneVoice: true,
    repMilestoneInterval: 5,
    showTargetProgress: true,
    playTargetRepsCompletionVoice: true,
    intentVoiceFeedbackEnabled: true,
    enableGuidanceModeSuggestion: true,
    enableSmallBodyPartFocus: true,
    adaptiveRomFeedbackEnabled: true,
    adaptiveRomWarmupReps: 3,
    stretchSetConfig: new SMWorkoutLibrary.StretchSetConfig(3, 20, {
      restSecondsBetweenStretches: 5,
    }),
    positionRepConfig: new SMWorkoutLibrary.PositionRepConfig(3, 5),
    internalInsightsKey: 'squat-regular',
    displayContext: new SMWorkoutLibrary.ExerciseDisplayContext({
      sectionTitle: 'MAIN SET',
      playsTitleSound: true,
      group: new SMWorkoutLibrary.ExerciseDisplayGroup(
        'circuit-1',
        SMWorkoutLibrary.ExerciseDisplayGroupKind.Circuit,
        1,
      ),
    }),
  }
);

const continuation = new SMWorkoutLibrary.WorkoutContinuation(
  'continue_unlock.mp3',
  [exercise],
  'continue_intro.mp3'
);

const workout = new SMWorkoutLibrary.SMWorkout(
  'workout-123',
  'Strength Builder',
  null,
  null,
  [exercise],
  null,
  null,
  null,
  continuation,
  { exportInternalInsights: true }
);

await startCustomWorkout(workout, null);

The supported exercise options include shortIntro, quickMotionParams, rowingFeedbackLevel, phonePosition, guidanceMode, useWideAngleCamera, playPreExerciseCountdown, playRepMilestoneVoice, repMilestoneInterval, playSoundOnEachRep, showTargetProgress, adaptiveRomFeedbackEnabled, adaptiveRomWarmupReps, guidanceVideoSegments, stretchSetConfig, side, and displayContext.

Android 1.9.4 also supports playTargetRepsCompletionVoice, intentVoiceFeedbackEnabled, enableGuidanceModeSuggestion, enableSmallBodyPartFocus, positionRepConfig, and internalInsightsKey. Set SMWorkout's exportInternalInsights option with setIncludeAssessmentInsights(true) before configure when the custom assessment should return those insights.

For reps scoring, targetReps stays available for scoring and summary data. Add showTargetProgress: true only when the timer slot should show completed/target reps and finish at the target; omit it to keep the normal timer behavior.

Examples

Complete Setup Example

import React, { useEffect, useState } from 'react';
import { View, TouchableOpacity, Text } from 'react-native';
import {
  configure,
  startAssessment,
  startWorkoutProgram,
  SMWorkoutLibrary
} 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(
        SMWorkoutLibrary.AssessmentTypes.Fitness,
        true,
        null,
        false,
        '',
        null
      );
      console.log('Assessment completed:', result);
    } catch (error) {
      console.error('Assessment failed:', error);
    }
  };

  const handleWorkout = async () => {
    try {
      const config = new SMWorkoutLibrary.WorkoutConfig(
        1,
        SMWorkoutLibrary.BodyZone.FullBody,
        SMWorkoutLibrary.WorkoutDifficulty.MidDifficulty,
        SMWorkoutLibrary.WorkoutDuration.Short,
        SMWorkoutLibrary.Language.English,
        'program-123'
      );
      const result = await startWorkoutProgram(config, null);
      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

const startBody360Assessment = async () => {
  try {
    const result = await startAssessment(
      SMWorkoutLibrary.AssessmentTypes.Body360,
      true,
      null,
      false,
      '',
      null
    );
    
    if (result.didFinish) {
      console.log('Body360 assessment completed');
      console.log('Summary:', result.summary);
    }
  } catch (error) {
    console.error('Body360 assessment error:', error);
  }
};

Customized Workout Example

const startCustomizedWorkout = async () => {
  try {
    const config = new SMWorkoutLibrary.WorkoutConfig(
      2,
      SMWorkoutLibrary.BodyZone.UpperBody,
      SMWorkoutLibrary.WorkoutDifficulty.HighDifficulty,
      SMWorkoutLibrary.WorkoutDuration.Long,
      SMWorkoutLibrary.Language.English,
      'program-123',
      { shortIntro: true }
    );
    
    const result = await startWorkoutProgram(config, null);
    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:

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:

# 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 - Complete API reference with detailed parameters
• Changelog - Version history and release notes
• Example App - Working demonstration app with source code

Support

Need help?

• Documentation: See API.md for detailed API documentation
• Issues: Check our GitHub Issues
• Email: [email protected]

License

MIT

Repository

• GitHub: sency-ai/smkit-sdk
• NPM Package: @sency/react-native-smkit-ui

Configure and exercise options

configure(key, language, options) accepts customer code, feedback and mobility voices, feedback frequency, highlights, assessment insights, and iOS model download and presentation/audio options. Unsupported Android 1.9.4 configure options reject with UNSUPPORTED_PLATFORM. To select the iOS target-reps timer, set an exercise's options.targetRepsTimerDisplayMode to repsProgress or timeProgress.

Note: iOS 2.5.1 accepts enablePerExerciseBodyCalibration, but its native per-exercise flow is currently disabled by an internal release gate.