Shen.AI (CE) SDK Documentation

Initialization

Before starting the video measurement, you’ll need to initialize the SDK.

Under the hood that step verifies the license and prepares the selected input pipeline. This also connects to a platform camera device, so the app must have camera permissions before this step.

You’ll need to provide an API key - see Authorization for more information.

Security tip: In production applications, short-lived tokens should be issued from a backend instead of embedding permanent API keys in client-side code. This reduces exposure of long-lived credentials while preserving standard SDK initialization flows for web and mobile applications.

lib/main.dart


import 'package:shenai_sdk/shenai_sdk.dart';
 
var API_KEY = ""
var USER_ID = ""
 
final _initResult = await ShenaiSdk.initialize(API_KEY, USER_ID);

App.tsx


import { initialize, InitializationResult } from "react-native-shenai-sdk"
 
const API_KEY = ""
const USER_ID = ""
 
const initResult = await initialize(API_KEY, USER_ID)


import { ShenaiSdkCapacitor } from "capacitor-shenai-sdk"
 
const API_KEY = ""
const USER_ID = ""
 
const { value: initResult } = await ShenaiSdkCapacitor.initialize({ apiKey: API_KEY, userId: USER_ID })


using Shenai.Maui;
 
const string API_KEY = "";
const string USER_ID = "";
 
var initResult = await ShenaiSdk.InitializeAsync(API_KEY, USER_ID);

AppDelegate.swift


import ShenaiSDK
 
let API_KEY = "";
 
let init_result = ShenaiSDK.initialize(API_KEY, userID: nil, settings: nil)

MainActivity.kt


import ai.mxlabs.shenai_sdk.ShenAIAndroidSDK
 
val API_KEY = ""
val USER_ID = ""
 
val initResult = shenaiSDKHandler.initialize(this, API_KEY, USER_ID)

index.ts


import CreateShenaiSDK from "shenai-sdk"
 
const shenaiSDK = await CreateShenaiSDK()
 
const API_KEY = "" // Use your API key here
const USER_ID = ""
 
shenaiSDK.initialize(
  API_KEY,
  USER_ID,
  {
    /* settings */
  },
  initResult => {
    /* handle result */
  }
)

You can pass an optional configuration object to CreateShenaiSDK(...) to control the loader behaviour before the engine boots:

enableErrorReporting?: boolean – opt‑out of the built‑in Sentry reporting by setting this to false.
enablePreloadDisplay?: boolean – set to false to skip the animated preload canvas entirely.
preloadDisplayCanvasId?: string – optionally render the preload UI into a specific <canvas> element.
hidePreloadDisplayLogo?: boolean – hides the Shen.ai logo on the preload UI by default. Set to false to display it.
onWasmLoadingProgress?: (progress: number) => void – receive progress updates (0–1) while WASM downloads.

index.ts


const shenaiSDK = await CreateShenaiSDK({
  enablePreloadDisplay: true,
  preloadDisplayCanvasId: "mxcanvas",
  hidePreloadDisplayLogo: false,
  onWasmLoadingProgress: value => console.log(`Loading ${(value * 100).toFixed(0)}%`)
})

Error handling

You should check if the initialization was successful before proceeding further.

Possible errors at this stage include:

INVALID_API_KEY - the provided API key is malformed or inactive
CONNECTION_ERROR - there is a problem with network connection to the licensing server
INTERNAL_ERROR - other errors such as missing camera permissions


enum InitializationResult {
  success,
  failInvalidApiKey,
  failConnectionError,
  failInternalError
}
 
if (_initResult != InitializationResult.success) {
  // handle error
}


enum InitializationResult {
  OK,
  INVALID_API_KEY,
  CONNECTION_ERROR,
  INTERNAL_ERROR
}
 
if (initResult != InitializationResult.OK) {
  // handle error
}


import { ShenaiSdkCapacitor, InitializationResult } from "capacitor-shenai-sdk"
 
const { value: initResult } = await ShenaiSdkCapacitor.initialize({ apiKey: API_KEY })
 
if (initResult != InitializationResult.OK) {
  // handle error
}


using Shenai.Maui;
 
enum InitializationResult
{
    OK = 0,
    INVALID_API_KEY,
    CONNECTION_ERROR,
    INTERNAL_ERROR,
}
 
