Fingerprinting

Norrix uses fingerprinting to determine if an OTA update is compatible with a deployed native binary. The fingerprint captures the state of native dependencies to ensure safe updates.

What Gets Fingerprinted

1. Native Plugins

All npm packages with NativeScript native code:

• Detected by checking for nativescript key in package.json
• Version numbers are captured from installed packages

2. App_Resources

Contents of your App_Resources folder:

• Recursive hash of all files
• Excludes hidden files (.DS_Store, etc.)
• Excludes the fingerprint file itself

3. Native Sources

Custom native code defined in nativescript.config.ts:

• Files matching NativeSource patterns
• Hashed and included in fingerprint

norrix fingerprint

Print the fingerprint for your project.

Synopsis

norrix fingerprint [platform] [options]

Arguments

Options

Output

Displays fingerprint details:

• Hash (SHA-256)
• Native plugins with versions
• App_Resources hash
• NativeSource hash (if applicable)

Examples

# Print iOS fingerprint
norrix fingerprint ios
 
# Print Android fingerprint with app ID
norrix fingerprint android --app-id com.example.myapp

norrix fingerprint compare

Compare fingerprints between a stored build and another build or local project.

Synopsis

norrix fingerprint compare --from <buildId> [--to <buildIdOrLocal>]

Options

Behavior

When comparing:

1. Fetches the fingerprint from the source build
2. Computes or fetches the target fingerprint
3. Compares all fingerprint components
4. Reports compatibility and differences

Examples

# Compare build to local project
norrix fingerprint compare --from build-123
 
# Compare two builds
norrix fingerprint compare --from build-123 --to build-456

Output

The comparison shows:

• Compatible: ✅ OTA updates are safe
• Incompatible: ❌ A new store build is required

If incompatible, the output details what changed:

• Plugin version changes
• App_Resources changes
• NativeSource changes

Fingerprint File

At build time, Norrix writes a fingerprint file to your app’s assets:

assets/norrix.fingerprint.json

Example content:

{
  "createdAt": "2024-01-01T00:00:00.000Z",
  "platform": "ios",
  "hash": "abc123def456...",
  "nativePlugins": {
    "@nativescript/core": "8.6.0",
    "nativescript-camera": "4.5.0",
    "@nativescript/imagepicker": "1.0.0"
  },
  "appResourcesHash": "def456...",
  "nativeSourcesHash": "ghi789..."
}

This file is bundled into the app binary and read at runtime by the Client SDK.

How Fingerprinting Works

At Build Time

1. Norrix computes the fingerprint from your project
2. The hash is stored in the build record
3. The fingerprint file is written to assets/
4. The file is included in the native binary

At Update Time

1. Norrix computes the fingerprint from your project
2. The hash is stored with the update record
3. When a device checks for updates, fingerprints are compared

At Runtime

1. The Client SDK reads the bundled fingerprint file
2. On update check, the SDK sends its fingerprint to the server
3. The server compares fingerprints
4. If compatible: returns OTA download URL
5. If incompatible: returns requiresStoreUpdate: true

Fingerprint Caching

The SDK caches the native binary’s fingerprint in ApplicationSettings:

• Key: Norrix_Binary_Fingerprint
• Persists across OTA updates
• Ensures the original native fingerprint is always used

This prevents the fingerprint from changing when running from an OTA bundle stored in a different location.

Best Practices

1. Check before publishing: Run norrix fingerprint compare before publishing OTA updates
2. Version native plugins carefully: Plugin updates often require new store builds
3. Monitor App_Resources: Changes to icons, launch screens, etc. require store builds
4. Use NativeSource patterns: Declare all custom native code in nativescript.config.ts