Shen.AI 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. In the default camera modes this also connects to a platform camera device, so the app must have camera permissions before this step. If you initialize the mobile SDKs with cameraMode = CustomFrames, the SDK will not start a camera and you can provide frames from your own native pipeline instead.

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 "@shenai/react-native-sdk"
 
const API_KEY = ""
const USER_ID = ""
 
const initResult = await initialize(API_KEY, USER_ID)


import { ShenaiSdkCapacitor } from "@shenai/capacitor-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)}%`)
})


#include "shenai_sdk_c.h"
 
shen_context_t* ctx = NULL;
shen_init_options_t opts = {
  .api_key_or_token = "YOUR_API_KEY_OR_TOKEN",
  .user_id = "user-123",
  .language = "en",
  .offline_mode = 0
};
 
shen_status_t status = shen_initialize(&opts, &ctx);


from shenai_sdk import ShenaiSDK
 
sdk = ShenaiSDK(
  api_key="YOUR_API_KEY_OR_TOKEN",
  user_id="user-123",
  language="en",
  offline=False
)

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 "@shenai/capacitor-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
  }
})


shen_status_t status = shen_initialize(&opts, &ctx);
if (status != SHEN_STATUS_OK || ctx == NULL) {
  /* handle error */
}


from shenai_sdk import ShenaiSDK, ShenaiError
 
try:
  sdk = ShenaiSDK(api_key="YOUR_API_KEY_OR_TOKEN")
except ShenaiError as exc:
  # handle error
  print(exc)

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

The SDK can be configured at the initialization stage to determine its behavior and visual appearance. The options can also be changed at runtime.

Calibration Integration

To use calibration modes (CALIBRATION or CALIBRATED_MEASUREMENT), be sure to set initializationMode. See the Calibration page for more details.

Initialization Settings

If you’d like to change these initialization settings from the Shen.AI Portal instead of app code, see Remote Configuration.


enum Event {
  startButtonClicked,
  stopButtonClicked,
  measurementFinished,
  userFlowFinished,
  screenChanged,
}
 
typedef EventCallback = void Function(Event event);
 
class InitializationSettings {
InitializationMode? initializationMode;
PrecisionMode? precisionMode;
OperatingMode? operatingMode;
MeasurementPreset? measurementPreset;
CameraMode? cameraMode;
OnboardingMode? onboardingMode;
bool? showUserInterface;
bool? showFacePositioningOverlay;
bool? showVisualWarnings;
bool? enableCameraSwap;
bool? showFaceMask;
bool? showBloodFlow;
bool? hideShenaiLogo;
bool? includeTimestampInPdf;
bool? enableStartAfterSuccess;
bool? enableSummaryScreen;
bool? showResultsFinishButton;
bool? enableHealthRisks;
bool? showHealthIndicesFinishButton;
bool? saveHealthRisksFactors;
bool? showOutOfRangeResultIndicators;
bool? showSignalQualityIndicator;
bool? showSignalTile;
bool? showStartStopButton;
bool? showInfoButton;
bool? showDisclaimer;
UiVersion? uiVersion;
bool? showTrialMetricLabels;
bool? applyPrecisionModeToBloodPressure;
List<MeasurementEnvironmentCondition>? blockingMeasurementConditions;
List<MeasurementEnvironmentCondition>? warningMeasurementConditions;
List<Screen>? uiFlowScreens;
int? frameWidth;
int? frameHeight;
int? rotation;
RisksFactors? risksFactors;
}


export type EventName =
  | "START_BUTTON_CLICKED"
  | "STOP_BUTTON_CLICKED"
  | "MEASUREMENT_FINISHED"
  | "USER_FLOW_FINISHED"
  | "SCREEN_CHANGED";
 
