Skip to Content
ConceptsFingerprinting

Fingerprinting

Fingerprinting is Norrix’s mechanism for tracking native dependencies and ensuring OTA updates are compatible with deployed binaries.

Why Fingerprinting?

NativeScript apps consist of:

  1. JavaScript code: Your app logic, easily updatable
  2. Native code: Platform code, plugins, resources

OTA updates can safely replace JavaScript, but native code changes require a new app store binary. Fingerprinting automatically detects when this boundary is crossed.

What Gets Fingerprinted

1. Native Plugins

All npm packages with NativeScript native code:

{
  "nativePlugins": {
    "@nativescript/core": "8.6.0",
    "nativescript-camera": "4.5.0",
    "@nativescript/imagepicker": "1.0.0"
  }
}

Detection:

  • Scans package.json for nativescript key
  • Captures version numbers from installed packages
  • Includes all native-containing dependencies

2. App_Resources

The App_Resources folder contains native assets:

App_Resources/
├── iOS/
│   ├── Info.plist
│   ├── Assets.xcassets/
│   └── LaunchScreen.storyboard
└── Android/
    ├── src/main/
    └── values/

Hashing:

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

3. Native Sources

Custom native code defined in nativescript.config.ts:

// nativescript.config.ts
export default {
  id: 'com.example.app',
  appResourcesPath: 'App_Resources',
 
  // These get fingerprinted
  ios: {
    NativeSource: ['native-src/ios/**'],
  },
  android: {
    NativeSource: ['native-src/android/**'],
  },
};

Hashing:

  • Finds files matching NativeSource patterns
  • Computes combined hash
  • Result: nativeSourcesHash

Fingerprint Computation

The fingerprint is a SHA-256 hash of all components:

fingerprint = SHA256(
  JSON.stringify(sortedNativePlugins) +
  appResourcesHash +
  nativeSourcesHash
)

CLI Command

View your project’s fingerprint:

norrix fingerprint ios

Output:

Fingerprint for ios:
  Hash: abc123def456...

  Native Plugins:
    @nativescript/core: 8.6.0
    nativescript-camera: 4.5.0

  App_Resources Hash: def456...
  NativeSource Hash: ghi789...

Fingerprint File

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

assets/norrix.fingerprint.json

Contents:

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

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

Runtime Behavior

SDK Fingerprint Reading

The SDK reads the fingerprint on initialization:

  1. Check ApplicationSettings for cached fingerprint
  2. If not cached, read from assets/norrix.fingerprint.json
  3. Cache the result for future use

Caching Purpose

The SDK caches the original binary fingerprint because:

  • OTA updates may change file paths
  • The original fingerprint must be preserved
  • Ensures consistent compatibility checking

Storage key: Norrix_Binary_Fingerprint

Fingerprint Comparison

At Update Time

When you publish an update:

norrix update ios 1.0.1

Norrix:

  1. Computes the current project fingerprint
  2. Stores it with the update record
  3. This fingerprint is used for compatibility checks

At Check Time

When a device checks for updates:

  1. Device sends its fingerprint in the request
  2. Server compares with update fingerprint
  3. If match: Returns OTA download URL
  4. If mismatch: Returns requiresStoreUpdate: true

CLI Commands

norrix fingerprint ios
norrix fingerprint android

Compare Fingerprints

Compare a build to your local project:

norrix fingerprint compare --from build-123

Compare two builds:

norrix fingerprint compare --from build-123 --to build-456

Output shows:

  • Compatibility status
  • Changed plugins
  • Changed hashes
  • Specific differences

Troubleshooting

Unexpected Incompatibility

If updates are unexpectedly incompatible:

  1. Run fingerprint compare:

    norrix fingerprint compare --from <last-build-id>

  2. Check what changed:

    • Plugin version updates?
    • App_Resources changes?
    • NativeSource modifications?

  3. If changes are intentional, publish a new store build

Missing Fingerprint File

If the SDK can’t find the fingerprint:

  • Ensure the build was made with Norrix CLI
  • Check assets/norrix.fingerprint.json exists
  • Verify the file wasn’t stripped during build

Fingerprint Mismatch

Common causes:

  • Dev/prod dependency differences
  • Platform-specific plugin versions
  • Modified App_Resources between builds
OverviewOTA Compatibility