From f3aba639a0b1c828bb81bcb4a7aa50f28fa994ef Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 29 May 2026 15:34:58 +0200 Subject: [PATCH 1/4] docs(apple): restructure install docs and add SentryObjC Reorganize the SPM page into Pre-compiled, Compile from Source, and SentryObjC sections so users can quickly find the right product. Add SentryObjC xcframeworks to the manual install page and a callout on the install index for ObjC++/no-modules projects. Co-Authored-By: Claude Opus 4.6 --- docs/platforms/apple/common/install/index.mdx | 9 ++ .../apple/common/install/manual-install.mdx | 24 +++-- .../common/install/swift-package-manager.mdx | 90 ++++++++++++++++--- 3 files changed, 103 insertions(+), 20 deletions(-) diff --git a/docs/platforms/apple/common/install/index.mdx b/docs/platforms/apple/common/install/index.mdx index e5f3e0c6dd4931..375cf466317dd8 100644 --- a/docs/platforms/apple/common/install/index.mdx +++ b/docs/platforms/apple/common/install/index.mdx @@ -13,4 +13,13 @@ brew install getsentry/tools/sentry-wizard && sentry-wizard -i ios This will patch your project and configure the SDK. You'll only need to patch the project once, then you'll be able to add the patched files to your version control system. If you prefer, you can choose one of the alternative methods below. + + If your project uses Objective-C++ or can't enable Clang modules, see the{" "} + + SentryObjC + {" "} + section for a pure Objective-C integration that doesn't require Swift headers + or `@import`. + + diff --git a/docs/platforms/apple/common/install/manual-install.mdx b/docs/platforms/apple/common/install/manual-install.mdx index ad7414b5d67cda..dea8d1e00e6310 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -7,14 +7,22 @@ sidebar_order: 3000 To integrate Sentry into your Xcode project, follow these steps: 1. Download the latest version of the SDK from the Sentry Cocoa [Releases page](https://github.com/getsentry/sentry-cocoa/releases). -2. Each release contains the following four framework options: - - Sentry-Dynamic.xcframework.zip: Dynamic framework - - Sentry.xcframework.zip: Static framework - - SentrySwiftUI.xcframework.zip: Static Framework with SwiftUI support - - Sentry-WithoutUIKitOrAppKit.xcframework.zip: Static framework without UIKit or AppKit linking and related features +2. Each release contains the following framework options: + + **Sentry (Swift / standard Objective-C):** + - `Sentry.xcframework.zip` — Static framework (recommended) + - `Sentry-Dynamic.xcframework.zip` — Dynamic framework + - `SentrySwiftUI.xcframework.zip` — Static framework with SwiftUI support + - `Sentry-WithoutUIKitOrAppKit.xcframework.zip` — Static framework without UIKit or AppKit linking and related features + + **SentryObjC (pure Objective-C interface):** + - `SentryObjC.xcframework.zip` — Static framework + - `SentryObjC-Dynamic.xcframework.zip` — Dynamic framework + 3. Import the chosen framework into your Xcode project target. -### Usage Guidelines: +### Usage Guidelines - • Use `Sentry-Dynamic`, `Sentry`, or `Sentry-WithoutUIKitOrAppKit` independently. Only one of these should be included in your project at a time. - • If you're using `SentrySwiftUI`, it must be combined with `Sentry-Dynamic`. +- Use `Sentry-Dynamic`, `Sentry`, or `Sentry-WithoutUIKitOrAppKit` independently. Only one of these should be included in your project at a time. +- If you're using `SentrySwiftUI`, it must be combined with `Sentry-Dynamic`. +- Use **SentryObjC** when you need a pure Objective-C interface — no Swift headers, no `@import`, no `-Swift.h`. This is recommended for Objective-C++ projects or projects with Clang modules disabled. Each SentryObjC framework embeds the full Sentry SDK, so do not link both `Sentry` and `SentryObjC` in the same target. See SentryObjC for configuration details. diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 1c8a3e4524a96e..908ae2765dbf01 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -10,36 +10,42 @@ To integrate Sentry into your Xcode project using Swift Package Manager (SPM), o https://github.com/getsentry/sentry-cocoa.git ``` -You can define your dependency rule by selecting the SDK version (or branch), and then click the "Add Package" button. -You will then be prompted to choose one of the options `Sentry`, `Sentry-Dynamic`, `SentrySwiftUI`, or `SentrySPM`. - -- `Sentry` is the static pre-built framework, which is the recommended option if you prefer a fast app start time. -- `Sentry-Dynamic` is the dynamic pre-built framework. -- `SentrySwiftUI` is used to track performance of SwiftUI views, see more information in the [docs](/platforms/apple/guides/ios/tracing/instrumentation/swiftui-instrumentation/). -- `SentrySPM` compiles the SDK from source as part of your project build instead of using a pre-built binary. This is useful if you want to step through SDK code while debugging. Not all product variants are available yet with this option. +You can define your dependency rule by selecting the SDK version (or branch), and then click the "Add Package" button. You will then be prompted to choose a product — see below for which one to pick. Xcode allows you to choose many options, but you should choose only one of the - options above. + options below. +## Pre-compiled (Recommended) + +These products use pre-built binary frameworks. They don't add to your project's compile time and are the recommended choice for most projects. + +- **`Sentry`** — Static pre-built framework. Recommended for most projects as it provides the fastest app start time. +- **`Sentry-Dynamic`** — Dynamic pre-built framework. Use this if your project requires dynamic linking. +- **`SentrySwiftUI`** — Static pre-built framework with SwiftUI performance tracking. Use this to measure the performance of your SwiftUI views. See [SwiftUI Instrumentation](/platforms/apple/guides/ios/tracing/instrumentation/swiftui-instrumentation/) for more information. + Alternatively, when your project uses a `Package.swift` file to manage dependencies, you can specify the target with: ```swift {tabTitle:Swift} .package(url: "https://github.com/getsentry/sentry-cocoa", from: "{{@inject packages.version('sentry.cocoa') }}"), ``` -## Building Without UIKit or AppKit +## Compile from Source + +The **`SentrySPM`** product compiles the SDK from source as part of your project build instead of using a pre-built binary. This is useful if you want to step through SDK code while debugging. Not all product variants are available yet with this option. + +### Building Without UIKit or AppKit If you're building a command-line tool, a headless server app, or any other target where UIKit or AppKit isn't available, you can use the `NoUIFramework` package trait to strip out UI framework dependencies entirely. This requires **Sentry SDK 9.7.0+**, **Swift 6.1+**, and **Xcode 26.4+**. When enabled, the SDK compiles from source without linking UIKit, AppKit, or SwiftUI. UI-related features like UIViewController tracing and screenshot capture are excluded. -### Xcode +#### Xcode 1. Add the Sentry package as described above. 2. Select the **`SentrySPM`** product instead of `Sentry` or `Sentry-Dynamic`. 3. In your project settings, go to **Package Dependencies**, select the Sentry package, and enable the **`NoUIFramework`** trait. -### Package.swift +#### Package.swift Add the dependency with the `NoUIFramework` trait and depend on the `SentrySPM` product: @@ -65,5 +71,65 @@ let package = Package( ``` - The `SentrySPM` product compiles the SDK from source. This is required for package traits to take effect, since the pre-built binary targets (`Sentry`, `Sentry-Dynamic`) don't support compile-time configuration. + The `SentrySPM` product compiles the SDK from source. This is required for + package traits to take effect, since the pre-built binary targets (`Sentry`, + `Sentry-Dynamic`) don't support compile-time configuration. + + +## SentryObjC + +Available from SDK **9.16.1+**. + +**SentryObjC** is a pure Objective-C wrapper around the Sentry SDK, recommended for projects that use Objective-C++ (`.mm` files), have Clang modules disabled (`-fmodules=NO`), or otherwise can't use `@import` or `-Swift.h`. It provides a standalone ObjC interface with no Swift dependencies in your headers. + +### Installation + +In Xcode, add the Sentry package as described above and select the **`SentryObjC`** product. + +With `Package.swift`: + +```swift {tabTitle:Swift} +.package(url: "https://github.com/getsentry/sentry-cocoa", from: "{{@inject packages.version('sentry.cocoa') }}"), +``` + +Then depend on the `SentryObjC` product: + +```swift {tabTitle:Swift} +.target( + name: "MyApp", + dependencies: [ + .product(name: "SentryObjC", package: "sentry-cocoa"), + ] +) +``` + +### Configuration + +All SentryObjC types use the `SentryObjC` prefix. Import the umbrella header and initialize the SDK: + +```objc +#import + +- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { + + [SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + options.debug = YES; + + // Adds IP for users. + // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/ + options.sendDefaultPii = YES; + + // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring. + // We recommend adjusting this value in production. + options.tracesSampleRate = @1.0; + }]; + + return YES; +} +``` + + + SentryObjC embeds the full Sentry SDK. Do not link both `Sentry` and + `SentryObjC` in the same target. From 965ece2a6baa3cc995b6b0f08b06349f78e8700f Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 29 May 2026 15:40:19 +0200 Subject: [PATCH 2/4] fix(apple): correct SentryObjC availability SentryObjC via SPM compiles from source; only the dynamic xcframework is available pre-compiled. Remove the non-existent static xcframework and clarify the SPM product compiles from source. Co-Authored-By: Claude Opus 4.6 --- docs/platforms/apple/common/install/manual-install.mdx | 1 - docs/platforms/apple/common/install/swift-package-manager.mdx | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/platforms/apple/common/install/manual-install.mdx b/docs/platforms/apple/common/install/manual-install.mdx index dea8d1e00e6310..65d79daad04b9d 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -16,7 +16,6 @@ To integrate Sentry into your Xcode project, follow these steps: - `Sentry-WithoutUIKitOrAppKit.xcframework.zip` — Static framework without UIKit or AppKit linking and related features **SentryObjC (pure Objective-C interface):** - - `SentryObjC.xcframework.zip` — Static framework - `SentryObjC-Dynamic.xcframework.zip` — Dynamic framework 3. Import the chosen framework into your Xcode project target. diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 908ae2765dbf01..8cdf832ff8d91f 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -84,7 +84,7 @@ let package = Package( ### Installation -In Xcode, add the Sentry package as described above and select the **`SentryObjC`** product. +The `SentryObjC` SPM product compiles the SDK from source. In Xcode, add the Sentry package as described above and select the **`SentryObjC`** product. A pre-compiled dynamic framework is also available via manual download. With `Package.swift`: From a04d11792203e5ae04e603baa890a83ca5782fab Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 29 May 2026 15:42:49 +0200 Subject: [PATCH 3/4] docs(apple): deprecate SentrySwiftUI product SwiftUI view performance tracking is now included in the main Sentry product. Mark SentrySwiftUI as deprecated in both SPM and manual install pages. Co-Authored-By: Claude Opus 4.6 --- docs/platforms/apple/common/install/manual-install.mdx | 4 ++-- docs/platforms/apple/common/install/swift-package-manager.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/apple/common/install/manual-install.mdx b/docs/platforms/apple/common/install/manual-install.mdx index 65d79daad04b9d..34abb27302005a 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -12,7 +12,7 @@ To integrate Sentry into your Xcode project, follow these steps: **Sentry (Swift / standard Objective-C):** - `Sentry.xcframework.zip` — Static framework (recommended) - `Sentry-Dynamic.xcframework.zip` — Dynamic framework - - `SentrySwiftUI.xcframework.zip` — Static framework with SwiftUI support + - `SentrySwiftUI.xcframework.zip` — Deprecated. SwiftUI tracking is now included in the main `Sentry` framework. - `Sentry-WithoutUIKitOrAppKit.xcframework.zip` — Static framework without UIKit or AppKit linking and related features **SentryObjC (pure Objective-C interface):** @@ -23,5 +23,5 @@ To integrate Sentry into your Xcode project, follow these steps: ### Usage Guidelines - Use `Sentry-Dynamic`, `Sentry`, or `Sentry-WithoutUIKitOrAppKit` independently. Only one of these should be included in your project at a time. -- If you're using `SentrySwiftUI`, it must be combined with `Sentry-Dynamic`. +- `SentrySwiftUI` is deprecated. If you still use it, it must be combined with `Sentry-Dynamic`. - Use **SentryObjC** when you need a pure Objective-C interface — no Swift headers, no `@import`, no `-Swift.h`. This is recommended for Objective-C++ projects or projects with Clang modules disabled. Each SentryObjC framework embeds the full Sentry SDK, so do not link both `Sentry` and `SentryObjC` in the same target. See SentryObjC for configuration details. diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 8cdf832ff8d91f..4cd31f6ca7d69a 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -23,7 +23,7 @@ These products use pre-built binary frameworks. They don't add to your project's - **`Sentry`** — Static pre-built framework. Recommended for most projects as it provides the fastest app start time. - **`Sentry-Dynamic`** — Dynamic pre-built framework. Use this if your project requires dynamic linking. -- **`SentrySwiftUI`** — Static pre-built framework with SwiftUI performance tracking. Use this to measure the performance of your SwiftUI views. See [SwiftUI Instrumentation](/platforms/apple/guides/ios/tracing/instrumentation/swiftui-instrumentation/) for more information. +- **`SentrySwiftUI`** — Deprecated. SwiftUI view performance tracking is now included in the main `Sentry` product. Do not add this to new projects. Alternatively, when your project uses a `Package.swift` file to manage dependencies, you can specify the target with: From b2f735039d7d1bac426d04661e997aeb1357c9ba Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 29 May 2026 15:47:47 +0200 Subject: [PATCH 4/4] Apply suggestion from @philprime --- docs/platforms/apple/common/install/swift-package-manager.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/apple/common/install/swift-package-manager.mdx b/docs/platforms/apple/common/install/swift-package-manager.mdx index 4cd31f6ca7d69a..595b1e394ee669 100644 --- a/docs/platforms/apple/common/install/swift-package-manager.mdx +++ b/docs/platforms/apple/common/install/swift-package-manager.mdx @@ -78,7 +78,7 @@ let package = Package( ## SentryObjC -Available from SDK **9.16.1+**. +Available from SDK **9.16.0+**. **SentryObjC** is a pure Objective-C wrapper around the Sentry SDK, recommended for projects that use Objective-C++ (`.mm` files), have Clang modules disabled (`-fmodules=NO`), or otherwise can't use `@import` or `-Swift.h`. It provides a standalone ObjC interface with no Swift dependencies in your headers.