# KinesteX SDK Documentation — Full Text
> Complete KinesteX SDK documentation. Source: https://www.kinestex.com/docs
This file concatenates every documentation section as Markdown for AI agents and LLMs. Code samples are included for all supported platforms (Swift, Kotlin, React Native, Flutter, HTML/JavaScript, React TypeScript).
---
## Getting Started
KinesteX offers a powerful motion tracking SDK that seamlessly integrates into your platform. Choose between ready-made workouts, plans, challenges, AI assessments, or create custom experiences with our advanced motion tracking.
### Overview
Our white-label solution supports any camera-enabled device across Android, iOS, and web, with SDKs for React Native, Flutter, Kotlin, Swift, Java, PWA, and JavaScript for quick integration.
KinesteX's real-time AI motion tracking boosts engagement, retention, and revenue while providing valuable data insights to create personalized, growth-driving experiences.
#### Plug and Play Integration
Pre-built experiences ready to integrate. Customize colors, fonts, and certain UI/UX elements while we handle the core workout experience, motion tracking, and user flow.
##### Complete UX (Main)
Full experience with personalized plan selection, user survey, and AI-generated workout schedules.
##### Plan View
Display a specific workout plan with schedule and multiple workouts.
##### Workout View
Launch directly into a specific workout by name or ID.
##### Challenge View
Gamified exercise challenges with leaderboards and rep tracking.
##### Leaderboard View
Display real-time leaderboards for challenge exercises as a standalone view.
##### AI Experiences
Interactive fitness games like Balloon Pop, Color Chase, and Alien Squat Shooter.
##### Personalized Plan
AI-generated workout plans tailored to user biometrics, fitness level, and assessment results.
##### AI Trainer Chat
Conversational AI personal trainer with in-app fitness assessment, personalized workout generation, and next-session scheduling.
Full guide: [AI Trainer Chat](/docs/ai-trainer-chat)
##### Admin Workout Editor
Embedded view for creating and managing workouts and exercises. Receive events for workout/exercise creation, selection, and updates. Flutter and Swift.
#### Custom Integration
Build everything yourself with full control over UI/UX. Use our Content APIs to fetch workout data and the Camera Component for real-time motion analysis.
##### Custom Workout
Create personalized workout sequences with custom exercises, reps, durations, and rest periods. Full control over exercise order and timing.
##### Camera Component
Access raw pose analysis data to build your own custom workout UI. Receive real-time rep counts, form feedback, and body tracking data.
##### Content Fetching APIs
Fetch workout plans, exercises, and content data via REST APIs. Build your own content browsing and workout selection experience.
### Requirements
**Platform Versions:**
• iOS 14.0+
• Android API 26+
• Web browser support (Chrome, Safari, Firefox, Edge)
**Prerequisites:**
• API key from KinesteX
• Camera permissions
• Internet connection
### Get API Key
To get demo access and your API key, fill out the contact form on our website.
[Contact Us](/#contact-form)
---
## Installation
Follow these steps to install the KinesteX SDK in your project.
### Step 1: Add Dependencies
Add the KinesteX SDK to your project using your platform's package manager.
**Install SDK**
_Swift (iOS)_
```swift
1. In Xcode: File > Add Package Dependencies...
2. Enter URL: https://github.com/KinesteX/KinesteX-AI-Kit.git
3. Click "Add Package"
```
_Kotlin (Android)_
```kotlin
// 1. Add JitPack repository in settings.gradle.kts
dependencyResolutionManagement {
repositories {
maven { url = uri("https://jitpack.io") }
}
}
// 2. Add dependency in app/build.gradle.kts
dependencies {
// Use the latest release from https://github.com/KinesteX/KinesteX-SDK-Kotlin/releases
implementation("com.github.KinesteX:KinesteX-SDK-Kotlin:2.0.9")
}
// 3. Sync project with Gradle files
```
_React Native_
```jsx
// 1. Install packages
npm install kinestex-sdk-react-native react-native-webview
// 2. Install iOS dependencies
cd ios && pod install && cd ..
// For Expo projects:
npx expo install react-native-webview
```
_Flutter_
```dart
# 1. Add to pubspec.yaml
dependencies:
kinestex_sdk_flutter: ^1.5.1 # use the latest version from pub.dev
permission_handler: ^11.3.1
# 2. Install packages
flutter pub get
# 3. Install iOS dependencies
cd ios && pod install && cd ..
```
_HTML / JavaScript_
```html
```
_React (TypeScript)_
```tsx
npm i kinestex-sdk-react-ts
```
### Step 2: Configure Permissions
Add the required permissions for camera and motion sensors.
**Required Permissions**
_Swift (iOS)_
```swift
NSCameraUsageDescriptionCamera access is required for AI-powered workout trackingNSMotionUsageDescriptionMotion sensors help position your device correctly for workouts
```
_Kotlin (Android)_
```kotlin
```
_React Native_
```jsx
NSCameraUsageDescriptionCamera access is required for AI-powered workout trackingNSMotionUsageDescriptionMotion sensors help position your device correctly for workouts
```
_Flutter_
```dart
NSCameraUsageDescriptionCamera access is required for AI-powered workout trackingNSMotionUsageDescriptionMotion sensors help position your device correctly for workouts
```
_HTML / JavaScript_
```html
```
_React (TypeScript)_
```tsx
Browser will prompt users for camera access automatically. No additional permissions are needed.
```
### Step 3: Import the SDK
Import the KinesteX SDK in your code to start using it.
**Import Statement**
_Swift (iOS)_
```swift
import KinesteXAIKit
```
_Kotlin (Android)_
```kotlin
import com.kinestex.kinestexsdkkotlin.KinesteXSDK
```
_React Native_
```jsx
import KinestexSDK from 'kinestex-sdk-react-native';
// Types and enums live in the /src/types subpath (the package root has only the default export)
import { IntegrationOption, IPostData, PlanCategory } from 'kinestex-sdk-react-native/src/types';
```
_Flutter_
```dart
import 'package:kinestex_sdk_flutter/kinestex_sdk.dart';
```
_HTML / JavaScript_
```html
// Define the iframe element and create a URL to be later used to load the iframe
const webView = document.getElementById('webView');
const srcURL = 'https://ai.kinestex.com';
```
_React (TypeScript)_
```tsx
import {
IntegrationOption,
KinesteXSDK,
type IPostData,
type KinesteXSDKCamera,
} from "kinestex-sdk-react-ts";
```
**Step 4: iOS 15+ Device Orientation Fix (Required)** — React Native
react-native-webview doesn't support iOS 15+ motion permissions by default. Apply this patch to enable device orientation tracking:
_4.1: Install patch-package_
```bash
npm install patch-package postinstall-postinstall --save-dev
```
_4.2: Add postinstall script to package.json_
```json
{
"scripts": {
"postinstall": "patch-package"
}
}
```
_4.3: Patch RNCWebViewImpl.m_
```objectivec
// Edit: node_modules/react-native-webview/apple/RNCWebViewImpl.m
// Find requestMediaCapturePermissionForOrigin (line ~1312)
// Add this method after it:
- (void)webView:(WKWebView *)webView
requestDeviceOrientationAndMotionPermissionForOrigin:(WKSecurityOrigin *)origin
initiatedByFrame:(WKFrameInfo *)frame
decisionHandler:(void (^)(WKPermissionDecision))decisionHandler {
(void)webView;
(void)origin;
(void)frame;
decisionHandler(WKPermissionDecisionGrant);
}
```
_4.4: Save the patch_
```bash
npx patch-package react-native-webview
```
**Step 5: Expo Android Camera Fix** — React Native
For Expo on Android, request app-level camera permission before displaying KinesteX:
_5.1: Install expo-camera_
```bash
npx expo install expo-camera
```
_5.2: Configure app.json_
```json
{
"expo": {
"android": {
"permissions": ["android.permission.CAMERA"]
},
"ios": {
"infoPlist": {
"NSCameraUsageDescription": "For AI Motion Tracking"
}
}
}
}
```
_5.3: Request permission before showing KinesteX_
```typescript
import { Camera } from 'expo-camera';
import { useState, useEffect } from 'react';
const [hasPermission, setHasPermission] = useState(false);
useEffect(() => {
(async () => {
const { status } = await Camera.requestCameraPermissionsAsync();
setHasPermission(status === 'granted');
})();
}, []);
// Only render KinesteX when hasPermission is true
```
---
## Configuration
Initialize the SDK with your API credentials.
**Step 1: Initialize the SDK**
_Swift (iOS)_
```swift
import KinesteXAIKit
@State var showKinesteX = false // Controls KinesteX SDK visibility
@State var isLoading = false // Optional: Controls custom loading screen
// Initialize with your API key, company name, and unique user ID
let kinestex = KinesteXAIKit(
apiKey: "YOUR_API_KEY",
companyName: "YOUR_COMPANY",
userId: "unique-user-id"
)
// Optional: UserDetails to customize workout intensity
let user = UserDetails(
age: 20,
height: 170,
weight: 70,
gender: .Male,
lifestyle: .Active
)
```
_Kotlin (Android)_
```kotlin
import com.kinestex.kinestexsdkkotlin.KinesteXSDK
// Initialize the SDK in your Application class as early as possible
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
KinesteXSDK.initialize(
context = this,
apiKey = "YOUR_API_KEY",
companyName = "YOUR_COMPANY",
userId = "unique-user-id"
)
}
}
```
_React Native_
```jsx
// 1. Create a reference to KinesteXSDK component
const kinestexSDKRef = useRef(null);
// 2. Create postData object to initialize KinesteX session
const postData: IPostData = {
key: 'YOUR_API_KEY',
userId: 'YOUR_USER_ID', // unique per user
company: 'YOUR_COMPANY',
style: {
style: 'dark', // 'dark' or 'light'
loadingBackgroundColor: '000000', // hex without #
},
customParameters: {
// language: 'es' // customize language
},
// Optional: UserDetails for workout intensity
age: 25,
height: 180, // cm
weight: 75, // kg
gender: 'Male',
lifestyle: Lifestyle.Active,
};
// 3. Handle real-time messages from KinesteX
const handleMessage = (type: string, data: { [key: string]: any }) => {
switch (type) {
case 'exit_kinestex':
console.log('User exited');
setShowKinesteX(false);
break;
case 'plan_unlocked':
console.log('Plan unlocked:', data);
break;
default:
console.log('Message:', type, data);
break;
}
};
```
_Flutter_
```dart
import 'package:kinestex_sdk_flutter/kinestex_sdk.dart';
// Initialize the SDK in your main function as early as possible.
await KinesteXAIFramework.initialize(
apiKey: "YOUR_API_KEY",
companyName: "YOUR_COMPANY",
userId: "unique-user-id",
);
```
_HTML / JavaScript_
```html
// 1. Define the config data to be sent to the iframe
const postData = {
userId: "YOUR_USER_ID", // Unique identifier for the user
company: "YOUR_COMPANY", // Your organization's name from kinestex admin dashboard
key: "YOUR_API_KEY", // Your API Key from kinestex admin dashboard
// Optional parameters for customization
style: "dark", // dark or light theme
// user related customization
age: 30, // User's age (optional)
height: 175, // User's height in cm (optional)
weight: 70, // User's weight in kg (optional)
gender: "Female", // Gender (optional)
};
// 2. Sending the messages to the iframe will be done through postMessage API
function sendMessage() {
if (webView.contentWindow) {
webView.contentWindow.postMessage(postData, srcURL); // post initial data to start session
} else {
setTimeout(() => {
try {
webView.contentWindow.postMessage(postData, srcURL); // post initial data to start session
} catch {
webView.contentWindow.postMessage(postData, srcURL); // retry sending message
}
}, 100);
}
}
// 3. Whenever you want to display the view:
webView.src = srcURL; // Update this URL for specific features
webView.onload = () => {
sendMessage();
};
// 4. Handle the loading confirmation received from the iframe to send the initial data once more (iOS specific verification)
window.addEventListener("message", (event) => {
if (event.origin !== "https://ai.kinestex.com") return; // prevent listening for messages from other sources for security
const message = JSON.parse(event.data);
if (message.type === 'kinestex_loaded') {
sendMessage();
}
});
```
_React (TypeScript)_
```tsx
// 1. Create a reference to KinesteXSDK component
const kinestexSDKRef = useRef(null);
// 2. Create postData object to initialize KinesteX session
const postData: IPostData = {
key: 'YOUR_API_KEY',
userId: 'YOUR_USER_ID', // unique per user
company: 'YOUR_COMPANY',
style: {
style: 'dark', // 'dark' or 'light'
loadingBackgroundColor: '000000', // hex without #
},
customParameters: {
// language: 'es' // customize language
},
// Optional: UserDetails for workout intensity
age: 25,
height: 180, // cm
weight: 75, // kg
gender: 'Male',
lifestyle: Lifestyle.Active,
};
// 3. Handle real-time messages from KinesteX
const handleMessage = (type: string, data: { [key: string]: any }) => {
switch (type) {
case 'exit_kinestex':
console.log('User exited');
setShowKinesteX(false);
break;
case 'plan_unlocked':
console.log('Plan unlocked:', data);
break;
default:
console.log('Message:', type, data);
break;
}
};
```
**Step 2: Register Application Class** — Kotlin (Android)
Register your custom Application class in AndroidManifest.xml:
_AndroidManifest.xml_
```xml
```
**Step 3: Request Camera Permission** — Kotlin (Android)
Before a user starts a workout, request camera permission at the app level. Your activity or fragment must implement the PermissionHandler interface:
_MainActivity with PermissionHandler_
```kotlin
class MainActivity : AppCompatActivity(), PermissionHandler {
// Initialize the webview
private var kinesteXWebView: GenericWebView? = null
// Optional: Pass user details to adjust exercises and estimate calories
// Note: User details are only used on the device for customization during the session
private var userDetails = UserDetails(
age = 20,
height = 170,
weight = 180,
gender = Gender.MALE,
lifestyle = Lifestyle.ACTIVE
)
// Register permission launcher
private val requestPermissionLauncher = registerForActivityResult(
ActivityResultContracts.RequestPermission()
) { isGranted: Boolean ->
// Pass permission result to KinesteX webview
kinesteXWebView?.handlePermissionResult(isGranted)
}
// Override to display system dialog for camera access
override fun requestCameraPermission() {
requestPermissionLauncher.launch(Manifest.permission.CAMERA)
}
}
```
**Step 4: Handle SDK Messages** — Kotlin (Android)
Implement a callback function to handle messages from the SDK:
_Message Handler_
```kotlin
private fun handleWebViewMessage(message: WebViewMessage) {
when (message) {
is WebViewMessage.ExitKinestex -> {
// Dismiss KinesteX view when user clicks exit button
}
// Handle other messages
else -> {
Log.d("KinesteX", message.toString())
}
}
}
```
**Step 2: Request Camera Permission** — Flutter
Request camera permission before launching KinesteX. Ensure you've added the necessary permissions in AndroidManifest.xml and Info.plist. Add the following to your iOS Podfile:
_2.1: ios/Podfile_
```ruby
post_install do |installer|
installer.pods_project.targets.each do |target|
flutter_additional_ios_build_settings(target)
target.build_configurations.each do |config|
config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
'$(inherited)',
## dart: PermissionGroup.camera
'PERMISSION_CAMERA=1',
]
end
end
end
```
_2.2: Request Permission in Dart_
```dart
void _checkCameraPermission() async {
if (await Permission.camera.request() != PermissionStatus.granted) {
_showCameraAccessDeniedAlert();
}
}
void _showCameraAccessDeniedAlert() {
showDialog(
context: context,
builder: (BuildContext context) {
return AlertDialog(
title: const Text("Camera Permission Denied"),
content: const Text("Camera access is required for this app to function properly."),
actions: [
TextButton(
child: const Text("OK"),
onPressed: () {
Navigator.of(context).pop();
},
),
],
);
},
);
}
```
**Step 3: Initialize on App Launch** — Flutter
Initialize KinesteX in your main function for WebView warmup:
_main.dart_
```dart
Future main() async {
await KinesteXAIFramework.initialize(
apiKey: YOUR_API_KEY,
companyName: YOUR_COMPANY_NAME,
userId: YOUR_USER_ID,
);
runApp(
const MaterialApp(
home: MyHomePage(),
),
);
}
```
**Step 4: Deinitialize on App Closure** — Flutter
Call dispose when closing the app:
_Dispose Method_
```dart
@override
void dispose() {
disposeKinesteXAIFramework();
super.dispose();
}
```
**Step 5: Setup Recommendations** — Flutter
Use a ValueNotifier to manage KinesteX presentation and handle callback messages:
_State Management & Message Handler_
```dart
import 'package:kinestex_sdk_flutter/kinestex_sdk.dart';
// Add a ValueNotifier to manage presentation
ValueNotifier showKinesteX = ValueNotifier(false);
// Handle callback messages from KinesteX
void handleWebViewMessage(WebViewMessage message) {
if (message is ExitKinestex) {
setState(() {
showKinesteX.value = false;
});
} else {
print("Message received: ${message.data}");
}
}
```
---
## Integration Options
Choose the integration option that best fits your use case. Each option provides a different level of UI customization.
Looking for a guided, conversational coaching experience? See the [AI Trainer Chat](/docs/ai-trainer-chat) integration guide — a chat-based AI personal trainer with workout launching and next-session scheduling.
### Plug and Play Integration
Pre-built experiences ready to integrate. Customize colors, fonts, and certain UI/UX elements while we handle the core workout experience, motion tracking, and user flow.
#### Complete UX (Main)
Display the full KinesteX experience with personalized workout plan selection based on category. Includes user survey, assessment, and personalized schedule generation. This is the easiest integration option.
**Available Plan Categories:**
| Plan Category | Key |
|---------------|-----|
| Strength | Strength |
| Cardio | Cardio |
| Weight Management | Weight Management |
| Rehabilitation | Rehabilitation |
| Custom | Custom |
**Define Plan Category**
First, define the plan category for personalized fitness goals:
_Swift (iOS)_
```swift
// Plan category for personalized fitness goals
@State private var planCategory: PlanCategory = .Cardio
```
_Kotlin (Android)_
```kotlin
// Plan category for personalized fitness goals
private var planCategory = PlanCategory.Cardio
```
_React Native_
```jsx
// Plan category for personalized fitness goals
const planCategory = PlanCategory.Cardio; // Strength, Cardio, etc.;
```
_Flutter_
```dart
// Plan category for personalized fitness goals
PlanCategory planCategory = PlanCategory.Cardio;
```
_HTML / JavaScript_
```html
// Plan category for personalized fitness goals
const planCategory = "Cardio";
```
_React (TypeScript)_
```tsx
// Plan category for personalized fitness goals
const planCategory = PlanCategory.Cardio; // Strength, Cardio, etc.
```
**Display Category View**
Display the category-based view with real-time message handling:
_Swift (iOS)_
```swift
kinestex.createCategoryView(
planCategory: planCategory,
user: user, // optional: can be nil
isLoading: $isLoading,
customParams: ["style": "dark"], // dark or light theme
onMessageReceived: { message in
switch message {
case .kinestex_launched(let data):
print("KinesteX Launched: \(data)")
case .finished_workout(let data):
print("Workout Finished: \(data)")
case .exit_kinestex(let data):
showKinesteX = false // Dismiss the view
default:
print("Received \(message)")
break
}
}
)
// OPTIONAL: Display loading screen during view initialization
.overlay(
Group {
if showAnimation {
Text("Aifying workouts...")
.foregroundColor(.black)
.font(.caption)
.frame(maxWidth: .infinity, maxHeight: .infinity)
.background(Color.white)
}
}
)
.onChange(of: isLoading) { newValue in
withAnimation(.easeInOut(duration: 2.5)) {
showAnimation = !newValue
}
}
```
_Kotlin (Android)_
```kotlin
KinesteXSDK.createMainView(
context = this,
planCategory = planCategory,
user = userDetails, // optional user details
customParams = mutableMapOf("style" to "dark"),
isLoading = viewModel.isLoading,
onMessageReceived = { message ->
when (message) {
is WebViewMessage.KinestexLaunched ->
println("KinesteX Launched")
is WebViewMessage.FinishedWorkout ->
println("Workout Finished: ${message.data}")
is WebViewMessage.ExitKinestex -> finish()
else -> println("Received: $message")
}
},
permissionHandler = this
)
```
_React Native_
```jsx
// postData structure
const postData: IPostData = {
key: 'YOUR_API_KEY',
userId: 'YOUR_USER_ID',
company: 'YOUR_COMPANY_NAME',
planCategory: planCategory,
style: {
style: 'dark', // or 'light'
},
};
{
switch (type) {
case 'kinestex_launched':
console.log('KinesteX Launched:', data);
break;
case 'finished_workout':
console.log('Workout Finished:', data);
break;
case 'exit_kinestex':
setShowKinesteX(false);
break;
}
}}
/>
```
_Flutter_
```dart
KinesteXAIFramework.createMainView(
isShowKinestex: showKinesteX,
planCategory: planCategory,
customParams: {"style": "dark"},
isLoading: ValueNotifier(false),
onMessageReceived: (message) {
if (message is KinestexLaunched) {
print('KinesteX Launched');
} else if (message is FinishedWorkout) {
print('Workout Finished: ${message.data}');
} else if (message is ExitKinestex) {
setState(() {
showKinesteX.value = false;
});
}
},
)
```
_HTML / JavaScript_
```html
// Add planCategory to postData
const postData = {
// ... all initial fields
planCategory: planCategory, // "Strength", "Cardio", etc.
};
const srcURL = "https://ai.kinestex.com";
webView.src = srcURL;
webView.onload = () => {
sendMessage();
};
// Handle messages
window.addEventListener('message', (event) => {
const { type, data } = event.data;
switch (type) {
case 'kinestex_launched':
console.log('KinesteX Launched:', data);
break;
case 'exit_kinestex':
// Hide the iframe
break;
}
});
```
_React (TypeScript)_
```tsx
import { IntegrationOption, KinesteXSDK, PlanCategory, type IPostData } from 'kinestex-sdk-react-ts';
// postData structure
const postData: IPostData = {
key: 'YOUR_API_KEY',
userId: 'YOUR_USER_ID',
company: 'YOUR_COMPANY_NAME',
planCategory: PlanCategory.Cardio,
style: {
style: 'dark',
},
};
{
switch (type) {
case 'kinestex_launched':
console.log('KinesteX Launched:', data);
break;
case 'finished_workout':
console.log('Workout Finished:', data);
break;
case 'exit_kinestex':
setShowKinesteX(false);
break;
}
}}
/>
```
**Complete Example**
Full implementation example with all required setup:
_Swift (iOS)_
```swift
import SwiftUI
import KinesteXAIKit
struct MainViewIntegration: View {
@State private var showKinesteX = false
@State private var isLoading = false
// Replace with your KinesteX credentials
let kinesteXKit = KinesteXAIKit(
apiKey: "YOUR API KEY",
companyName: "YOUR COMPANY NAME",
userId: "YOUR USER ID"
)
// Plan category for personalized fitness goals
@State private var planCategory: PlanCategory = .Cardio
var body: some View {
VStack {
Text("KinesteX Main View")
.font(.title)
.padding()
Spacer()
Button(action: {
showKinesteX.toggle()
}) {
Text("Open Main View")
.font(.title3)
.foregroundColor(.white)
.bold()
.padding()
.frame(maxWidth: .infinity)
.background(Color.green.cornerRadius(10))
.padding(.horizontal)
}
Spacer()
}
.fullScreenCover(isPresented: $showKinesteX) {
kinestex.createCategoryView(
planCategory: planCategory,
user: nil,
isLoading: $isLoading,
customParams: ["style": "light"],
onMessageReceived: { message in
switch message {
case .exit_kinestex(_):
showKinesteX = false
default:
print("Message received: \(message)")
}
}
)
}
}
}
#Preview {
MainViewIntegration()
}
```
_Kotlin (Android)_
```kotlin
import android.os.Bundle
import android.widget.Toast
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.runtime.mutableStateOf
import com.kinestex.kinestexsdkkotlin.GenericWebView
import com.kinestex.kinestexsdkkotlin.KinesteXSDK
import com.kinestex.kinestexsdkkotlin.PlanCategory
import com.kinestex.kinestexsdkkotlin.PermissionHandler
import com.kinestex.kinestexsdkkotlin.WebViewMessage
import kotlinx.coroutines.flow.MutableStateFlow
class MainViewActivity : ComponentActivity(), PermissionHandler {
private val viewModel = MainViewModel()
// OPTIONAL: UserDetails to customize workout intensity and calorie estimation
// Note: User details are only used on-device during the session
private val userDetails = UserDetails(
age = 30,
height = 180,
weight = 75,
gender = Gender.MALE,
lifestyle = Lifestyle.ACTIVE
)
// Custom data for the WebView
private val data = mutableMapOf()
// Store reference to the KinesteX WebView
private var kinesteXWebView: GenericWebView? = null
// Register permission launcher
private val requestPermissionLauncher = registerForActivityResult(
ActivityResultContracts.RequestPermission()
) { isGranted: Boolean ->
// Pass permission result to KinesteX webview
kinesteXWebView?.handlePermissionResult(isGranted)
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
data["style"] = "light"
setContent {
val webView = KinesteXSDK.createMainView(
context = this,
planCategory = PlanCategory.Cardio,
user = userDetails,
customParams = data,
isLoading = viewModel.isLoading,
onMessageReceived = ::handleWebViewMessage,
permissionHandler = this
) as GenericWebView
kinesteXWebView = webView
webView.Render()
}
}
private fun handleWebViewMessage(message: WebViewMessage) {
when (message) {
is WebViewMessage.ExitKinestex -> finish()
is WebViewMessage.KinestexLaunched -> viewModel.isLoading.value = false
else -> Toast.makeText(this, "Received: $message", Toast.LENGTH_SHORT).show()
}
}
// When request is sent, display system dialog for camera access
override fun requestCameraPermission() {
requestPermissionLauncher.launch(Manifest.permission.CAMERA)
}
}
class MainViewModel {
val isLoading = MutableStateFlow(true)
}
```
_React Native_
```jsx
import React, { useState } from 'react';
import { View, Button, StyleSheet } from 'react-native';
import KinestexSDK from 'kinestex-sdk-react-native';
import { IntegrationOption, IPostData, PlanCategory } from 'kinestex-sdk-react-native/src/types';
const MainViewIntegration = () => {
const [showKinesteX, setShowKinesteX] = useState(false);
const postData: IPostData = {
key: 'YOUR_API_KEY',
userId: 'YOUR_USER_ID',
company: 'YOUR_COMPANY_NAME',
planCategory: PlanCategory.Cardio,
style: {
style: 'dark',
},
};
return (
{showKinesteX ? (
{
if (type === 'exit_kinestex') {
setShowKinesteX(false);
}
}}
/>
) : (
);
};
const styles = StyleSheet.create({
container: { flex: 1 }
});
export default MainViewIntegration;
```
_Flutter_
```dart
import 'package:flutter/material.dart';
import 'package:kinestex_sdk_flutter/kinestex_sdk.dart';
import 'package:permission_handler/permission_handler.dart';
Future main() async {
WidgetsFlutterBinding.ensureInitialized();
await KinesteXAIFramework.initialize(
apiKey: "your_api_key",
companyName: "your_company_name",
userId: "your_user_id",
);
runApp(const MyApp());
}
class MyApp extends StatefulWidget {
const MyApp({super.key});
@override
State createState() => _MyAppState();
}
class _MyAppState extends State {
@override
void dispose() {
disposeKinesteXAIFramework();
super.dispose();
}
Future disposeKinesteXAIFramework() async {
await KinesteXAIFramework.dispose();
}
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'KinesteX Main View',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: const MyHomePage(),
);
}
}
class MyHomePage extends StatefulWidget {
const MyHomePage({super.key});
@override
State createState() => _MyHomePageState();
}
class _MyHomePageState extends State {
ValueNotifier showKinesteX = ValueNotifier(false);
@override
void initState() {
super.initState();
_checkCameraPermission();
}
void _checkCameraPermission() async {
if (await Permission.camera.request() != PermissionStatus.granted) {
_showCameraAccessDeniedAlert();
}
}
void _showCameraAccessDeniedAlert() {
showDialog(
context: context,
builder: (BuildContext context) {
return AlertDialog(
title: const Text("Camera Permission Denied"),
content: const Text("Camera access is required for this app to function properly."),
actions: [
TextButton(
child: const Text("OK"),
onPressed: () => Navigator.of(context).pop(),
),
],
);
},
);
}
void handleWebViewMessage(WebViewMessage message) {
if (message is ExitKinestex) {
setState(() {
showKinesteX.value = false;
});
}
}
Widget createMainView() {
return Center(
child: KinesteXAIFramework.createMainView(
isShowKinestex: showKinesteX,
planCategory: PlanCategory.Cardio,
customParams: {
"style": "dark",
},
isLoading: ValueNotifier(false),
onMessageReceived: handleWebViewMessage,
),
);
}
@override
Widget build(BuildContext context) {
return ValueListenableBuilder(
valueListenable: showKinesteX,
builder: (context, isShowKinesteX, child) {
return isShowKinesteX
? SafeArea(
child: createMainView(),
)
: Scaffold(
body: Center(
child: ElevatedButton(
style: ElevatedButton.styleFrom(
padding: const EdgeInsets.symmetric(
horizontal: 40,
vertical: 20,
),
backgroundColor: Colors.green,
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(10),
),
),
onPressed: () {
showKinesteX.value = true;
},
child: const Text(
'Start Main View',
style: TextStyle(
fontSize: 20,
fontWeight: FontWeight.bold,
color: Colors.white,
),
),
),
),
);
},
);
}
}
```
_HTML / JavaScript_
```html
KinesteX: Complete User Experience
```
#### Camera Component
KinesteX Motion Recognition: Real-Time Engagement.
- **Interactive Tracking**: Advanced motion recognition for immersive fitness experiences
- **Real-Time Feedback**: Instantly track reps, spot mistakes, and calculate calories burned
- **Boost Motivation**: Keep users engaged with detailed exercise feedback
- **Custom Integration**: Adapt camera placement to fit your app's design
**Important — what to pass for `currentExercise` and `exercises`:** we **recommend exercise IDs** — they're stable, human-readable, and you already have them when listing exercises from the Content API. Set `exerciseFetchType: "exercise_id"` to use them. The Camera Component also accepts **model IDs** (the default, kept for backward compatibility — but they require an extra round-trip through the Content API to look up) and **exercise titles** (case-sensitive — convenient for prototyping, but title matching depends on locale-normalization and can mismatch similar exercises, so prefer IDs in production). See the **Fetching Exercises** section below.
**Before showing the camera UI**, wait for both `model_warmedup` and `models_loaded` events to fire. See the **Preloading & Events** section below.
**Quick Start**
_Swift (iOS)_
```swift
// Model IDs come from the Content API or admin dashboard.
// See "Camera: Model IDs" subsection.
@State var currentExercise = "3"
kinestex.createCameraView(
exercises: ["3"], // preload every model ID you may switch to
currentExercise: $currentExercise,
user: nil,
isLoading: $isLoading,
onMessageReceived: { message in
switch message {
case .reps(let value):
reps = value["value"] as? Int ?? 0
case .mistake(let value):
mistake = value["value"] as? String ?? "--"
default:
break
}
}
)
```
_Kotlin (Android)_
```kotlin
// Model IDs come from the Content API or admin dashboard.
// See "Camera: Model IDs" subsection.
val cameraView = KinesteXSDK.createCameraComponent(
context = this,
currentExercise = "3",
exercises = listOf("3"),
user = userDetails,
isLoading = viewModel.isLoading,
onMessageReceived = { message ->
when (message) {
is WebViewMessage.Reps ->
(message.data["value"] as? Int)?.let { reps = it }
is WebViewMessage.Mistake ->
(message.data["value"] as? String)?.let { mistake = it }
else -> {}
}
},
permissionHandler = this
)
```
_React Native_
```jsx
// Model IDs come from the Content API or admin dashboard.
// See "Camera: Model IDs" subsection.
// postData seeds the SDK with INITIAL values. To change them at runtime,
// call methods on kinestexSDKRef (e.g. changeExercise) — see "Camera: Controls".
const postData: IPostData = {
key: 'YOUR_API_KEY',
userId: 'YOUR_USER_ID',
company: 'YOUR_COMPANY_NAME',
currentExercise: '3',
exercises: ['3'], // preload every model ID you may switch to
style: { style: 'dark' },
};
{
if (type === 'successful_repeat') setReps(data.value);
if (type === 'mistake') setMistake(data.value);
}}
/>
```
_Flutter_
```dart
// Model IDs come from the Content API or admin dashboard.
// See "Camera: Model IDs" subsection.
KinesteXAIFramework.createCameraComponent(
isShowKinestex: showKinesteX,
exercises: ["3"],
currentExercise: "3",
isLoading: ValueNotifier(false),
onMessageReceived: (message) {
if (message is Reps) {
setState(() => reps = message.data['value']);
}
if (message is Mistake) {
setState(() => mistake = message.data['value']);
}
},
)
```
_HTML / JavaScript_
```html
// Model IDs come from the Content API or admin dashboard.
// See "Camera: Model IDs" subsection.
const postData = {
// ... your initial fields (key, userId, company, etc.)
currentExercise: "3",
exercises: ["3"],
};
const srcURL = "https://ai.kinestex.com/camera";
webView.src = srcURL;
webView.onload = () => sendMessage(postData);
window.addEventListener("message", (event) => {
if (event.origin !== "https://ai.kinestex.com") return;
const msg = JSON.parse(event.data);
if (msg.type === 'successful_repeat') console.log('Rep:', msg.value);
if (msg.type === 'mistake') console.log('Mistake:', msg.data?.value);
});
```
_React (TypeScript)_
```tsx
// Model IDs come from the Content API or admin dashboard.
// See "Camera: Model IDs" subsection.
import { useRef } from 'react';
import {
IntegrationOption,
KinesteXSDK,
type IPostData,
type KinesteXSDKCamera,
} from 'kinestex-sdk-react-ts';
const ref = useRef(null);
// postData seeds the SDK with INITIAL values. To change them at runtime,
// call methods on the ref (e.g. ref.current?.changeExercise) — see "Camera: Controls".
const postData: IPostData = {
key: 'YOUR_API_KEY',
userId: 'YOUR_USER_ID',
company: 'YOUR_COMPANY_NAME',
currentExercise: '3',
exercises: ['3'],
style: { style: 'dark' },
};
{
if (type === 'successful_repeat') setReps(data.value as number);
if (type === 'mistake') setMistake(data.value as string);
}}
/>
```
##### Model IDs
> **Recommendation:** prefer **exercise IDs** — they're easier to get (you already have them when listing exercises from the Content API) and don't require an extra round-trip just to look up a numeric model ID. Set `exerciseFetchType: "exercise_id"` and pass `exercise.id` directly. See the [Fetching Exercises](#camera-component-fetching-exercises) section.
Model IDs are still supported (it's the default when `exerciseFetchType` is omitted) and useful when you already have one handy — e.g. from a stored `WorkoutModel.sequence` or the admin dashboard. They are numeric values like `"3"` for Squats or `"394"` for Jumping Jack.
**Three ways to get a model ID:**
1. **Content API** — call `fetchExercises()` (Swift / Kotlin), `fetchContent(contentType: ContentType.exercise)` (Flutter), or `GET /api/v1/exercises` (REST). Each `ExerciseModel` has a `model_id` field. See the [Content API](/docs/content-api) section for full details. *(Note: this is the extra round-trip that exercise IDs let you skip.)*
2. **Admin dashboard** — open the exercise in [admin.kinestex.com](https://admin.kinestex.com); the model ID is shown at the top of the page header.
3. **Workout sequences** — when iterating `WorkoutModel.sequence`, each `ExerciseModel` entry exposes its own `model_id`.
**Fetch a Model ID**
_Swift (iOS)_
```swift
Task {
let result = await kinestex.fetchExercises(limit: 10)
if case .success(let response) = result,
let exercise = response.exercises.first {
// exercise.modelId is what the Camera Component expects
currentExercise = exercise.modelId
}
}
```
_Kotlin (Android)_
```kotlin
lifecycleScope.launch {
val result = withContext(Dispatchers.IO) {
KinesteXSDK.api.fetchAPIContentData(
contentType = ContentType.EXERCISE,
limit = 10
)
}
if (result is APIContentResult.Exercises) {
// exercise.modelId is what the Camera Component expects
currentExercise = result.exercises.firstOrNull()?.modelId ?: ""
}
}
```
_React Native_
```jsx
const res = await fetch(
'https://admin.kinestex.com/api/v1/exercises?limit=10',
{ headers: { 'x-api-key': API_KEY, 'x-company-name': COMPANY_NAME } },
);
const { exercises } = await res.json();
// exercise.model_id is what the Camera Component expects.
// Pass it as initial value, or switch later via ref.current?.changeExercise(...).
const modelId = exercises[0].model_id;
```
_Flutter_
```dart
final result = await KinesteXAIFramework.apiService.fetchContent(
contentType: ContentType.exercise,
limit: 10,
);
// exercise.modelId is what the Camera Component expects
if (result is ExercisesResult) {
final modelId = result.response.exercises.first.modelId;
}
```
_HTML / JavaScript_
```html
const res = await fetch(
'https://admin.kinestex.com/api/v1/exercises?limit=10',
{ headers: { 'x-api-key': API_KEY, 'x-company-name': COMPANY_NAME } },
);
const { exercises } = await res.json();
// exercise.model_id is what the Camera Component expects
const modelId = exercises[0].model_id;
```
_React (TypeScript)_
```tsx
const res = await fetch(
'https://admin.kinestex.com/api/v1/exercises?limit=10',
{ headers: { 'x-api-key': API_KEY, 'x-company-name': COMPANY_NAME } },
);
const { exercises } = await res.json() as { exercises: ExerciseModel[] };
// exercise.model_id is what the Camera Component expects
const modelId = exercises[0].model_id;
```
##### Fetching Exercises (by ID or Title)
Besides model IDs, the Camera Component can fetch exercises by **exercise ID** (recommended) or **exercise title**. Set the `exerciseFetchType` parameter to choose the form:
| `exerciseFetchType` | Meaning | What goes in `exercises` / `currentExercise` |
|---|---|---|
| `"exercise_id"` ✅ **recommended** | Exercise IDs from the Content API — easiest to use, no extra round-trip | e.g. `"squats_v2"` |
| `"model_id"` *(default)* | Numeric model IDs — kept for backward compatibility; requires a Content API lookup to obtain | `"3"`, `"394"` |
| `"exercise_title"` | Exercise titles (case-sensitive) — handy for prototyping, but title matching depends on locale-normalization and can mismatch similar exercises | `"Squats"`, `"Jumping Jack"` |
Omitting `exerciseFetchType` keeps the default model-ID behavior — no migration needed for existing integrations.
**Where to pass it:**
- **React Native (SDK v1.3.1+):** directly in `postData`, alongside `exercises` and `currentExercise`.
- **Swift, Kotlin, Flutter, HTML/JS, React (TypeScript):** inside `customParams` / `customParameters` along with `exercises` and `currentExercise`.
**Keep one form per session:** use the same form for both `exercises` and `currentExercise`, and for any later switches.
**Fetch by Exercise Title**
_Swift (iOS)_
```swift
// exerciseFetchType goes inside customParams
kinestex.createCameraView(
exercises: ["Squats", "Jumping Jack"],
currentExercise: $currentExercise, // e.g. "Squats"
customParams: [
"exerciseFetchType": "exercise_title" // "model_id" (default) | "exercise_id" | "exercise_title"
]
)
```
_Kotlin (Android)_
```kotlin
// exerciseFetchType goes inside customParams
KinesteXSDK.createCameraComponent(
context = this,
currentExercise = "Squats",
exercises = listOf("Squats", "Jumping Jack"),
customParams = mutableMapOf(
"exerciseFetchType" to "exercise_title" // "model_id" (default) | "exercise_id" | "exercise_title"
),
permissionHandler = this
)
```
_React Native_
```jsx
// React Native v1.3.1+: exerciseFetchType is direct in postData
const postData: IPostData = {
key: 'YOUR_API_KEY',
userId: 'YOUR_USER_ID',
company: 'YOUR_COMPANY_NAME',
currentExercise: 'Squats',
exercises: ['Squats', 'Jumping Jack'],
exerciseFetchType: 'exercise_title', // "model_id" (default) | "exercise_id" | "exercise_title"
};
```
_Flutter_
```dart
// exerciseFetchType goes inside customParams
KinesteXAIFramework.createCameraComponent(
isShowKinestex: showKinesteX,
exercises: ["Squats", "Jumping Jack"],
currentExercise: "Squats",
customParams: {
"exerciseFetchType": "exercise_title", // "model_id" (default) | "exercise_id" | "exercise_title"
},
isLoading: ValueNotifier(false),
onMessageReceived: handleWebViewMessage,
)
```
_HTML / JavaScript_
```html
// exerciseFetchType goes inside customParams
const postData = {
// ... your initial fields (key, userId, company, etc.)
currentExercise: "Squats",
exercises: ["Squats", "Jumping Jack"],
customParams: {
exerciseFetchType: "exercise_title", // "model_id" (default) | "exercise_id" | "exercise_title"
},
};
```
_React (TypeScript)_
```tsx
// exerciseFetchType goes inside customParameters
const postData: IPostData = {
key: 'YOUR_API_KEY',
userId: 'YOUR_USER_ID',
company: 'YOUR_COMPANY_NAME',
currentExercise: 'Squats',
exercises: ['Squats', 'Jumping Jack'],
customParameters: {
exerciseFetchType: 'exercise_title', // "model_id" (default) | "exercise_id" | "exercise_title"
},
};
```
##### Loading More Exercises at Runtime (React Native v1.3.1+)
**Availability:** React Native SDK `v1.3.1+` only. Other platforms must pass the full `exercises` list at initialization.
In React Native you can fetch and cache **additional** exercise models **after the session has started**, without re-mounting the camera. This is done by calling `sendAction` with the `"load_models"` action and an `extras` object containing the new identifiers.
**Three-step flow:**
1. Send the `load_models` action with the identifiers you want to add.
2. Wait for the `models_loaded` event — `data.modelIds` echoes the identifiers that resolved.
3. Switch the active exercise with `changeExercise(...)` (do **not** repeat `exerciseFetchType`).
If `exercises` is missing or empty, the SDK posts back `{ "type": "error_occurred", "message": "load_models: no exercises provided" }`. Per-identifier failures arrive as separate `error_occurred` messages; any identifiers that did resolve are still listed in `modelIds` and are switchable.
**Load More Models, Then Switch**
_React Native_
```jsx
// Step 1 — fetch additional models at runtime
sdkRef.current?.sendAction(
"workout_activity_action",
"load_models",
{
exercises: ["Jumping Jack", "Lunges"],
exerciseFetchType: "exercise_title", // match the form you used initially
}
);
// Step 2 — wait for models_loaded, then switch
const handleMessage = (type: string, data: { [key: string]: any }) => {
if (type === "models_loaded" && data.modelIds?.includes("Jumping Jack")) {
// Step 3 — switch the active exercise. Do NOT repeat exerciseFetchType here.
sdkRef.current?.changeExercise("Jumping Jack");
}
if (type === "error_occurred") {
console.warn("KinesteX error:", data.message);
}
};
```
##### Preloading & Events
Two events fire as the component initializes. Wait for **both** before revealing the camera UI to the user.
| Event | Meaning |
|---|---|
| `model_warmedup` | Pose-tracking (MediaPipe) model is ready |
| `models_loaded` | All exercise models in `exercises` have downloaded |
**Pattern:** mount the camera hidden (e.g. `opacity: 0`) with a loader on top. Reveal once both events have fired.
**Wait for Both Events**
_Swift (iOS)_
```swift
@State private var modelWarmedUp = false
@State private var modelsLoaded = false
var isReady: Bool { modelWarmedUp && modelsLoaded }
kinestex.createCameraView(
exercises: ["3"],
currentExercise: $currentExercise,
user: nil,
isLoading: $isLoading,
onMessageReceived: { message in
if case .custom_type(let value) = message,
let type = value["type"] as? String {
if type == "model_warmedup" { modelWarmedUp = true }
if type == "models_loaded" { modelsLoaded = true }
}
}
)
.opacity(isReady ? 1 : 0)
```
_Kotlin (Android)_
```kotlin
var modelWarmedUp = false
var modelsLoaded = false
val cameraView = KinesteXSDK.createCameraComponent(
context = this,
currentExercise = "3",
exercises = listOf("3"),
user = null,
isLoading = viewModel.isLoading,
onMessageReceived = { message ->
if (message is WebViewMessage.CustomType) {
when (message.data["type"] as? String) {
"model_warmedup" -> modelWarmedUp = true
"models_loaded" -> modelsLoaded = true
}
cameraView.alpha = if (modelWarmedUp && modelsLoaded) 1f else 0f
}
},
permissionHandler = this
)
```
_React Native_
```jsx
const [modelWarmedUp, setModelWarmedUp] = useState(false);
const [modelsLoaded, setModelsLoaded] = useState(false);
const isReady = modelWarmedUp && modelsLoaded;
{
if (type === 'model_warmedup') setModelWarmedUp(true);
if (type === 'models_loaded') setModelsLoaded(true);
}}
/>
```
_Flutter_
```dart
bool modelWarmedUp = false;
bool modelsLoaded = false;
KinesteXAIFramework.createCameraComponent(
isShowKinestex: showKinesteX,
exercises: ["3"],
currentExercise: "3",
isLoading: ValueNotifier(false),
onMessageReceived: (message) {
// Model-readiness events arrive as CustomType; the name is in data['type']
if (message is CustomType) {
if (message.data['type'] == 'model_warmedup') {
setState(() => modelWarmedUp = true);
}
if (message.data['type'] == 'models_loaded') {
setState(() => modelsLoaded = true);
}
}
},
)
```
_HTML / JavaScript_
```html
let modelWarmedUp = false, modelsLoaded = false;
const reveal = () => {
if (modelWarmedUp && modelsLoaded) iframe.style.opacity = '1';
};
iframe.style.opacity = '0';
window.addEventListener("message", (event) => {
if (event.origin !== "https://ai.kinestex.com") return;
const msg = JSON.parse(event.data);
if (msg.type === 'model_warmedup') { modelWarmedUp = true; reveal(); }
if (msg.type === 'models_loaded') { modelsLoaded = true; reveal(); }
});
```
_React (TypeScript)_
```tsx
const [modelWarmedUp, setModelWarmedUp] = useState(false);
const [modelsLoaded, setModelsLoaded] = useState(false);
const isReady = modelWarmedUp && modelsLoaded;
{
if (type === 'model_warmedup') setModelWarmedUp(true);
if (type === 'models_loaded') setModelsLoaded(true);
}}
/>
```
##### Controls
**Switching exercises in real time.** Set `currentExercise` to any model ID from the `exercises` array — the camera component swaps tracking immediately.
**Control commands.** Send any of these strings as `currentExercise` to control the session:
| Command | Effect |
|---|---|
| `"Pause Exercise"` | Pauses motion tracking; rep counter freezes |
| `"Pause Audio"` | Mutes voice feedback |
| `"Resume Audio"` | Re-enables voice feedback |
| `"Workout Overview"` | Triggers a summary snapshot for the current session |
| `"Stop Camera"` | ⚠️ **Destructive** — releases camera + models, fires `stop_camera`. Not recoverable without re-mounting the component (see warning below) |
To resume tracking after a pause, set `currentExercise` back to a real model ID from `exercises`.
> ⚠️ **`"Stop Camera"` is destructive — avoid it for normal flows.** It tears down the camera, MediaPipe, and all loaded exercise models, then fires the `stop_camera` event. **You cannot recover from it without unmounting and re-creating the entire camera component.** Only send it when the user is permanently leaving the camera screen. For temporary pauses, use `"Pause Exercise"` instead.
**Switch Exercise and Send Control Commands**
_Swift (iOS)_
```swift
// Switch exercise (Swift uses two-way binding via @State)
currentExercise = "394"
// Pause / resume tracking
currentExercise = "Pause Exercise"
currentExercise = "3"
```
_Kotlin (Android)_
```kotlin
// Switch exercise
KinesteXSDK.updateCurrentExercise("394")
// Pause / resume tracking
KinesteXSDK.updateCurrentExercise("Pause Exercise")
KinesteXSDK.updateCurrentExercise("3")
```
_React Native_
```jsx
// Switch exercise
kinestexSDKRef.current?.changeExercise("394");
// Pause / resume tracking
kinestexSDKRef.current?.changeExercise("Pause Exercise");
kinestexSDKRef.current?.changeExercise("3");
```
_Flutter_
```dart
// All controls go through your updateExercise ValueNotifier
updateExercise.value = "394";
updateExercise.value = "Pause Exercise";
updateExercise.value = "3";
```
_HTML / JavaScript_
```html
// Switch exercise
webView.contentWindow.postMessage(
{ currentExercise: "394" },
srcURL
);
// Pause / resume tracking
webView.contentWindow.postMessage({ currentExercise: "Pause Exercise" }, srcURL);
webView.contentWindow.postMessage({ currentExercise: "3" }, srcURL);
```
_React (TypeScript)_
```tsx
// Switch exercise
ref.current?.changeExercise("394");
// Pause / resume tracking
ref.current?.changeExercise("Pause Exercise");
ref.current?.changeExercise("3");
```
##### Customization
Pass any of these fields in `customParams` (Swift / Kotlin / Flutter) or directly in `postData` (HTML/JS, React Native, React TS) at initialization.
| Field | Type | Description |
|---|---|---|
| `restSpeeches` | `string[]` | Audio phrases to preload (from `ExerciseModel.rest_speech`) |
| `videoURL` | `string` | Use a video file instead of the live camera — the full tracking pipeline (reps, accuracy) runs on the video. Ideal for testing without physically performing exercises; see [Testing & Simulation](/docs/customization-parameters/testing-simulation) |
| `landmarkColor` | `string` | Pose overlay color in hex with `#` (default `#14FF00`) |
| `showSilhouette` | `boolean` | Show "get into frame" silhouette (default `true`) |
| `includeRealtimeAccuracy` | `boolean` | (Beta) Stream live position-confidence alongside reps |
| `includePoseData` | `string[]` | Any of `"angles"`, `"poseLandmarks"`, `"worldLandmarks"`. **Performance impact** — only enable for custom calculations |
##### Event Reference
All events the Camera Component emits to the host app:
| Event | Payload | When |
|---|---|---|
| `model_warmedup` | `{ message }` | Pose model is ready |
| `models_loaded` | `{ message }` | All exercise models in `exercises` finished downloading |
| `person_in_frame` | `{ message }` | User entered the silhouette frame |
| `successful_repeat` | `{ exercise, value, accuracy }` | A rep was counted (`value` = total reps so far) |
| `mistake` | `{ value }` | Form mistake detected |
| `correct_position_accuracy` | `{ accuracy }` | (Beta) Live position confidence — only when `includeRealtimeAccuracy: true` |
| `pose_landmarks` | `{ poseLandmarks }` | Per-frame screen-space landmarks — only when `includePoseData` includes `"poseLandmarks"` |
| `world_landmarks` | `{ worldLandmarks }` | Per-frame world-space landmarks — only when `includePoseData` includes `"worldLandmarks"` |
| `speech_fetch_complete` | `{ successCount, failureCount }` | All `restSpeeches` finished loading |
| `error_occurred` | `{ message }` or `{ data, error }` | Any error (model fetch fail, phrase fail, etc.) |
| `warning` | `{ data }` | Non-fatal config issue (e.g. no model IDs provided) |
| `stop_camera` | `{ message }` | Confirms the `"Stop Camera"` command finished |
##### Pose Data
When `includePoseData` contains `"poseLandmarks"` or `"worldLandmarks"`, the camera emits per-frame events with raw skeleton data. **Only enable this if you're doing custom calculations — there is a performance cost.**
**Two coordinate spaces:**
- `poseLandmarks` — values 0–1, normalized to the camera frame.
- `worldLandmarks` — meters, relative to the hips (best Z accuracy).
Each landmark has `{ x, y, z, visibility }` (all 0–1).
**Available landmarks** (same names in both spaces): `nose`, `leftEyeInner`, `leftEye`, `leftEyeOuter`, `rightEyeInner`, `rightEye`, `rightEyeOuter`, `leftEar`, `rightEar`, `mouthLeft`, `mouthRight`, `leftShoulder`, `rightShoulder`, `leftElbow`, `rightElbow`, `leftWrist`, `rightWrist`, `leftPinky`, `rightPinky`, `leftIndex`, `rightIndex`, `leftThumb`, `rightThumb`, `leftHip`, `rightHip`, `leftKnee`, `rightKnee`, `leftAnkle`, `rightAnkle`, `leftHeel`, `rightHeel`, `leftFootIndex`, `rightFootIndex`.
**Available angles** (when `"angles"` is included — both 2D and 3D versions are emitted): `leftKneeAngle`, `rightKneeAngle`, `leftHipAngle`, `rightHipAngle`, `leftShoulderAngle`, `rightShoulderAngle`, `leftElbowAngle`, `rightElbowAngle`, `leftWristAngle`, `rightWristAngle`, `leftAnkleAngle`, `rightAnkleAngle`, `leftArmpitAngle`, `rightArmpitAngle`.
##### Complete Example
Minimal working example with **Next** / **Previous** buttons that cycle between exercises and a live rep counter in the UI.
**Complete Implementation**
_Swift (iOS)_
```swift
import SwiftUI
import KinesteXAIKit
struct CameraScreen: View {
let kinestex = KinesteXAIKit(
apiKey: "YOUR_API_KEY",
companyName: "YOUR_COMPANY_NAME",
userId: "YOUR_USER_ID"
)
// 3 = Squats, 394 = Jumping Jack
let exerciseIds = ["3", "394"]
@State private var index = 0
@State private var currentExercise = "3"
@State private var reps = 0
@State private var isLoading = false
var body: some View {
VStack(spacing: 16) {
Text("Reps: \(reps)")
.font(.title)
.padding(.top)
kinestex.createCameraView(
exercises: exerciseIds,
currentExercise: $currentExercise,
user: nil,
isLoading: $isLoading,
onMessageReceived: { message in
if case .reps(let value) = message {
reps = value["value"] as? Int ?? 0
}
}
)
HStack(spacing: 24) {
Button("Previous") { switchTo(index - 1) }
Button("Next") { switchTo(index + 1) }
}
.padding(.bottom)
}
}
private func switchTo(_ newIndex: Int) {
index = (newIndex + exerciseIds.count) % exerciseIds.count
currentExercise = exerciseIds[index]
reps = 0
}
}
```
_Kotlin (Android)_
```kotlin
import android.Manifest
import android.os.Bundle
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity
import com.kinestex.kinestexsdkkotlin.GenericWebView
import com.kinestex.kinestexsdkkotlin.KinesteXSDK
import com.kinestex.kinestexsdkkotlin.PermissionHandler
import com.kinestex.kinestexsdkkotlin.WebViewMessage
import kotlinx.coroutines.flow.MutableStateFlow
class CameraActivity : AppCompatActivity(), PermissionHandler {
// 3 = Squats, 394 = Jumping Jack
private val exerciseIds = listOf("3", "394")
private var index = 0
private val isLoading = MutableStateFlow(false)
private lateinit var camera: GenericWebView
private lateinit var tvReps: TextView
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_camera)
tvReps = findViewById(R.id.tvReps)
camera = KinesteXSDK.createCameraComponent(
context = this,
currentExercise = exerciseIds[0],
exercises = exerciseIds,
user = null,
isLoading = isLoading,
onMessageReceived = { msg ->
if (msg is WebViewMessage.Reps) {
val v = msg.data["value"] as? Int ?: 0
runOnUiThread { tvReps.text = "Reps: $v" }
}
},
permissionHandler = this
) as GenericWebView
findViewById(R.id.cameraContainer).addView(camera)
findViewById