ReleaseTag iOS SDK

Overview

The ReleaseTag iOS SDK captures crashes from POSIX signals and uncaught NSExceptions, writes them to disk using async-signal-safe I/O, and uploads them on the next healthy app launch. Combined with dSYM uploads, crash reports are automatically symbolicated to show function names instead of raw memory addresses.

Requirements

• iOS 15.0+ / macOS 12.0+ / visionOS 1.0+
• Swift 6.0+
• Xcode 15+

Installation

Swift Package Manager

In Xcode: File → Add Package Dependencies and enter the repository URL:

https://github.com/releasetag/releasetag-ios.git

Or add it to your Package.swift:

.package(url: "https://github.com/releasetag/releasetag-ios.git", from: "1.0.0")

Setup

Step 1: Create an SDK key

1. Go to Project Settings → Integrations
2. Find the ReleaseTag SDK section
3. Click Create Key and copy the generated key (format: rt_pk_...)

Step 2: Initialize the SDK

Call ReleaseTag.start() as early as possible in your app's lifecycle:

import ReleaseTag

@main
struct MyApp: App {
    init() {
        ReleaseTag.start(apiKey: "rt_pk_your_key_here")
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

For UIKit apps, initialize in application(_:didFinishLaunchingWithOptions:).

Step 3: Upload dSYM files for symbolication

Release builds strip debug symbols, so crash backtraces contain raw memory addresses. Upload your dSYM files so ReleaseTag can symbolicate crashes into readable function names.

Add a Run Script build phase to your Xcode target:

1. Select your target → Build Phases → + → New Run Script Phase
2. Paste the following script:

   if [ "$CONFIGURATION" != "Release" ]; then
     exit 0
   fi
   
   "${SRCROOT}/path/to/Scripts/upload-dsyms.sh" \
       --api-key "rt_pk_your_key_here"

3. Add an input file: $(DWARF_DSYM_FOLDER_PATH)/$(DWARF_DSYM_FILE_NAME)

Make sure your Debug Information Format build setting is set to DWARF with dSYM File for Release builds.

CI / manual upload

You can also run the script manually or from CI, passing dSYM paths directly:

./Scripts/upload-dsyms.sh \
    --api-key "rt_pk_your_key_here" \
    /path/to/MyApp.app.dSYM

How it works

1. Initialization — ReleaseTag.start() installs POSIX signal handlers and an NSException handler, and snapshots all loaded binary images for symbolication.
2. Crash capture — Signal crashes are written to disk using pre-allocated buffers and async-signal-safe I/O (no malloc, no locks). Exception crashes write a full JSON report. Both include the binary image list for symbolication.
3. Upload — On the next healthy launch, pending reports are uploaded. The server matches binary image UUIDs against uploaded dSYM symbol tables to symbolicate the backtrace.
4. Retroactive symbolication — If dSYMs are uploaded after a crash has already been recorded, existing crash logs are automatically symbolicated.

User identification

By default, crash reports use an anonymous device identifier. To associate crashes with a specific user in your system:

ReleaseTag.setUserId("user-123")

This also retroactively links any previously anonymous crash reports from the same device to the identified user.

What gets captured

• Signal name or NSException name and reason
• Full stack trace with binary image data
• Device model and OS version
• App version and build number
• Free memory and disk space
• Anonymous device ID or custom user ID

Troubleshooting

Crashes not appearing

• Verify the SDK key is correct and active in Project Settings → Integrations
• Check the device logs (Console.app, subsystem com.releasetag.sdk) for upload errors
• Crashes are uploaded on the next launch after the crash — the app must be opened again

Backtraces showing raw addresses

• Ensure dSYM files are being uploaded via the build phase script
• Verify Debug Information Format is set to DWARF with dSYM File (not just DWARF)
• If dSYMs were uploaded after the crash, the backtrace will be retroactively symbolicated

Support

Having trouble? Contact us at support@releasetag.com