docs(apple): Add Hints API documentation

docs/platforms/apple/common/configuration/filtering.mdx

@@ -16,12 +16,106 @@ Configure your SDK to filter error events by using the <PlatformIdentifier name=
 
 ### Using <PlatformIdentifier name="before-send" />
 
-All Sentry SDKs support the <PlatformIdentifier name="before-send" /> callback method. Because it's called immediately before the event is sent to the server, this is your last chance to decide not to send data or to edit it. <PlatformIdentifier name="before-send" /> receives the event object as a parameter, which you can use to either modify the event’s data or drop it completely by returning `null`, based on custom logic and the data available on the event.
+All Sentry SDKs support the <PlatformIdentifier name="before-send" /> callback method. Because it's called immediately before the event is sent to the server, this is your last chance to decide not to send data or to edit it. <PlatformIdentifier name="before-send" /> receives the event object as a parameter, which you can use to either modify the event's data or drop it completely by returning `null`, based on custom logic and the data available on the event.
 
 <PlatformContent includePath="configuration/before-send/" />
 
 Note also that breadcrumbs can be filtered, as discussed in [our Breadcrumbs documentation](/product/issues/issue-details/breadcrumbs/).
 
+#### Event Hints
+
+The `beforeSendWithHint` callback is passed both the `event` and a second argument, `hint`, that holds one or more hints.
+
+Typically, a `hint` holds the original exception so that additional data can be extracted or grouping is affected. In this example, the event is dropped if the original error belongs to a domain you want to ignore:
+
+<PlatformContent includePath="configuration/before-send-hint" />
+
+<Alert>
+
+Hints are available in Sentry Cocoa SDK version `9.28.0` and above.
+
+`beforeSendWithHint` and `beforeBreadcrumbWithHint` are transitional APIs. In the next major version, the hint parameter will be added to `beforeSend` and `beforeBreadcrumb` directly.
+
+</Alert>
+
+When the SDK creates an event or breadcrumb for transmission, that transmission is typically created from some sort of source object. For instance, an error event is typically created from an `NSError` or `NSException` instance. For better customization, the SDK sends these objects to certain callbacks (`beforeSendWithHint`, `beforeBreadcrumbWithHint`).
+
+### Using Hints
+
+Hints are available in two places:
+
+1. `beforeSendWithHint` / `beforeBreadcrumbWithHint`
+2. The `hint` parameter on `SentrySDK.capture` methods
+
+Event and breadcrumb `hints` are objects containing various information used to put together an event or a breadcrumb. Typically `hints` hold the original exception so that additional data can be extracted or grouping can be affected.
+
+For events, hints contain properties such as `originalError`, `originalException`, and `attachments` (the list of attachments that will be sent with the event, including screenshots and view hierarchies when enabled).
+
+For breadcrumbs, hints contain the `urlRequest` and `httpResponse` when the breadcrumb originates from a network operation.
+
+#### Hints for Events
+
+`originalError`
+
+The original `Error` (typically an `NSError`) that caused the Sentry SDK to create the event. This is useful for changing how the Sentry SDK groups events or to extract additional information.
+
+`originalException`
+
+The original `NSException` that caused the Sentry SDK to create the event.
+
+`attachments`
+
+The attachments that will be sent alongside the event. The SDK pre-populates this list (including screenshots and view hierarchies when enabled) before the callback runs. You can add or remove attachments by modifying this array.
+
+#### Hints for Breadcrumbs
+
+<PlatformContent includePath="configuration/breadcrumb-hints" />
+
+#### Custom Hint Values
+
+You can store arbitrary key-value data on a hint using `setHintValue(_:forKey:)` and `hintValue(forKey:)`. This is useful when passing hints through the capture methods:
+
+```swift {tabTitle:Swift}
+let hint = Hint()
+hint.setHintValue("custom-data", forKey: "myKey")
+
+SentrySDK.capture(event: event, hint: hint)
+```
+
+```objc {tabTitle:Objective-C}
+SentryHint *hint = [[SentryHint alloc] init];
+[hint setHintValue:@"custom-data" forKey:@"myKey"];
+
+[SentrySDK captureEvent:event withScope:SentrySDK.currentHub.scope hint:hint];
+```
+
+#### Passing Hints to Capture Methods
+
+All public capture methods on `SentrySDK` accept an optional `hint` parameter. The hint is passed through to `beforeSendWithHint`, allowing you to forward contextual information from the capture site to the callback:
+
+```swift {tabTitle:Swift}
+import Sentry
+
+// Capture an error with a hint
+let hint = Hint(error: myError)
+hint.setHintValue("checkout-flow", forKey: "source")
+SentrySDK.capture(error: myError, hint: hint)
+
+// Capture an event with a hint
+SentrySDK.capture(event: event, hint: hint)
+
+// Capture an exception with a hint
+SentrySDK.capture(exception: myException, hint: Hint(exception: myException))
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+// Capture an error with a hint
+SentryHint *hint = [[SentryHint alloc] initWithError:myError];
+[hint setHintValue:@"checkout-flow" forKey:@"source"];
+[SentrySDK captureError:myError withScope:SentrySDK.currentHub.scope hint:hint];
+```
 
 ## Filtering Spans
 

docs/platforms/apple/common/configuration/options.mdx

@@ -419,10 +419,30 @@ By the time <PlatformIdentifier name="beforeSend" /> is executed, all scope data
 
 </SdkOption>
 
