iOS crash symbolication with dSYMs

Symbolication turns captured native addresses into function names and source locations when the exact build's debug information is available. NativeWatch matches iOS frames by project, binary UUID and CPU architecture, retaining the original raw frames.

#Keep the symbols from the shipped binary

Rebuild with the current mobile plugin. Older events without a binary UUID and architecture cannot be matched safely after the fact.

Archive the app in Xcode's Release configuration with DWARF with dSYM File (DEBUG_INFORMATION_FORMAT=dwarf-with-dsym). Keep the app and framework dSYMs from the exact archive you distribute. A new build from the same source is not a substitute: verify identities as described in Apple's build UUID guidance.

The plugin uses KSCrash for fatal native capture. If your app already embeds another KSCrash owner, coordinate that integration before shipping; the recorder has one configuration per process. Keep the Swift package resolution file with your build evidence.

#Upload privately from CI

Create a project CI token and store it as the secret NATIVEWATCH_RELEASE_TOKEN. A GitHub repository connection is not required for symbol uploads. Install the SDK dependencies in the CI checkout and run this after the archive step, with both path variables set to your actual build locations:

export NATIVEWATCH_URL=https://native.watch
php artisan nativewatch:symbols \
  "$ARCHIVE_PATH/dSYMs/YourApp.app.dSYM" \
  --source-root="$BUILD_CHECKOUT_ROOT"

The source root is the absolute checkout directory recorded by the compiler, not where you later downloaded the archive. If the build remaps debug paths, pass that remapped root. Upload each relevant framework dSYM too. The command also accepts a regular DWARF file from a dSYM's Contents/Resources/DWARF directory; do not pass a ZIP archive.

The command verifies the server's SHA-256 receipt and prints indexed UUID/architecture identities. Identical retries are safe. A different artifact for an existing identity returns HTTP 409.

Keep the token scoped to this upload step, outside the environment used to package the app. It must not enter a bundled .env, Info.plist or Android resource. Uploading your build symbols does not grant a user's diagnostic consent.

#Read the result

After a consented test crash and relaunch, open the matching occurrence. Symbolication runs asynchronously; an open event polls while that work is pending.

Late uploads requeue retained matching occurrences. Refresh an already open event after uploading. Show raw frames preserves the binary identity, offset and address kind for comparison. Symbolication does not change the stored event's grouping fingerprint.

#Verify the limits

Optimized code, generated thunks and system images may lack exact source lines even with correct symbols. MetricKit diagnostics can arrive later and need physical-device testing; an unknown historical binary architecture cannot be guessed safely. Android mapping and native symbol processing are separate capabilities, not provided by this iOS upload command.

Use a fully compiled Release app outside the debugger, trigger a private development crash, relaunch, and match the actual event's build and mechanism. Compare raw and resolved frames against the archived build. Compilation alone does not prove runtime capture, and physical-iPhone flight-mode acceptance remains deferred in current project evidence.

dSYMs contain private function names and build paths. Restrict artifact and token access, and include symbols in your retention process. Follow privacy and consent for collection and offline delivery for the crash-to-relaunch path.