feat(objc): Add SentryObjC wrapper SDK

[philprime]

📜 Description

Adds a pure Objective-C SDK wrapper (SentryObjC) that enables Sentry usage in Objective-C++ projects with CLANG_ENABLE_MODULES=NO. This solves the long-standing issue where Swift SDK APIs are inaccessible without Clang modules, affecting React Native, Haxe, and other custom build systems.

What's Included

• SentryObjC module: Pure Objective-C headers that mirror the Swift SDK public API
• SentryObjCBridge: Swift bridge layer that forwards calls from ObjC to the Swift SDK
• Type wrappers: ObjC implementations for Swift-only types (Metrics API, AttributeContent, Units)
• API stability tracking: Automated extraction and CI checks via sdk_objc_api.json
• Sample application: iOS-ObjectiveCpp-NoModules demonstrating real-world usage
• Session Replay support: Full replay API exposed via bridge

💡 Motivation and Context

Closes #6342

The Problem

Since SDK 8.54.0, the Swift SDK's public API requires Clang modules to be imported. When CLANG_ENABLE_MODULES=NO:

• #import <Sentry/Sentry.h> only exposes Objective-C APIs
• Swift types like SentrySDK, SentryOptions.sessionReplay, and the Metrics API are unavailable
• Build errors: use of undeclared identifier 'SentrySDK'

This breaks projects that cannot enable modules, particularly:

• React Native (uses ObjC++ extensively)
• Haxe-based applications
• Custom build systems with strict compiler settings

Implementation Approach & Thought Process

Initial Considerations

Option 1: Make Swift SDK importable without modules

• ❌ Extremely difficult - would require rewriting core SDK architecture
• ❌ Breaks existing Swift API design patterns
• ❌ Not backwards compatible

Option 2: Pure ObjC wrapper (chosen approach)

• ✅ Preserves existing SDK architecture
• ✅ Allows Swift and ObjC to coexist
• ✅ Minimal maintenance burden
• ✅ Clean separation of concerns

Architecture Decision

The wrapper uses a three-layer architecture:

