SDK Configuration

Configure the SDK when initializing with initNorrix().

Configuration Options

Option	Type	Default	Description
`updateUrl`	`string`	required	Base URL for Norrix OTA server
`checkForUpdatesOnLaunch`	`boolean`	`false`	Automatically check on app start
`installUpdatesAutomatically`	`boolean`	`false`	Auto-download and install updates
`allowStoreUpdateOverride`	`boolean`	`false`	Apply OTA even when store update required
`promptToRestartAfterInstall`	`boolean`	`false`	Show restart dialog after install
`retryFailedUpdates`	`boolean`	`false`	Allow quarantined updates to be offered
`statusCallback`	`function`	-	Callback for sync status changes
`downloadProgressCallback`	`function`	-	Download progress callback (0-100)

Basic Configuration

Minimal setup with automatic updates:


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

Configuration Details

updateUrl (required)

Base URL for your Norrix OTA server.


updateUrl: 'https://norrix.net';

The SDK constructs the check endpoint as:


{updateUrl}/api/update/check/{bundleId}?currentVersion=...

checkForUpdatesOnLaunch

When true, the SDK automatically calls checkForUpdates() when constructed.


checkForUpdatesOnLaunch: true;

installUpdatesAutomatically

When true, compatible updates are automatically downloaded and installed.


installUpdatesAutomatically: true;

The update is activated on the next app restart.

allowStoreUpdateOverride

When the server indicates an update requires a new store binary (incompatible native changes), this option controls behavior:

false (default): Update is ignored, app continues normally
true: Update is applied anyway (use with caution)


allowStoreUpdateOverride: true; // Not recommended for production

promptToRestartAfterInstall

When true, shows a native dialog prompting the user to restart after an update is installed:


promptToRestartAfterInstall: true;

Dialog text:

Title: “Update Installed”
Message: “Would you like to reload the app now to apply the update?”
Buttons: “Apply Now” / “Later”

retryFailedUpdates

An update that fails to launch before it has ever displayed content is quarantined: it is never launched again and never reinstalled while the current store binary is in place. Its id is sent to the server as excludeIds on each check, and filtered locally as well.

Set this to true to let the server offer a quarantined update again:


retryFailedUpdates: true; // debugging a rollout

Quarantine is cleared automatically when the app is updated from the store. Use getQuarantinedUpdateIds() to see what is currently quarantined on a device.

statusCallback

Called whenever the sync status changes:


statusCallback: (status, data) => {
  console.log('Status:', status, data);
};

See Sync Status Reference for all status values.

downloadProgressCallback

Called with download progress (0-100):


downloadProgressCallback: (progress) => {
  console.log(`Download progress: ${progress}%`);
};

Advanced Configuration

Full configuration with all callbacks:


import { initNorrix, SyncStatus } from '@norrix/client-sdk';
 
const norrix = initNorrix({
  updateUrl: 'https://norrix.net',
  checkForUpdatesOnLaunch: true,
  installUpdatesAutomatically: true,
  promptToRestartAfterInstall: true,
 
  statusCallback: (status, data) => {
    switch (status) {
      case SyncStatus.CHECKING_FOR_UPDATE:
        console.log('Checking for updates...');
        break;
      case SyncStatus.DOWNLOADING_PACKAGE:
        console.log('Downloading update...');
        break;
      case SyncStatus.INSTALLING_UPDATE:
        console.log('Installing update...');
        break;
      case SyncStatus.UPDATE_INSTALLED:
        console.log(`Update ${data?.version} installed!`);
        break;
      case SyncStatus.UP_TO_DATE:
        console.log('App is up to date');
        break;
      case SyncStatus.UPDATE_IGNORED:
        console.log('Update skipped:', data?.compatibilityReason);
        break;
      case SyncStatus.ERROR:
        console.error('Update error:', data?.message);
        break;
    }
  },
 
  downloadProgressCallback: (progress) => {
    // Update UI with progress
    updateProgressBar(progress);
  },
});

Environment-Specific Configuration

Use different URLs for different environments:


const updateUrl = __DEV__ ? 'https://dev.norrix.dev' : 'https://norrix.net';
 
initNorrix({
  updateUrl,
  checkForUpdatesOnLaunch: !__DEV__, // Skip in dev
  installUpdatesAutomatically: !__DEV__,
});

When to Initialize

Import @norrix/client-sdk at the top of your app entry file (main.ts or app.ts) and call initNorrix() synchronously during bootstrap, before you start the app.

The SDK arms its launch monitor when the module is evaluated, so the import position matters more than where the initNorrix() call sits. Initializing late — on a timer, after login, behind a lazy route — delays telemetry and the first update check, and delays the point at which a successful launch is confirmed. It cannot cause a rollback.

NativeScript Core


// app.ts
import { Application } from '@nativescript/core';
import { initNorrix } from '@norrix/client-sdk';
 
initNorrix({
  updateUrl: 'https://norrix.net',
  checkForUpdatesOnLaunch: true,
  installUpdatesAutomatically: true,
});
 
Application.run({ moduleName: 'app-root' });

NativeScript Angular


// main.ts
import { platformNativeScript } from '@nativescript/angular';
import { initNorrix } from '@norrix/client-sdk';
import { AppModule } from './app/app.module';
 
initNorrix({
  updateUrl: 'https://norrix.net',
  checkForUpdatesOnLaunch: true,
  installUpdatesAutomatically: true,
});
 
platformNativeScript().bootstrapModule(AppModule);

NativeScript Vue


// app.ts
import { createApp } from 'nativescript-vue';
import { initNorrix } from '@norrix/client-sdk';
import App from './App.vue';
 
initNorrix({
  updateUrl: 'https://norrix.net',
  checkForUpdatesOnLaunch: true,
  installUpdatesAutomatically: true,
});
 
createApp(App).start();