var initResult = await ShenaiSdk.InitializeAsync(API_KEY, USER_ID);
if (initResult != InitializationResult.OK)
{
    // handle error
}


enum InitializationResult {
  case success
  case failureInvalidApiKey
  case failureConnectionError
  case failureInternalError
};
 
if (init_result != .success) {
// handle error
}


enum InitializationResult {
  OK,
  INVALID_API_KEY,
  CONNECTION_ERROR,
  INVALID
}
 
if (initResult != InitializationResult.OK) {
  // handle error
}


import { InitializationResult } from "shenai-sdk"
 
// Initialize the SDK and handle result in callback
shenaiSDK.initialize(API_KEY, USER_ID, {}, initResult => {
  switch (initResult) {
    case InitializationResult.OK:
      // initialization succeeded
      break
    case InitializationResult.INVALID_API_KEY:
      // handle invalid API key
      break
    case InitializationResult.CONNECTION_ERROR:
      // handle connection error
      break
    case InitializationResult.INTERNAL_ERROR:
      // handle internal error
      break
  }
})

If the SDK has been successfully initialized, repeated calls to initialize will immediately return success - to start a new session first deinitialize the SDK.

Custom initialization options

Shen.AI (CE) uses the standard initialization flow and supports SDK events.

Supported Shen.AI (CE) initialization settings

Shen.AI (CE) accepts the standard API key/user ID inputs and keeps the standard event-callback integration. During the preview phase, use the same API key as for the standard SDK. It also accepts language where the platform exposes it during initialization, limited to en, de, es, fr, and pl. Unsupported language values are normalized to en.

The only supported initialization flow is:

MEASUREMENT: standard measurement without calibration data.

Calibration-related enum values remain present for cross-product wrapper compatibility, but Shen.AI (CE) normalizes them to MEASUREMENT.

SDK events

SDK events notify your app about important changes in the SDK flow. They are most useful when your app state, navigation, or analytics need to stay aligned with the embedded SDK flow.

Available events:

START_BUTTON_CLICKED: the user clicked START in the SDK UI.
STOP_BUTTON_CLICKED: the user clicked STOP in the SDK UI.
MEASUREMENT_FINISHED: a measurement completed and results are ready to read.
USER_FLOW_FINISHED: the user completed the current SDK flow.
SCREEN_CHANGED: the SDK changed the currently displayed screen.

Platform access differs by SDK:

Web, Android, and iOS expose eventCallback in initialization settings.
Flutter uses ShenaiSdk.setEventCallback(...).
React Native emits the native ShenAIEvent event.
Capacitor emits the ShenAIEvent plugin event.
MAUI exposes ShenaiSdk.Events.

Use these events for app state, navigation, analytics, and host-app updates. Keep event handlers lightweight and read detailed measurement data through the regular result APIs.

Providing the user interface

You’ll need to embed the SDK’s UI in your app. The SDK uses OpenGL/WebGL for rendering, embedded in a platform-specific native view component.

You can use the ShenaiView widget to embed the SDK’s UI in your Flutter app.

lib/main.dart


import 'package:shenai_sdk/shenai_view.dart';
...
 
@override
Widget build(BuildContext context) {
  return Center(
      child: ShenaiView(),
    );
}

You can use the ShenaiSdkView component to embed the SDK’s UI in your React Native app.

App.tsx


import {ShenaiSdkView} from 'react-native-shenai-sdk';
 
const App = () => {
  ...
  return (
    <View>
      <ShenaiSdkView />
    </View>
  );
};


import { ShenaiSdkCapacitor } from "capacitor-shenai-sdk"
 
const initShenai = async () => {
  await ShenaiSdkCapacitor.initialize({ apiKey: API_KEY })
}

MauiProgram.cs


using Shenai.Maui;
 
var builder = MauiApp.CreateBuilder();
builder.UseMauiApp<App>()
       .UseShenai();

MainPage.xaml


<ContentPage xmlns:shenai="clr-namespace:Shenai.Maui">
    <shenai:ShenaiSdkView HeightRequest="400" />
</ContentPage>

You can use the ShenaiView class to embed the SDK’s UI in your iOS app.

Swift example:

AppDelegate.swift


