diff --git a/docs/platforms/apple/common/install/index.mdx b/docs/platforms/apple/common/install/index.mdx index e5f3e0c6dd493..375cf466317dd 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 ad7414b5d67cd..34abb27302005 100644 --- a/docs/platforms/apple/common/install/manual-install.mdx +++ b/docs/platforms/apple/common/install/manual-install.mdx @@ -7,14 +7,21 @@ 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` — 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):** + - `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. +- `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 1c8a3e4524a96..595b1e394ee66 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`** — 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: ```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.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. + +### Installation + +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`: + +```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.