Crash Symbolication & dSYMs (iOS)

FireworkVideo is distributed as a prebuilt binary XCFramework. Because your app does not compile the SDK, Xcode never generates a dSYM for it during your build or archive, and the FireworkVideo.xcframework itself does not bundle a dSYMs/ folder. As a result, crash reporting tools (Embrace, Firebase Crashlytics, Sentry, Datadog, Bugsnag, etc.) will report "missing dSYM" for frames inside FireworkVideo unless you upload the SDK's dSYM yourself.

This page explains where to find the dSYMs and how to get them into your crash reporting tool.

Where to find the dSYMs

Every SDK release on GitHub ships a separate dSYMs-v<version>.zip asset next to the .xcframework.zip:

https://github.com/loopsocial/firework_ios_sdk/releases/download/v<version>/dSYMs-v<version>.zip

For example, for SDK 1.44.3:

https://github.com/loopsocial/firework_ios_sdk/releases/download/v1.44.3/dSYMs-v1.44.3.zip

The zip has the following layout:

dSYMs/
├── ios/
│   └── FireworkVideo.framework.dSYM        <- upload this one
└── simulator/
    └── FireworkVideo.framework.dSYM        <- simulator only, not needed for production crashes

The dSYM must match the exact SDK version you ship. A dSYM is matched to a binary by UUID, so the dSYM for 1.44.2 cannot symbolicate crashes from 1.44.3. Download the zip whose version matches the version pinned in your Package.resolved / Podfile.lock, and repeat this whenever you bump the SDK.

You can verify the UUIDs match with dwarfdump:

# UUID of the binary you ship
dwarfdump --uuid FireworkVideo.xcframework/ios-arm64/FireworkVideo.framework/FireworkVideo

# UUID of the dSYM
dwarfdump --uuid dSYMs/ios/FireworkVideo.framework.dSYM

Option 1: Upload manually

Download the zip for your SDK version, unzip it, and upload dSYMs/ios/FireworkVideo.framework.dSYM using your crash reporting tool's dSYM upload CLI or web UI. Refer to your vendor's documentation, for example:

• Embrace: embrace upload / dSYM upload endpoint

• Firebase Crashlytics: upload-symbols -gsp GoogleService-Info.plist -p ios <path-to-dSYM>

• Sentry: sentry-cli debug-files upload <path-to-dSYM>

This is the quickest way to unblock symbolication for a release that is already live.

Option 2: Fetch automatically during archive (recommended)

Most crash reporting SDKs install a Run Script build phase that uploads every dSYM found in $DWARF_DSYM_FOLDER_PATH when you archive. You can add a script before that phase which downloads the matching FireworkVideo dSYM into the same folder, so it is picked up by your existing upload step and stays in sync with the SDK version automatically.

In Xcode, select your app target > Build Phases > + > New Run Script Phase. Rename the phase to Fetch FireworkVideo dSYM (double-click the phase title) and paste the following script. Keep it after the built-in phases (Compile Sources, Link Binary With Libraries, Copy Bundle Resources — the default position for a new phase) and above your crash reporter's dSYM upload phase (e.g. "Embrace Symbol Upload", "Upload Crashlytics dSYMs", "Sentry Upload Debug Symbols"):

#!/bin/bash
# Downloads the FireworkVideo dSYM matching the SDK version linked into this build
# and places it in DWARF_DSYM_FOLDER_PATH so crash-reporter upload scripts can find it.

set -euo pipefail

# Only needed when this build generates dSYMs (Debug Information Format = "DWARF with dSYM File",
# which is Xcode's default for Release / archive builds).
if [ "${DEBUG_INFORMATION_FORMAT:-}" != "dwarf-with-dsym" ]; then
  echo "FireworkVideo dSYM: skipping, DEBUG_INFORMATION_FORMAT is '${DEBUG_INFORMATION_FORMAT:-}' (no dSYM generated for this build)"
  exit 0
fi