interface InitializationSettings {
  initializationMode?: InitializationMode;
  precisionMode?: PrecisionMode;
  operatingMode?: OperatingMode;
  measurementPreset?: MeasurementPreset;
  cameraMode?: CameraMode;
  onboardingMode?: OnboardingMode;
  showUserInterface?: boolean;
  showFacePositioningOverlay?: boolean;
  showVisualWarnings?: boolean;
  enableCameraSwap?: boolean;
  showFaceMask?: boolean;
  showBloodFlow?: boolean;
  hideShenaiLogo?: boolean;
  includeTimestampInPdf?: boolean;
  enableStartAfterSuccess?: boolean;
  enableSummaryScreen?: boolean;
  showResultsFinishButton?: boolean;
  enableHealthRisks?: boolean;
  showHealthIndicesFinishButton?: boolean;
  saveHealthRisksFactors?: boolean;
  showOutOfRangeResultIndicators?: boolean;
  showTrialMetricLabels?: boolean;
  showSignalQualityIndicator?: boolean;
  showSignalTile?: boolean;
  showStartStopButton?: boolean;
  showInfoButton?: boolean;
  showDisclaimer?: boolean;
  applyPrecisionModeToBloodPressure?: boolean;
  blockingMeasurementConditions?: MeasurementEnvironmentCondition[];
  warningMeasurementConditions?: MeasurementEnvironmentCondition[];
  enableMeasurementsDashboard?: boolean;
  uiVersion?: UiVersion;
  uiFlowScreens?: Screen[];
  frameWidth?: number;
  frameHeight?: number;
  rotation?: number;
  risksFactors?: RisksFactors;
}


export type EventName =
  | "START_BUTTON_CLICKED"
  | "STOP_BUTTON_CLICKED"
  | "MEASUREMENT_FINISHED"
  | "USER_FLOW_FINISHED"
  | "SCREEN_CHANGED"
 
interface InitializationSettings {
  initializationMode?: InitializationMode
  precisionMode?: PrecisionMode
  operatingMode?: OperatingMode
  measurementPreset?: MeasurementPreset
  cameraMode?: CameraMode
  onboardingMode?: OnboardingMode
  showUserInterface?: boolean
  showFacePositioningOverlay?: boolean
  showVisualWarnings?: boolean
  enableCameraSwap?: boolean
  showFaceMask?: boolean
  showBloodFlow?: boolean
  hideShenaiLogo?: boolean
  includeTimestampInPdf?: boolean
  enableStartAfterSuccess?: boolean
  enableSummaryScreen?: boolean
  showResultsFinishButton?: boolean
  enableHealthRisks?: boolean
  showHealthIndicesFinishButton?: boolean
  saveHealthRisksFactors?: boolean
  showOutOfRangeResultIndicators?: boolean
  showTrialMetricLabels?: boolean
  showSignalQualityIndicator?: boolean
  showSignalTile?: boolean
  showStartStopButton?: boolean
  showInfoButton?: boolean
  showDisclaimer?: boolean
  applyPrecisionModeToBloodPressure?: boolean
  blockingMeasurementConditions?: MeasurementEnvironmentCondition[]
  warningMeasurementConditions?: MeasurementEnvironmentCondition[]
  enableMeasurementsDashboard?: boolean
  uiVersion?: UiVersion
  uiFlowScreens?: Screen[]
  frameWidth?: number
  frameHeight?: number
  rotation?: number
  risksFactors?: RisksFactors
}


using Shenai.Maui;
 
public enum EventName
{
    START_BUTTON_CLICKED = 0,
    STOP_BUTTON_CLICKED,
    MEASUREMENT_FINISHED,
    USER_FLOW_FINISHED,
    SCREEN_CHANGED,
}
 
public sealed class InitializationSettings
{
    public PrecisionMode? PrecisionMode { get; set; }
    public OperatingMode? OperatingMode { get; set; }
    public MeasurementPreset? MeasurementPreset { get; set; }
    public CameraMode? CameraMode { get; set; }
    public OnboardingMode? OnboardingMode { get; set; }
    public bool? ShowUserInterface { get; set; }
    public bool? ShowFacePositioningOverlay { get; set; }
    public bool? ShowVisualWarnings { get; set; }
    public bool? EnableCameraSwap { get; set; }
    public bool? ShowFaceMask { get; set; }
    public bool? ShowBloodFlow { get; set; }
    public bool? HideShenaiLogo { get; set; }
    public bool? IncludeTimestampInPdf { get; set; }
    public bool? EnableStartAfterSuccess { get; set; }
    public bool? EnableSummaryScreen { get; set; }
    public bool? ShowResultsFinishButton { get; set; }
    public bool? EnableHealthRisks { get; set; }
    public bool? ShowHealthIndicesFinishButton { get; set; }
    public bool? ShowOutOfRangeResultIndicators { get; set; }
    public bool? ShowSignalQualityIndicator { get; set; }
    public bool? ShowSignalTile { get; set; }
    public bool? EnableMeasurementsDashboard { get; set; }
    public UiVersion? UiVersion { get; set; }
    public bool? ShowStartStopButton { get; set; }
    public bool? ShowInfoButton { get; set; }
    public bool? ShowTrialMetricLabels { get; set; }
    public bool? ApplyPrecisionModeToBloodPressure { get; set; }
    public IReadOnlyList<MeasurementEnvironmentCondition>? BlockingMeasurementConditions { get; set; }
    public IReadOnlyList<MeasurementEnvironmentCondition>? WarningMeasurementConditions { get; set; }
    public IReadOnlyList<Screen>? UiFlowScreens { get; set; }
    public int? FrameWidth { get; set; }
    public int? FrameHeight { get; set; }
    public int? Rotation { get; set; }
    public RisksFactors? RisksFactors { get; set; }
}