+<SdkOption name="beforeSendWithHint" type="function">
+
+This function is called with an SDK-specific message or error event object and a `Hint` object, and can return a modified event object, or `null` to skip reporting the event. If set, this takes precedence over `beforeSend`.
+
+The `Hint` provides access to the raw source material that produced the event, such as the original `Error` or `NSException`, along with the list of attachments that will be sent with the event. See <PlatformLink to="/configuration/filtering/#using-hints">Using Hints</PlatformLink> for details.
+
+_Available since SDK version `9.28.0`. This is a transitional API: in the next major version, the hint parameter will be added to `beforeSend` directly._
+
+</SdkOption>
+
 <SdkOption name="beforeBreadcrumb" type="function">
 
 This function is called with an SDK-specific breadcrumb object before the breadcrumb is added to the scope. When nothing is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the first argument, which contains the breadcrumb object.
-The callback typically gets a second argument (called a "hint") which contains the original object from which the breadcrumb was created to further customize what the breadcrumb should look like.
+To access additional context about the breadcrumb's origin (such as the original HTTP request or response), use `beforeBreadcrumbWithHint` instead.
+
+</SdkOption>
+
+<SdkOption name="beforeBreadcrumbWithHint" type="function">
+
+This function is called with an SDK-specific breadcrumb object and a `Hint` object before the breadcrumb is added to the scope. If set, this takes precedence over `beforeBreadcrumb`.
+
+For network breadcrumbs, the `Hint` contains the original `URLRequest` and `HTTPURLResponse`. See <PlatformLink to="/configuration/filtering/#using-hints">Using Hints</PlatformLink> for details.
+
+_Available since SDK version `9.28.0`. This is a transitional API: in the next major version, the hint parameter will be added to `beforeBreadcrumb` directly._
 
 </SdkOption>
 

docs/platforms/apple/common/enriching-events/breadcrumbs/index.mdx

@@ -31,6 +31,8 @@ Manually record a breadcrumb:
 
 SDKs allow you to customize breadcrumbs through the <PlatformIdentifier name="before-breadcrumb" /> hook.
 
-This hook is passed an already assembled breadcrumb and, in some SDKs, an optional hint. The function can modify the breadcrumb or decide to discard it entirely by returning `nil`:
+This hook is passed an already assembled breadcrumb. The function can modify the breadcrumb or decide to discard it entirely by returning `nil`:
 
 <PlatformContent includePath="enriching-events/breadcrumbs/before-breadcrumb" />
+
+To access additional context about the breadcrumb's origin — such as the original `URLRequest` or `HTTPURLResponse` for network breadcrumbs — use `beforeBreadcrumbWithHint` instead. See <PlatformLink to="/configuration/filtering/#using-hints">Using Hints</PlatformLink> for details and examples.

platform-includes/configuration/before-send-hint/apple.mdx

@@ -0,0 +1,53 @@
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.beforeSendWithHint = { event, hint in
+        // Access the original error that triggered this event
+        if let error = hint.originalError as NSError?,
+           error.domain == "com.example.ignorable" {
+            return nil // Drop the event
+        }
+
+        // Add or remove attachments before they are sent
+        hint.attachments = hint.attachments.filter { $0.filename != "sensitive.txt" }
+
+        return event
+    }
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.beforeSendWithHint = ^SentryEvent * _Nullable(SentryEvent * _Nonnull event, SentryHint * _Nonnull hint) {
+        // Access the original error that triggered this event
+        NSError *error = hint.originalError;
+        if ([error.domain isEqualToString:@"com.example.ignorable"]) {
+            return nil; // Drop the event
+        }
+
+        return event;
+    };
+}];
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+#import <SentryObjC/SentryObjC.h>
+
+[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.beforeSendWithHint = ^SentryObjCEvent * _Nullable(SentryObjCEvent * _Nonnull event, SentryObjCHint * _Nonnull hint) {
+        // Access the original error that triggered this event
+        NSError *error = hint.originalError;
+        if ([error.domain isEqualToString:@"com.example.ignorable"]) {
+            return nil; // Drop the event
+        }
+
+        return event;
+    };
+}];
+```

platform-includes/configuration/breadcrumb-hints/apple.mdx

@@ -0,0 +1,59 @@
+`urlRequest`
+
+For breadcrumbs created from HTTP network operations, the hint contains the original `URLRequest`. This can be used to filter breadcrumbs by URL or extract additional request data.
+
+`httpResponse`
+
+For breadcrumbs created from HTTP network operations, the hint contains the `HTTPURLResponse`. This can be used to inspect status codes, headers, or other response metadata.
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.beforeBreadcrumbWithHint = { breadcrumb, hint in
+        // Access the original HTTP request for network breadcrumbs
+        if let request = hint.urlRequest {
+            if request.url?.host == "internal-api.example.com" {
+                return nil // Drop breadcrumbs for internal API calls
+            }
+        }
+
+        return breadcrumb
+    }
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.beforeBreadcrumbWithHint = ^SentryBreadcrumb * _Nullable(SentryBreadcrumb * _Nonnull breadcrumb, SentryHint * _Nonnull hint) {
+        // Access the original HTTP request for network breadcrumbs
+        NSURLRequest *request = hint.urlRequest;
+        if ([request.URL.host isEqualToString:@"internal-api.example.com"]) {
+            return nil; // Drop breadcrumbs for internal API calls
+        }
+
+        return breadcrumb;
+    };
+}];
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+#import <SentryObjC/SentryObjC.h>
+
+[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.beforeBreadcrumbWithHint = ^SentryObjCBreadcrumb * _Nullable(SentryObjCBreadcrumb * _Nonnull breadcrumb, SentryObjCHint * _Nonnull hint) {
+        // Access the original HTTP request for network breadcrumbs
+        NSURLRequest *request = hint.urlRequest;
+        if ([request.URL.host isEqualToString:@"internal-api.example.com"]) {
+            return nil; // Drop breadcrumbs for internal API calls
+        }
+
+        return breadcrumb;
+    };
+}];
+```