sentry-ios-swift-setup

---
name: sentry-ios-swift-setup
description: Setup Sentry in iOS/Swift apps. Use when asked to add Sentry to iOS, install sentry-cocoa SDK, or configure error monitoring for iOS applications using Swift and SwiftUI.
license: Apache-2.0
---

# Sentry iOS Swift Setup

Install and configure Sentry in iOS projects using Swift and SwiftUI.

## Invoke This Skill When

- User asks to "add Sentry to iOS" or "install Sentry" in a Swift app
- User wants error monitoring, tracing, or session replay in iOS
- User mentions "sentry-cocoa" or iOS crash reporting

**Important:** The configuration options and code samples below are examples. Always verify against [docs.sentry.io](https://docs.sentry.io) before implementing, as APIs and defaults may have changed.

## Requirements

- iOS 15.0+, macOS 12.0+, tvOS 15.0+, watchOS 8.0+

## Install

### Swift Package Manager (Recommended)

1. File > Add Package Dependencies
2. Enter: `https://github.com/getsentry/sentry-cocoa.git`
3. Select version rule: "Up to Next Major" from `9.5.0`

**SPM Products:** Choose based on your needs:

| Product | Use Case |
|---------|----------|
| `Sentry` | Default (static linking) |
| `Sentry-Dynamic` | Dynamic framework |
| `SentrySwiftUI` | SwiftUI view performance tracking |
| `Sentry-WithoutUIKitOrAppKit` | App extensions or CLI tools |

### CocoaPods

```ruby
# Podfile
pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '9.5.0'
```

Then run `pod install`.

## Configure

### SwiftUI App

```swift
import SwiftUI
import Sentry

@main
struct YourApp: App {
    init() {
        SentrySDK.start { options in
            options.dsn = "YOUR_SENTRY_DSN"
            options.debug = true
            
            // Tracing
            options.tracesSampleRate = 1.0
            
            // Profiling
            options.configureProfiling = {
                $0.sessionSampleRate = 1.0
                $0.lifecycle = .trace
            }
            
            // Session Replay
            options.sessionReplay.sessionSampleRate = 1.0
            options.sessionReplay.onErrorSampleRate = 1.0
            
            // Logs (SDK 9.0.0+; for 8.55.0-8.x use options.experimental.enableLogs)
            options.enableLogs = true
            
            // Error context
            options.attachScreenshot = true
            options.attachViewHierarchy = true
        }
    }
    
    var body: some Scene {
        WindowGroup { ContentView() }
    }
}
```

### UIKit App

```swift
import UIKit
import Sentry

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        SentrySDK.start { options in
            options.dsn = "YOUR_SENTRY_DSN"
            options.debug = true
            options.tracesSampleRate = 1.0
            options.enableLogs = true
        }
        return true
    }
}
```

## Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `dsn` | Sentry DSN | Required |
| `tracesSampleRate` | % of transactions traced | `0` |
| `sessionReplay.sessionSampleRate` | % of sessions replayed | `0` |
| `sessionReplay.onErrorSampleRate` | % of error sessions replayed | `0` |
| `enableLogs` | Send logs to Sentry | `false` |
| `attachScreenshot` | Attach screenshot on error | `false` |
| `attachViewHierarchy` | Attach view hierarchy on error | `false` |

## Auto-Instrumented Features

| Feature | What's Captured |
|---------|-----------------|
| App Launches | Cold/warm start times |
| Network | URLSession requests |
| UI | UIViewController loads, user interactions |
| File I/O | Read/write operations |
| Core Data | Fetch/save operations |
| Frames | Slow and frozen frame detection |

## Logging

```swift
let logger = SentrySDK.logger

logger.info("User action", attributes: [
    "userId": "123",
    "action": "checkout"
])

// Log levels: trace, debug, info, warn, error, fatal
```

## Session Replay

**iOS 26+ / Xcode 26+ caveat:** SDK 8.57.0+ automatically disables Session Replay on iOS 26.0+ when built with Xcode 26.0+ due to Apple's Liquid Glass rendering breaking masking reliability. Replay still works on iOS < 26 or Xcode < 26. To force-enable (use with caution): `options.experimental.enableSessionReplayInUnreliableEnvironment = true`.

### Masking

```swift
// SwiftUI modifiers
Text("Safe content").sentryReplayUnmask()
Text(user.email).sentryReplayMask()
```

## User Context

```swift
let user = User()
user.userId = "user_123"
user.email = "user@example.com"
SentrySDK.setUser(user)

// Clear on logout
SentrySDK.setUser(nil)
```

## Verification

```swift
// Test error capture
SentrySDK.capture(message: "Test from iOS")

// Or trigger a test error
do {
    try someFailingFunction()
} catch {
    SentrySDK.capture(error: error)
}
```

## Production Settings

```swift
SentrySDK.start { options in
    options.dsn = "YOUR_SENTRY_DSN"
    options.debug = false
    options.tracesSampleRate = 0.2  // 20%
    options.sessionReplay.sessionSampleRate = 0.1  // 10%
    options.sessionReplay.onErrorSampleRate = 1.0  // 100% on error
    options.enableLogs = true
}
```

## Size Analysis (Fastlane)

Track app bundle size with Sentry using the Fastlane plugin.

### Install Plugin

```bash
bundle exec fastlane add_plugin fastlane-plugin-sentry
```

### Configure Authentication

```bash
# Environment variable (recommended for CI)
export SENTRY_AUTH_TOKEN=your_token_here
```

Or create `.sentryclirc` (add to `.gitignore`):

```ini
[auth]
token=YOUR_SENTRY_AUTH_TOKEN
```

### Fastfile Lane

```ruby
lane :sentry_size do
  build_app(
    scheme: "YourApp",
    configuration: "Release",
    export_method: "app-store"
  )

  sentry_upload_build(
    org_slug: "your-org",
    project_slug: "your-project",
    build_configuration: "Release"
  )
end
```

### Run Size Analysis

```bash
bundle exec fastlane sentry_size
```

View results in the Sentry UI after the upload completes.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Events not appearing | Check DSN, enable `debug = true` |
| No traces | Set `tracesSampleRate` > 0 |
| No replays | Set `sessionSampleRate` > 0, check SDK 8.31.1+. On iOS 26+/Xcode 26+ see Liquid Glass caveat above |
| No logs | Set `enableLogs = true` (SDK 9.0.0+) or `experimental.enableLogs = true` (SDK 8.55.0-8.x) |
| CocoaPods fails | Run `pod repo update`, check iOS 15+ target |
| Size upload fails | Check `SENTRY_AUTH_TOKEN`, verify org/project slugs |