# Locate the FireworkVideo framework that was actually linked into the app.
FRAMEWORK_PLIST=$(find "${BUILT_PRODUCTS_DIR}" -path "*FireworkVideo.framework/Info.plist" -print -quit)
if [ -z "${FRAMEWORK_PLIST}" ]; then
  echo "FireworkVideo dSYM: FireworkVideo.framework not found in ${BUILT_PRODUCTS_DIR}, skipping"
  exit 0
fi

SDK_VERSION=$(/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" "${FRAMEWORK_PLIST}")
DSYM_DEST="${DWARF_DSYM_FOLDER_PATH}/FireworkVideo.framework.dSYM"

if [ -d "${DSYM_DEST}" ]; then
  echo "FireworkVideo dSYM: already present at ${DSYM_DEST}"
  exit 0
fi

ZIP_URL="https://github.com/loopsocial/firework_ios_sdk/releases/download/v${SDK_VERSION}/dSYMs-v${SDK_VERSION}.zip"
TMP_DIR=$(mktemp -d)
trap 'rm -rf "${TMP_DIR}"' EXIT

echo "FireworkVideo dSYM: downloading ${ZIP_URL}"
if ! curl -fsSL "${ZIP_URL}" -o "${TMP_DIR}/dSYMs.zip"; then
  # Do not fail the archive; just surface a warning in Xcode's issue navigator.
  echo "warning: FireworkVideo dSYM: failed to download ${ZIP_URL}. FireworkVideo crashes will not be symbolicated unless you upload the dSYM manually."
  exit 0
fi
unzip -q "${TMP_DIR}/dSYMs.zip" -d "${TMP_DIR}"

mkdir -p "${DWARF_DSYM_FOLDER_PATH}"
cp -R "${TMP_DIR}/dSYMs/ios/FireworkVideo.framework.dSYM" "${DSYM_DEST}"
echo "FireworkVideo dSYM: installed to ${DSYM_DEST}"

Disable User Script Sandboxing. Xcode 15+ enables ENABLE_USER_SCRIPT_SANDBOXING by default for new projects, which blocks this script from reading the build products directory and from accessing the network. In your app target's Build Settings, set User Script Sandboxing to No for every configuration you archive with. Otherwise the archive fails with errors like Sandbox: find(...) deny(1) file-read-data ... or Sandbox: curl(...) deny(1) network-outbound. Crash reporter upload scripts (Embrace, Crashlytics, Sentry) require the same setting.

Notes:

• The script runs only when Debug Information Format is set to DWARF with dSYM File (dwarf-with-dsym) for the current configuration — Xcode's default for Release — so it costs nothing on Debug builds and works with custom configuration names (e.g. Staging, Production). This is the same setting your crash reporter needs to produce your app's own dSYM.

• Leave Based on dependency analysis unchecked and the input/output file lists empty so the script runs on every archive.

• The script reads the SDK version from the FireworkVideo.framework that was linked into the build, so it works for both Swift Package Manager and CocoaPods installations and never drifts from the version you actually ship.

• The script targets stable releases only. Pre-release versions (x.y.z-beta.N) report their version as x.y.z in Info.plist, so the download will not find a matching asset; the script then emits a build warning and lets the archive continue. Upload the dSYM manually (Option 1) for beta builds.

• Your build machine (including CI) needs network access to github.com. The repository is public, so no token is required.

• If your archive pipeline uploads dSYMs from the .xcarchive instead of a build phase (e.g. Fastlane download_dsyms / upload_symbols_to_crashlytics), point that step at the extracted dSYMs/ios/FireworkVideo.framework.dSYM as an additional path.

Static XCFramework

If you integrate the static variant manually (FireworkVideo-static-v<version>.xcframework.zip), no separate dSYM is needed: the static library's code is linked directly into your app binary, so its symbols are included in the dSYM that Xcode generates for your app during archive.

Reporting a crash to Firework

When reporting a crash inside the SDK to Firework support, please include:

• The exact SDK version (from Package.resolved / Podfile.lock)

• The full crash report. A fully symbolicated report (including the FireworkVideo frames) is ideal. If the FireworkVideo frames are still unsymbolicated, also attach the original .ips / .crash file with the binary images and load addresses preserved, so we can symbolicate those frames with the matching dSYM on our side.

• iOS version and device model

• Reproduction steps, if known