public enum Event {
  START_BUTTON_CLICKED,
  STOP_BUTTON_CLICKED,
  MEASUREMENT_FINISHED,
  USER_FLOW_FINISHED,
  SCREEN_CHANGED
}
 
public interface EventCallback {
  void onEvent(Event event);
}
 
public class InitializationSettings {
  public InitializationMode initializationMode;
  public PrecisionMode precisionMode;
  public OperatingMode operatingMode;
  public MeasurementPreset measurementPreset;
  public CameraMode cameraMode;
  public OnboardingMode onboardingMode;
  public boolean showUserInterface;
  public boolean showFacePositioningOverlay;
  public boolean showVisualWarnings;
  public boolean enableCameraSwap;
  public boolean showFaceMask;
  public boolean showBloodFlow;
  public boolean hideShenaiLogo;
  public boolean includeTimestampInPdf;
  public boolean enableStartAfterSuccess;
  public boolean enableSummaryScreen;
  public boolean showResultsFinishButton;
  public boolean enableHealthRisks;
  public boolean showHealthIndicesFinishButton;
  public boolean saveHealthRisksFactors;
  public boolean showOutOfRangeResultIndicators;
  public boolean showTrialMetricLabels;
  public boolean showSignalQualityIndicator;
  public boolean showSignalTile;
  public boolean showStartStopButton;
  public boolean showInfoButton;
  public boolean showDisclaimer;
  public boolean applyPrecisionModeToBloodPressure;
  public List<MeasurementEnvironmentCondition> blockingMeasurementConditions;
  public List<MeasurementEnvironmentCondition> warningMeasurementConditions;
  public boolean enableMeasurementsDashboard;
  public UiVersion uiVersion;
  public List<Screen> uiFlowScreens;
  public int frameWidth;
  public int frameHeight;
  public int rotation;
  public EventCallback eventCallback;
  public RisksFactors risksFactors;
}


enum Event {
  case startButtonClicked
  case stopButtonClicked
  case measurementFinished
  case userFlowFinished
  case screenChanged
}
 
class InitializationSettings {
  var initializationMode: InitializationMode
  var precisionMode: PrecisionMode
  var operatingMode: OperatingMode
  var measurementPreset: MeasurementPreset
  var cameraMode: CameraMode
  var onboardingMode: OnboardingMode
  var showUserInterface: Bool
  var showFacePositioningOverlay: Bool
  var showVisualWarnings: Bool
  var enableCameraSwap: Bool
  var showFaceMask: Bool
  var showBloodFlow: Bool
  var hideShenaiLogo: Bool
  var includeTimestampInPdf: Bool
  var enableStartAfterSuccess: Bool
  var enableSummaryScreen: Bool
  var showResultsFinishButton: Bool
  var enableHealthRisks: Bool
  var showHealthIndicesFinishButton: Bool
  var saveHealthRisksFactors: Bool
  var showOutOfRangeResultIndicators: Bool
  var showTrialMetricLabels: Bool
  var showSignalQualityIndicator: Bool
  var showSignalTile: Bool
  var showStartStopButton: Bool
  var showInfoButton: Bool
  var showDisclaimer: Bool
  var applyPrecisionModeToBloodPressure: Bool
  var blockingMeasurementConditions: [NSNumber]?
  var warningMeasurementConditions: [NSNumber]?
  var enableMeasurementsDashboard: Bool
  var uiVersion: UiVersion
  var uiFlowScreens: [NSNumber]?
  var frameWidth: Int
  var frameHeight: Int
  var rotation: Int
  var eventCallback: ((Event) -> Void)?
  var risksFactors: RisksFactors?
}


