feat: add dropped-event session update API

[buenaflor]

📜 Description

Expose SentrySDK.internal.envelope.updateSessionForDroppedEventNonTerminating(unhandled:) so hybrid SDKs can apply the same session side effects as captureNonTerminating when an error is dropped by sampling, without sending an envelope.

unhandled: true means mechanism.handled=false: the session stays ok with the same ID, error count increments, and it is flagged so a later endSession reports unhandled. unhandled: false only increments errors.

captureNonTerminating already calls this helper internally. Hybrid SDKs must not call both for the same event.

Stacked on #8654.

💡 Motivation and Context

Hybrid SDKs such as Flutter sample in Dart/JS before calling native. Unsampled errors never reach captureNonTerminating, so the native session is never updated. Native SentryClient updates the session before sampling; this API closes that gap.

Matches Android getsentry/sentry-java#5990, with Cocoa's unhandled parameter name instead of Android's crashed.

Depends on #8654 (captureNonTerminating). Do not merge this until that PR lands.

💚 How did you test it?

• Hub tests for handled/unhandled dropped-event session updates, persistence, and later endSession status
• Internal envelope API forwarding and integration tests
• ObjC wrapper smoke tests

📝 Checklist

You have to check all boxes before merging:

• I added tests to verify the changes.
• No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
• I updated the docs if needed.
• I updated the wizard if needed.
• Review from the native team if needed.
• No breaking change or entry added to the changelog.
• No breaking change for hybrid SDKs or communicated to hybrid SDKs.
• Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.
• If I added a new public API, I also added it to the SentryObjC wrapper.

[github-actions]

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

Generated by 🚫 dangerJS against 979477c

[sentry]

📲 Install Builds

iOS

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

⚙️ sentry-cocoa Build Distribution Settings

[github-actions]

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	1216.28 ms	1249.49 ms	33.21 ms
Size	24.14 KiB	1.32 MiB	1.29 MiB

Baseline results on branch: main

Startup times

Revision	Plain	With Sentry	Diff
8ed81c1	1227.47 ms	1249.24 ms	21.77 ms
27850be	1222.65 ms	1254.23 ms	31.58 ms
030ffb6	1231.92 ms	1262.21 ms	30.30 ms
e329fff	1195.06 ms	1225.21 ms	30.14 ms
377c3a4	1214.89 ms	1256.24 ms	41.35 ms
cc1ad62	1223.79 ms	1239.35 ms	15.56 ms
613edc2	1221.32 ms	1253.88 ms	32.56 ms
ff56ae9	1222.51 ms	1257.87 ms	35.36 ms
4455127	1235.75 ms	1267.39 ms	31.64 ms
230cc86	1225.33 ms	1258.67 ms	33.34 ms

App size

Revision	Plain	With Sentry	Diff
8ed81c1	24.14 KiB	1.23 MiB	1.21 MiB
27850be	24.14 KiB	1.18 MiB	1.16 MiB
030ffb6	24.14 KiB	1.26 MiB	1.23 MiB
e329fff	24.14 KiB	1.26 MiB	1.23 MiB
377c3a4	24.14 KiB	1.25 MiB	1.23 MiB
cc1ad62	24.14 KiB	1.24 MiB	1.21 MiB
613edc2	24.14 KiB	1.22 MiB	1.20 MiB
ff56ae9	24.14 KiB	1.22 MiB	1.20 MiB
4455127	24.14 KiB	1.24 MiB	1.21 MiB
230cc86	24.14 KiB	1.25 MiB	1.23 MiB

Previous results on branch: feat/dropped-event-session-update

Startup times

Revision	Plain	With Sentry	Diff
ff59095	1204.92 ms	1239.00 ms	34.08 ms

App size

Revision	Plain	With Sentry	Diff
ff59095	24.14 KiB	1.31 MiB	1.29 MiB

[Copilot]

🟢 Approval recommended

The change is narrowly scoped with updated Swift/ObjC surfaces and tests; remaining feedback is a minor internal locking/maintainability improvement.

Pull request overview

Exposes a new hybrid-facing SPI API (SentrySDK.internal.envelope.updateSessionForDroppedEventNonTerminating(unhandled:)) to apply the same non-terminating session side effects as captureNonTerminating, but without sending an envelope—so hybrid SDKs can still update native session state when an error is dropped by sampling.

Changes:

• Add Swift SPI forwarding on SentrySDK.internal.envelope plus dependency-container plumbing to reach the current hub.
• Add Objective-C wrapper surface (SentryObjCInternalEnvelopeApi) and update API snapshot JSONs.
• Add unit/integration tests and update internal API documentation/changelog.

File summaries

File	Description
Tests/SentryTests/SentryHubTests.swift	Adds hub-level unit tests for handled/unhandled/no-session behaviors, asserting no envelope capture.
Tests/SentryTests/Integrations/Performance/Network/SentryNetworkTrackerTests.swift	Updates test hub stub to satisfy the expanded Hub protocol.
Tests/SentryTests/HybridSDK/SentryInternalScreenApiTests.swift	Updates hybrid screen API test mock to satisfy Hub protocol.
Tests/SentryTests/HybridSDK/SentryInternalScopeApiTests.swift	Updates hybrid scope API test mock to satisfy Hub protocol.
Tests/SentryTests/HybridSDK/SentryInternalEnvelopeApiTests.swift	Adds forwarding test ensuring the SPI method delegates to Hub without capturing envelopes.
Tests/SentryTests/HybridSDK/SentryInternalEnvelopeApiIntegrationTests.swift	Adds integration coverage for unhandled dropped-event session updates through SentrySDK.internal.envelope.
Tests/SentryObjCTests/SentryObjCInternalEnvelopeApiIntegrationTests.m	Adds ObjC smoke test ensuring the new ObjC wrapper method is callable.
Sources/Swift/SentryDependencyContainer.swift	Extends Hub protocol + default implementation to forward the new method to the current hub.
Sources/Swift/HybridSDK/SentryInternalEnvelopeApi.swift	Adds SPI method + docs clarifying when to use vs captureNonTerminating(_:).
Sources/SentryObjCCompat/SentryObjCInternalEnvelopeApi.swift	Exposes the SPI method through the ObjC-compat wrapper.
Sources/SentryObjC/Public/SentryObjCInternalEnvelopeApi.h	Adds public ObjC header documentation and method declaration.
Sources/Sentry/SentryHub.m	Implements the session update helper used by both capture and “dropped by sampling” flows.
Sources/Sentry/include/SentryHub+SwiftPrivate.h	Exposes the hub method to Swift with a Swift-friendly name/signature.
sdk_api_objc.json	Records the new ObjC API surface in the public API snapshot.
sdk_api_objc_v10.json	Records the new ObjC API surface in the v10 public API snapshot.
develop-docs/SENTRY-INTERNAL-API.md	Documents the new internal envelope SPI method and when to use it.
CHANGELOG.md	Adds a changelog entry describing the new hybrid SPI method.

Review details

• Files reviewed: 17/17 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[itaybre]

LGTM