import UIKit
import ShenaiSDK
 
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
 
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        window = UIWindow(frame: UIScreen.main.bounds)
        let mainVC = ShenaiView()
        window?.rootViewController = mainVC
        window?.makeKeyAndVisible()
 
        return true
    }
}

Objective-C example:

AppDelegate.m


#import "AppDelegate.h"
#import <ShenaiSDK/ShenaiView.h>
 
@interface AppDelegate ()
 
@end
 
@implementation AppDelegate
 
- (BOOL)application:(UIApplication _)application didFinishLaunchingWithOptions:(NSDictionary _)launchOptions {
  self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
  ShenaiView *vc = [[ShenaiView alloc] init];
  self.window.rootViewController = vc;
  [self.window makeKeyAndVisible];
 
  return YES;
}
 
@end

You can use the ShenAIView class to embed the SDK’s UI in your Android app. To construct the view, you’ll need to provide the current Activity as a parameter.

src/main/java/MainActivity.java


import ai.mxlabs.shenai_sdk.ShenAIView;
 
 
public class MainActivity extends ComponentActivity {
  ...
  ShenAIView shenaiView = new ShenAIView(this);
  setContentView(shenaiView);
  ...
}

To display the SDK output, you’ll need to provide a canvas element.

If you create a canvas with id="mxcanvas", the SDK will automatically connect to it on initialization and use it for rendering.


<canvas id="mxcanvas" />

Alternatively, you can connect the canvas manually using the attachToCanvas method. This can be done either before or after the initialization, or even during runtime. However, keep in mind that switching canvases at runtime might cause UI to be not responding for some time.


<canvas id="not-mxcanvas" />
...
shenaiSDK.attachToCanvas("#not-mxcanvas");

In such a case, it’s a good idea to also specify the same custom canvas for the preload display (which gives the instructions before the SDK is loaded and initialized) by passing preloadDisplayCanvasId when creating the SDK:


const shenaiSDK = await CreateShenaiSDK({
  preloadDisplayCanvasId: "not-mxcanvas"
})

It is also possible to attach to multiple canvases. For this, you can use the optional second parameter exclusive of the attachToCanvas method. If exclusive is false it allows to attach to another canvas without detaching from the current one.


<canvas id="canvas1" />
<canvas id="canvas2" />
...
shenaiSDK.attachToCanvas("#canvas1", true);
shenaiSDK.attachToCanvas("#canvas2", false);

You should use CSS to provide size boundaries for the canvas. The SDK will automatically expand the canvas to fit the available space. Don’t set directly the width and height attributes of the canvas as those will be set by the SDK itself to properly size the rendering buffer.

You should include the following <meta> viewport element in HTML of your website to ensure that canvas has the proper resolution on mobile devices:


<meta name="viewport" content="width=device-width,initial-scale=1.0">

We encourage to disable zooming as well by using the following <meta> viewport element instead:


<meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=0"/>

Deinitialization

After finishing using the SDK you should deinitialize it - that will free up any allocated resources and disconnect from the camera.


ShenaiSdk.deinitialize();


import { deinitialize } from "react-native-shenai-sdk"
 
deinitialize()


import { ShenaiSdkCapacitor } from "capacitor-shenai-sdk"
 
await ShenaiSdkCapacitor.deinitialize()


using Shenai.Maui;
 
await ShenaiSdk.DeinitializeAsync();


ShenaiSDK.deinitialize()


shenaiSDKHandler.deinitialize()


shenaiSDK.deinitialize()

Deinitializing the Web SDK will keep the runtime alive, allowing you to initialize the SDK again afterwards.

To release all memory held by the SDK in the current browser context, you should call the destroyRuntime method - note that you won’t be able to initialize the SDK again after that. You don’t need to call deinitialize before destroyRuntime.


shenaiSDK.destroyRuntime()

Note that in order for all resources to be released, you need to release all references you may have kept to the SDK runtime after creating it.

Web runtime cleanup guidance:

deinitialize() should be used when leaving the scan screen if another SDK session may be created later in the same page or SPA lifecycle.
destroyRuntime() should be used only when the SDK runtime is no longer needed in the current browser context and will not be initialized again.
If the application navigates away from the scan route or unmounts the scan view without cleanup, symptoms may include an apparently active camera, stale allocations, or failure during the next initialization.
When repeated Web initialization or cleanup issues are investigated, route-unmount logic should be verified before header or licensing issues are assumed.