export type EventName =
  | "START_BUTTON_CLICKED"
  | "STOP_BUTTON_CLICKED"
  | "MEASUREMENT_FINISHED"
  | "USER_FLOW_FINISHED"
  | "SCREEN_CHANGED"
 
interface InitializationSettings {
  initializationMode?: InitializationMode
  precisionMode?: PrecisionMode
  operatingMode?: OperatingMode
  measurementPreset?: MeasurementPreset
  cameraMode?: CameraMode
  cameraAspectRatio?: number
  onboardingMode?: OnboardingMode
  showUserInterface?: boolean
  showFacePositioningOverlay?: boolean
  showVisualWarnings?: boolean
  enableCameraSwap?: boolean
  showFaceMask?: boolean
  showBloodFlow?: boolean
  hideShenaiLogo?: boolean
  includeTimestampInPdf?: boolean
  pdfLogoId?: string
  enableStartAfterSuccess?: boolean
  enableSummaryScreen?: boolean
  showResultsFinishButton?: boolean
  enableHealthRisks?: boolean
  showHealthIndicesFinishButton?: boolean
  saveHealthRisksFactors?: boolean
  showOutOfRangeResultIndicators?: boolean
  showSignalQualityIndicator?: boolean
  showSignalTile?: boolean
  showStartStopButton?: boolean
  showInfoButton?: boolean
  showDisclaimer?: boolean
  applyPrecisionModeToBloodPressure?: boolean
  blockingMeasurementConditions?: MeasurementEnvironmentCondition[]
  warningMeasurementConditions?: MeasurementEnvironmentCondition[]
  enableMeasurementsDashboard?: boolean
  uiVersion?: UiVersion
  showTrialMetricLabels?: boolean
  enableFullFrameProcessing?: boolean
  language?: string
  customColorTheme?: CustomColorTheme
  customMeasurementConfig?: CustomMeasurementConfig
  uiFlowScreens?: Screen[]
  risksFactors?: RisksFactors
  eventCallback?: (event: EventName) => void
  onCameraError?: () => void
}


shen_init_options_t opts = {
  .api_key_or_token = "YOUR_API_KEY_OR_TOKEN",
  .user_id = NULL,
  .language = "en",
  .offline_mode = 0
};
 
shen_initialize(&opts, &ctx);
shen_set_measurement_preset(ctx, SHEN_MEAS_PRESET_ONE_MINUTE_ALL_METRICS);
 
/* Optional: apply a full JSON config string. */
const char* config_json = load_config_json();
shen_apply_sdk_config(config_json);


from shenai_sdk import ShenaiSDK, MeasurementPreset
 
sdk = ShenaiSDK(api_key="YOUR_API_KEY_OR_TOKEN", language="en")
sdk.measurement_preset = MeasurementPreset.ONE_MINUTE_ALL_METRICS
 
config_json = load_config_json()
sdk.apply_sdk_config(config_json)

uiFlowScreens defines an explicit sequence of UI screens. If the list is non-empty it takes priority over per-screen boolean flags such as showDisclaimer, enableSummaryScreen, and enableHealthRisks. Allowed screens: DISCLAIMER, ONBOARDING, MEASUREMENT, RESULTS, HEALTH_RISKS_EDIT, HEALTH_RISKS.

See Configuration for detailed information on each option.

SDK events

SDK events notify your app about important changes in the SDK flow. They are most useful when you build a custom or partially custom UI and need to keep your app state 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 custom UI updates. Keep event handlers lightweight and read detailed measurement data through the regular result APIs.

Providing the user interface

Unless you’re implementing a custom solution that doesn’t require a 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 '@shenai/react-native-sdk';
 
const App = () => {
  ...
  return (
    <View>
      <ShenaiSdkView />
    </View>
  );
};


import { ShenaiSdkCapacitor } from "@shenai/capacitor-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"/>

The Linux headless C SDK has no embedded UI. Build your own UX and submit frames via shen_submit_frame().

The Linux headless Python SDK has no embedded UI. Build your own UX and submit frames via submit_frame().

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 "@shenai/react-native-sdk"
 
deinitialize()


import { ShenaiSdkCapacitor } from "@shenai/capacitor-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.


shen_deinitialize(ctx);
shen_destroy_runtime();


sdk.close()
sdk.destroy_runtime()