SDK API Reference

initNorrix

Initialize the Norrix SDK and optionally start update checking.

Signature

function initNorrix(config: UpdateConfig): NorrixUpdates;

Parameters

Returns

NorrixUpdates: SDK instance for manual control

Example

import { initNorrix } from '@norrix/client-sdk';
 
const norrix = initNorrix({
  updateUrl: 'https://norrix.net',
  checkForUpdatesOnLaunch: true,
  installUpdatesAutomatically: true,
});

checkUpdates

Convenience function to check for updates using the global instance.

Signature

function checkUpdates(): Promise<UpdateInfo>;

Returns

Promise<UpdateInfo>: Update information

Throws

Error if initNorrix hasn’t been called.

NorrixUpdates Class

Main SDK class returned by initNorrix.

checkForUpdates()

Check for available updates from the server.

async checkForUpdates(): Promise<UpdateInfo>

Returns: Promise<UpdateInfo>

Example:

const update = await norrix.checkForUpdates();
if (update.updateAvailable) {
  console.log('Update available:', update.version);
}

sync()

Check, download, and install in one call, honouring installUpdatesAutomatically.

sync(): Promise<UpdateInfo>

Returns: Promise<UpdateInfo>

Only one sync runs at a time. A call made while another sync is in flight reports SyncStatus.IN_PROGRESS and resolves with the in-flight result, so a screen that syncs on every resume still performs one download.

downloadUpdate(update)

Download an update package.

async downloadUpdate(update: UpdateInfo): Promise<boolean>

Parameters:

Returns: Promise<boolean>. true if download succeeded

Example:

const update = await norrix.checkForUpdates();
if (update.updateAvailable && update.url) {
  const success = await norrix.downloadUpdate(update);
}

applyUpdate(options?)

Apply a downloaded update.

applyUpdate(
  closeAppNowOrOptions?: boolean | ApplyUpdateOptions
): Promise<ApplyUpdateResult>

Parameters:

Behavior:

• With no apply mode configured and no prompt, the update is left to activate on the next cold launch
• soft-reboot recreates the JavaScript runtime in place, which requires the NativeScript 9.1.0 runtime or newer
• process-restart closes the app, optionally via the restart page

Returns: Promise<ApplyUpdateResult>: { applied, mode, fallbackUsed?, message? }

getRunningUpdate()

What this process is executing, as decided by the native loader at launch.

getRunningUpdate(): RunningUpdateInfo

Returns: RunningUpdateInfo

interface RunningUpdateInfo {
  source: 'embedded' | 'update';
  updateId?: string;
  version: string;
  buildNumber: string;
  /** Whether this process reached first display. */
  confirmed: boolean;
}

Use this for version labels. The Norrix_OTA_Version / Norrix_OTA_BuildNumber keys in ApplicationSettings describe the installed update, not the running one, and are kept only for backward compatibility.

getInstalledUpdate()

The newest launchable installed update, which is what the next launch will run.

getInstalledUpdate(): InstalledUpdate | null

Returns: InstalledUpdate, or null when the next launch boots the store bundle

getQuarantinedUpdateIds()

Ids of updates that failed to launch on this binary and will not be installed again.

getQuarantinedUpdateIds(): string[]

The list is cleared when the app is updated from the store. retryFailedUpdates: true makes the SDK ignore it when checking.

isUpdateQuarantined(updateId)

isUpdateQuarantined(updateId: string): boolean

resetAllOTAs()

Clear all OTA updates and return to the store binary.

resetAllOTAs(): void

Behavior:

1. Resets the OTA state file, including the quarantine list
2. Removes every installed OTA package from disk
3. Clears the mirrored version keys in ApplicationSettings
4. Shows a restart prompt to the user

getCurrentFingerprintHash()

Get the current native binary fingerprint hash.

getCurrentFingerprintHash(): string | undefined

Returns: The fingerprint hash, or undefined if not found

Notes:

• Returns cached value if previously read
• Reads from assets/norrix.fingerprint.json
• Caches result to ensure consistency across OTA updates

getCurrentConfiguration()

Get the deployment configuration embedded in the native binary.

getCurrentConfiguration(): string | undefined

Returns: The configuration string (e.g., 'prod', 'stg'), or undefined if not found

Notes:

• Reads from native resources (Info.plist on iOS, BuildConfig on Android)
• Used to ensure OTA updates match the binary’s deployment target
• Prevents staging updates from being applied to production apps (and vice versa)

closeAppNow()

Utility to immediately close the app.

closeAppNow(): void

Platform behavior:

• iOS: Calls exit(0)
• Android: Calls java.lang.System.exit(0)

Warning: Only use after user confirmation.

UpdateConfig Interface

Configuration options for initNorrix.

interface UpdateConfig {
  updateUrl: string;
  checkForUpdatesOnLaunch?: boolean;
  installUpdatesAutomatically?: boolean;
  allowStoreUpdateOverride?: boolean;
  promptToRestartAfterInstall?: boolean;
  retryFailedUpdates?: boolean;
  applyUpdateMode?: ApplyUpdateMode;
  fallbackToProcessRestart?: boolean;
  statusCallback?: (status: SyncStatus, data?: UpdateInfo) => void;
  downloadProgressCallback?: (progress: number) => void;
}

UpdateInfo Interface

Information about an available update.

interface UpdateInfo {
  updateAvailable: boolean;
  updateId?: string;
  platform?: string;
  version?: string;
  buildNumber?: string;
  releaseNotes?: string;
  url?: string;
  expiresAt?: string;
  timestamp?: Date;
  message?: any;
  requiresStoreUpdate?: boolean;
  compatibilityReason?: string;
}

RunningUpdateInfo Interface

What getRunningUpdate() returns.

interface RunningUpdateInfo {
  source: 'embedded' | 'update';
  updateId?: string;
  version: string;
  buildNumber: string;
  confirmed: boolean;
}

InstalledUpdate Interface

What getInstalledUpdate() returns, and how each update is recorded in the state file.

interface InstalledUpdate {
  id: string;
  dir: string;
  version: string;
  build: string | null;
  fingerprint: string | null;
  installedAt: string;
  successfulLaunches: number;
  failedLaunches: number;
}

An update is launchable when successfulLaunches > 0 || failedLaunches === 0, its directory carries the install marker, and its id is not quarantined.

SyncStatus Enum

Status values for the statusCallback.

enum SyncStatus {
  UP_TO_DATE = 'UP_TO_DATE',
  UPDATE_INSTALLED = 'UPDATE_INSTALLED',
  UPDATE_IGNORED = 'UPDATE_IGNORED',
  ERROR = 'ERROR',
  SKIPPING_BECAUSE_HMR_ENABLED = 'SKIPPING_BECAUSE_HMR_ENABLED',
  IN_PROGRESS = 'IN_PROGRESS',
  CHECKING_FOR_UPDATE = 'CHECKING_FOR_UPDATE',
  AWAITING_USER_ACTION = 'AWAITING_USER_ACTION',
  DOWNLOADING_PACKAGE = 'DOWNLOADING_PACKAGE',
  INSTALLING_UPDATE = 'INSTALLING_UPDATE',
  RELOADING_APP = 'RELOADING_APP',
  RELOAD_FAILED = 'RELOAD_FAILED',
  ROLLED_BACK = 'ROLLED_BACK',
}

See Sync Status Reference for detailed documentation.

Telemetry Events

Reported automatically unless enableTelemetry: false. Events are batched and flushed to {updateUrl}/api/update/telemetry.

recoveryPath is 'newer' (a newer update arrived), 'cached' (the previous update), or 'embedded' (the store bundle).

Exports

The SDK exports:

// Main initialization
export { initNorrix, checkUpdates } from './lib/norrix-client-sdk';
 
// Classes and types
export { NorrixUpdates } from './lib/norrix-updates';
export type { UpdateConfig, UpdateInfo } from './lib/norrix-updates';
 
// Enum (also available as type)
export { SyncStatus } from './lib/norrix-updates';
 
// Launch state, for diagnostics and custom version labels
export { getRunningInfo, getLaunchStatus } from './lib/ota/launch-monitor';
export { selectLaunch, launchableUpdates } from './lib/ota/select-launch';
export type {
  BinaryIdentity,
  InstalledUpdate,
  LaunchMode,
  LaunchOutcome,
  LaunchRecord,
  OtaState,
} from './lib/ota/types';
 
// Telemetry
export {
  SDK_VERSION,
  trackOtaEvent,
  flushTelemetry,
  trackAppLaunch,
  configureTelemetry,
} from './lib/norrix-telemetry';