┌─────────────────────────────────────┐
│   SentryObjC (Pure ObjC Headers)    │  ← Public API for no-modules context
│  Sources/SentryObjC/Public/*.h      │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│   SentryObjCBridge (Swift)          │  ← Forwards to Swift SDK
│  Sources/SentryObjCBridge/*.swift   │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│     SentrySwift (Main SDK)          │  ← Actual implementation
└─────────────────────────────────────┘

Why this design?

1. Forward declarations avoid circular dependencies: SentryObjCSDK.m forward-declares SentrySDKInternal without importing headers, letting the linker resolve at build time
2. Bridge handles Swift-ObjC impedance: Complex Swift types (generics, enums with associated values) are converted in the bridge layer
3. Type safety preserved: Bridge validates attribute types and silently fails on invalid input rather than crashing

Key Implementation Decisions

1. Metrics API Type Conversion

Challenge: Swift's SentryAttributeContent enum with associated values cannot be directly bridged to ObjC.

Solution: Created SentryObjCAttributeContent as a class with factory methods:

[SentryObjCAttributeContent stringWithValue:@"endpoint"]
[SentryObjCAttributeContent integerWithValue:200]

Bridge uses KVC to extract values and convert to Swift enums. This avoids circular imports while maintaining type safety.

2. Session Replay API

Initial approach: Tried forward-declaring SentrySDKInternal.replay property

• ❌ Failed: Class properties in ObjC forward declarations are not recognized by the compiler

Final solution: Exposed via bridge

// SentryObjCBridge.swift
@objc public static var replay: AnyObject {
    return SentrySDK.replay
}

// SentryObjCSDK.m
+ (SentryReplayApi *)replay {
    return [SentryObjCBridge replay];
}

This pattern proved more reliable and consistent with the metrics/logger APIs.

3. Lazy Initialization Pattern

Original: Metrics API initialized in +initialize

+ (void)initialize {
    _metricsApi = [[SentryObjCMetricsApiImpl alloc] init];
}

Problem: Runs before SDK initialization, could cause issues if bridge calls Swift before SDK is ready.

Fixed: Switched to dispatch_once lazy initialization:

+ (id<SentryObjCMetricsApi>)metrics {
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{
        _metricsApi = [[SentryObjCMetricsApiImpl alloc] init];
    });
    return _metricsApi;
}

Guarantees thread-safe initialization only when first accessed.

4. Package Manifest Consistency

Bug: Swift 6.1 manifest (Package@swift-6.1.swift) was missing SentryObjCBridge in product targets:

// ❌ Missing bridge
.library(name: "SentryObjC", targets: ["SentryObjCInternal", "SentryObjC", "SentryCppHelper"])

// ✅ Fixed
.library(name: "SentryObjC", targets: ["SentryObjCInternal", "SentryObjCBridge", "SentryObjC", "SentryCppHelper"])

This would cause linker errors on Swift 6.1 since the bridge symbols wouldn't be included.

5. Package Resolution for Compile-from-Source Builds

Problem: SentryObjC product included SentryCppHelper, which isn't available in SPM compile-from-source context, causing package resolution failures in CI.

Solution: Removed SentryCppHelper from SentryObjC product to match SentrySPM pattern:

// Before
.library(name: "SentryObjC", targets: ["SentryObjCInternal", "SentryObjCBridge", "SentryObjC", "SentryCppHelper"])

// After
.library(name: "SentryObjC", targets: ["SentryObjCInternal", "SentryObjCBridge", "SentryObjC"])

SentryCppHelper is only needed for binary distribution products, not compile-from-source products.

Validation Strategy

Robust validation without logging overhead:

// Original approach: Verbose logging for each failure
guard let attr = value as? NSObject else {
    SentrySDK.logger.log("Invalid attribute", level: .warning)
    continue
}

// Final approach: Silent failure, cleaner code
objcAttributes.compactMapValues { value in
    guard let attr = value as? NSObject,
          let type = attr.value(forKey: "type") as? Int,
          let converted = convert(attr, type)
    else { return nil }
    return converted
}

Invalid attributes are silently skipped - this is intentional since:

• Keeps metrics API performant (no logging overhead)
• Prevents log spam from user mistakes
• Matches Swift SDK's behavior for invalid attributes

🧪 Testing Strategy

Unit Tests

• ✅ Metrics API shape and parameter variants
• ✅ Attribute type conversion (string, bool, int, double, arrays)
• ✅ Nil/empty attribute handling
• ✅ Invalid attribute graceful degradation
• ✅ Singleton pattern for metrics API
• ✅ Replay API availability on supported platforms

Integration Tests

• ✅ iOS-ObjectiveCpp-NoModules sample app builds successfully
• ✅ SDK initialization with SentryObjCSDK
• ✅ Session replay configuration (on supported platforms)
• ✅ Metrics recording via ObjC API

Build Verification

make format      # ✅ SwiftLint + clang-format
make analyze     # ✅ 0 violations
make build-ios   # ✅ Compiles for iOS Simulator
make build-sample-iOS-ObjectiveCpp-NoModules  # ✅ Sample builds

API Stability

• Automated extraction via extract-objc-api.sh (uses clang AST parsing)
• CI checks for breaking changes in sdk_objc_api.json
• Prevents accidental API modifications

🔖 Breaking Changes & Compatibility

No Breaking Changes

• Existing SDK users unaffected
• SentryObjC is an additive feature
• Swift SDK API unchanged
• ObjC projects with modules still use the main SDK

Hybrid SDK Impact

• React Native: Can now use SentryObjC for ObjC++ code
• Flutter/Dart: No impact (uses Cocoa SDK via platform channels)
• Unity/Unreal: No impact (uses PrivateSentrySDKOnly SPI)

📝 Checklist

• I added tests to verify the changes
• No new PII added
• Docs updated (sample README, AGENTS.md)
• Wizard update (not applicable - advanced use case)
• Review from native team
• No breaking changes
• No breaking changes for hybrid SDKs

🔗 Related Issues & Context

• Closes Create an ObjC SDK #6342
• Related to Replay options not visible from Objective-C without @import #4543 (original ObjC++ without modules issue)
• Thread safety fix for exception handling extracted to fix(macos): Fix thread safety in NSException capture #7672
• Architectural discussion in internal Slack thread

📦 XCFramework CI Pipeline

The standalone SentryObjC.xcframework build is integrated into the release CI workflow:

• Reuses existing sentry-static slices — no redundant Sentry static builds
• 2 new slice entries: SentryObjCBridge and SentryObjC (staticlib), built in parallel across all platform SDKs
• Custom assembly workflow (assemble-xcframework-sentryobjc.yml): downloads all 3 static slice sets, merges via libtool, links via swiftc into a dynamic framework per SDK, assembles into xcframework
• Dynamic framework detection: instead of hardcoded per-platform framework lists, checks SDK sysroot at link time — works correctly on all platforms including watchOS and tvOS

build-xcframework-variant-slices (matrix: slices × SDKs)
  → sentry-static slices (reused)
  → sentryobjc-bridge slices (new)
  → sentryobjc-objc slices (new)
assemble-xcframework-sentryobjc (custom)
  → libtool + swiftc per SDK → SentryObjC.xcframework

🚀 Future Improvements

Potential follow-ups (not blocking this PR):

1. E2E integration tests: Verify metrics actually reach Sentry backend
2. Performance benchmarks: Measure bridge overhead for metrics API
3. Documentation site: Add guide to docs.sentry.io for ObjC-only users
4. Feedback API: Expose user feedback API via ObjC wrapper
5. Profiling API: Add continuous profiling controls to ObjC wrapper

[github-actions]

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

New Features ✨

• (objc) Add SentryObjC wrapper SDK by philprime in #7598

Documentation 📚

• Add SentryCrash analysis and improvement plan document by itaybre in #7528

Internal Changes 🔧

• (deps) Bump json from 2.18.1 to 2.19.2 by dependabot in #7709

---

_{🤖 This preview updates automatically when you update the PR.}

[github-actions]

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against f05c5fe

[codecov]

Codecov Report

❌ Patch coverage is 0% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.432%. Comparing base (463cbc6) to head (b37e7c5).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...ources/Swift/Protocol/SentryAttributeContent.swift	0.000%	3 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##              main     #7598       +/-   ##
=============================================
- Coverage   86.439%   86.432%   -0.007%     
=============================================
  Files          487       487               
  Lines        40012     40015        +3     
  Branches     18011     18007        -4     
=============================================
  Hits         34586     34586               
- Misses        5375      5379        +4     
+ Partials        51        50        -1     

Files with missing lines	Coverage Δ
Sources/Swift/Core/Helper/Log/SentryLevel.swift	100.000% <ø> (ø)
...ources/Swift/Protocol/SentryAttributeContent.swift	96.899% <0.000%> (-2.308%)	⬇️

... and 6 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 463cbc6...b37e7c5. Read the comment docs.

[philprime]

@sentry review

[sentry]

📲 Install Builds

iOS

🔗 App Name	App ID	Version	Configuration
SDK-Size	io.sentry.sample.SDK-Size	9.10.0 (1)	Release

⚙️ sentry-cocoa Build Distribution Settings

[github-actions]

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	1207.65 ms	1228.72 ms	21.08 ms
Size	24.14 KiB	1.13 MiB	1.11 MiB

Baseline results on branch: main

Startup times

Revision	Plain	With Sentry	Diff
87074ac	1217.81 ms	1255.55 ms	37.74 ms
0ae2f57	1221.43 ms	1252.13 ms	30.70 ms
aa58669	1218.51 ms	1258.55 ms	40.04 ms
24f94fe	1230.71 ms	1265.21 ms	34.49 ms
d69379c	1211.30 ms	1234.77 ms	23.47 ms
dbfeb41	1215.17 ms	1237.41 ms	22.23 ms
301d380	1218.78 ms	1245.53 ms	26.75 ms
59981b9	1207.25 ms	1240.71 ms	33.46 ms
bbee1ba	1197.79 ms	1215.42 ms	17.63 ms
0de46cb	1227.60 ms	1257.60 ms	30.00 ms

App size

Revision	Plain	With Sentry	Diff
87074ac	24.14 KiB	1.12 MiB	1.10 MiB
0ae2f57	24.14 KiB	1.11 MiB	1.09 MiB
aa58669	24.14 KiB	1.10 MiB	1.07 MiB
24f94fe	24.15 KiB	1.10 MiB	1.07 MiB
d69379c	24.14 KiB	1.11 MiB	1.09 MiB
dbfeb41	24.14 KiB	1.04 MiB	1.02 MiB
301d380	24.14 KiB	1.13 MiB	1.11 MiB
59981b9	24.14 KiB	1.09 MiB	1.06 MiB
bbee1ba	24.14 KiB	1.11 MiB	1.09 MiB
0de46cb	24.14 KiB	1.12 MiB	1.10 MiB

Previous results on branch: philprime/objc-wrapper-sdk-6342

Startup times

Revision	Plain	With Sentry	Diff
a1f5242	1222.28 ms	1245.53 ms	23.25 ms
a1c7a37	1218.20 ms	1247.48 ms	29.28 ms
2105a77	1213.57 ms	1225.68 ms	12.12 ms
f042c2d	1217.49 ms	1232.57 ms	15.08 ms
1db3ef0	3762.07 ms	3780.62 ms	18.56 ms
664430d	1225.83 ms	1256.84 ms	31.01 ms
4bff642	1239.29 ms	1268.56 ms	29.28 ms
197530f	1234.94 ms	1261.72 ms	26.79 ms
bb809e8	1229.33 ms	1262.54 ms	33.21 ms
bfbc9c7	1231.69 ms	1262.49 ms	30.79 ms

App size

Revision	Plain	With Sentry	Diff
a1f5242	24.14 KiB	1.12 MiB	1.10 MiB
a1c7a37	24.14 KiB	1.12 MiB	1.10 MiB
2105a77	24.14 KiB	1.13 MiB	1.10 MiB
f042c2d	24.14 KiB	1.12 MiB	1.10 MiB
1db3ef0	24.14 KiB	1.12 MiB	1.10 MiB
664430d	24.14 KiB	1.12 MiB	1.10 MiB
4bff642	24.14 KiB	1.13 MiB	1.11 MiB
197530f	24.14 KiB	1.13 MiB	1.10 MiB
bb809e8	24.14 KiB	1.12 MiB	1.10 MiB
bfbc9c7	24.14 KiB	1.13 MiB	1.11 MiB

[sentry]

Sentry Build Distribution

App	Version	Configuration
App	9.6.0 (1)	Release

[sentry]

Sentry Build Distribution

App	Version	Configuration
App	9.6.0 (1)	Release

[philprime]

CI: SentryObjC XCFramework Pipeline

Added CI support for building the standalone SentryObjC.xcframework as part of the release workflow.

What changed

• 2 new slice entries in generate_release_matrix.sh: SentryObjCBridge and SentryObjC (both as staticlib). The existing sentry-static slices are reused for the Sentry component — no redundant builds.
• New assembly workflow (assemble-xcframework-sentryobjc.yml): downloads all 3 sets of static slices, arranges them into the expected directory layout, then runs build-xcframework-sentryobjc-standalone.sh which does libtool merge + swiftc dynamic link per SDK.
• Byproduct cleanup in slice builds: SentryObjCBridge and SentryObjC slice builds now remove Sentry.framework byproducts (same pattern as SentrySwiftUI).
• Removed -ForEmbedding suffix — investigation confirmed the -ForEmbedding static builds were identical to the normal static builds (same scheme, config, Mach-O type). The suffix was only a directory naming convention from development, not a different build configuration.
• Dynamic framework detection in the standalone script: instead of hardcoded per-platform framework lists (which broke on watchOS/tvOS due to missing WebKit etc.), the script now checks which frameworks actually exist in each SDK's System/Library/Frameworks/ at link time.

CI flow

generate_release_matrix.sh
  → build-xcframework-variant-slices.yml (matrix: 6 slices × N SDKs)
      includes: sentry-static, sentryobjc-bridge, sentryobjc-objc
  → assemble-xcframework-sentryobjc.yml (custom assembly)
      downloads sentry-static + sentryobjc-bridge + sentryobjc-objc slices
      libtool + swiftc per SDK → SentryObjC.xcframework

[github-actions]

🚨 Detected changes in high risk code 🚨

High-risk code can easily blow up and is hard to test. We had severe bugs in the past. Be extra careful when changing these files, and have an extra careful look at these:

• .github/file-filters.yml

[philprime]

Fixed pure-ObjC link failure for Swift-defined public classes.

The Swift compiler emits @objcMembers classes under mangled ObjC runtime names (e.g. _TtC6Sentry14SentryFeedback), so pure-ObjC consumers of SentryObjC resolved nothing for _OBJC_CLASS_$_Sentry* at link time. macOS had hidden this via NSClassFromString fallbacks; iOS surfaced it in sentry-unreal's iOS BuildCookRun.

Added @compatibility_alias to each affected public header, dispatched on SWIFT_PACKAGE (SPM compiles under SentrySwift, Xcode under Sentry). Consumer TUs now rewrite the plain name to the mangled class that Sentry.framework already exports.

Covered: SentryAttribute, SentryEnvelope, SentryEnvelopeHeader, SentryEnvelopeItem, SentryExperimentalOptions, SentryFeedback, SentryLog, SentryLogger, SentryReplayOptions.

Out of scope:

• SentryMessage — pure ObjC, already exports _OBJC_CLASS_$_SentryMessage.
• SentryOptions — Swift class Options with @objc(SentryOptions), already exports the plain symbol.
• Category B (SentryEvent, SentryBreadcrumb, SentryScope, PrivateSentrySDKOnly, …) — follow-up issue.

Verified:

• make build-sentryobjc green.
• make build-sample-iOS-ObjectiveCpp-NoModules green (real no-modules consumer).
• Synthetic no-modules consumer .o now references _OBJC_CLASS_$__TtC6Sentry…<Name> (mangled) for all 9 aliased classes and links cleanly against the built SentryObjC.framework.