docs(feature-flags): Document Apple, Java, and Android APIs

docs/platforms/android/feature-flags/index.mdx

@@ -8,7 +8,7 @@ description: With Feature Flags, Sentry tracks feature flag evaluations in your
 
 ## Prerequisites
 
-* You have the <PlatformLink to="/">Android SDK installed</PlatformLink>.
+- You have version 8.42.0 or later of the <PlatformLink to="/">Android SDK installed</PlatformLink>.
 
 ## Enable Evaluation Tracking
 
@@ -17,12 +17,3 @@ description: With Feature Flags, Sentry tracks feature flag evaluations in your
 ## Enable Change Tracking
 
 <PlatformContent includePath="feature-flags/change-tracking-index" />
-
-
-
-
-
-
-
-
-

docs/platforms/apple/common/feature-flags/index.mdx

@@ -0,0 +1,19 @@
+---
+title: Set Up Feature Flags
+sidebar_title: Feature Flags
+sidebar_order: 5750
+sidebar_section: features
+description: With Feature Flags, Sentry tracks feature flag evaluations in your application, keeps an audit log of feature flag changes, and reports any suspicious updates that may have caused an error.
+---
+
+## Prerequisites
+
+- You have version 9.22.0 or later of the <PlatformLink to="/">Apple SDK installed</PlatformLink>.
+
+## Enable Evaluation Tracking
+
+<PlatformContent includePath="feature-flags/evaluation-tracking-index" />
+
+## Enable Change Tracking
+
+<PlatformContent includePath="feature-flags/change-tracking-index" />

docs/platforms/apple/common/features/index.mdx

@@ -70,6 +70,7 @@ All features listed below are **enabled by default** unless otherwise noted. Som
   - Outgoing HTTP requests
 - <PlatformLink to="/enriching-events/attachments">Attachments</PlatformLink> enrich your event by storing additional files, such as config or log files
 - <PlatformLink to="/data-management/debug-files/source-context">Source Context</PlatformLink> shows snippets of code around the location of stack frames
+- <PlatformLink to="/feature-flags">Feature Flags</PlatformLink> track feature flag evaluations on error events and active spans
 - <PlatformLink to="/guides/ios/enriching-events/viewhierarchy/">View Hierarchy</PlatformLink> and <PlatformLink to="/guides/ios/enriching-events/screenshots/">Screenshot</PlatformLink> attachments for errors (only available on iOS and tvOS)
 - <PlatformLink to="/user-feedback">User Feedback</PlatformLink> provides the ability to collect user information when an event occurs (User Feedback UI only available on iOS 13+)
 

docs/platforms/java/common/feature-flags/index.mdx

@@ -8,7 +8,7 @@ description: With Feature Flags, Sentry tracks feature flag evaluations in your
 
 ## Prerequisites
 
-* You have the <PlatformLink to="/">Java SDK installed</PlatformLink>.
+- You have version 8.42.0 or later of the <PlatformLink to="/">Java SDK installed</PlatformLink>.
 
 ## Enable Evaluation Tracking
 
@@ -17,12 +17,3 @@ description: With Feature Flags, Sentry tracks feature flag evaluations in your
 ## Enable Change Tracking
 
 <PlatformContent includePath="feature-flags/change-tracking-index" />
-
-
-
-
-
-
-
-
-

docs/product/issues/issue-details/feature-flags/index.mdx

@@ -34,8 +34,15 @@ This allows you to quickly find all errors where a specific flag evaluation and
 ### Set Up Evaluation Tracking
 
 To set up evaluation tracking, visit the SDK integration documentation for your platform:
-* [JavaScript](/platforms/javascript/feature-flags/)
-* [Python](/platforms/python/feature-flags/)
+
+- [Android](/platforms/android/feature-flags/)
+- [Apple](/platforms/apple/feature-flags/)
+- [Dart](/platforms/dart/feature-flags/)
+- [Java](/platforms/java/feature-flags/)
+- [JavaScript](/platforms/javascript/feature-flags/)
+- [PHP](/platforms/php/feature-flags/)
+- [Python](/platforms/python/feature-flags/)
+- [React Native](/platforms/react-native/feature-flags/)
 
 ### Flag Distribution View
 
@@ -63,4 +70,7 @@ Learn more about how to interact with feature flag insights within the Sentry UI
 
 ### Set Up Change Tracking
 
-<PlatformContent includePath="feature-flags/change-tracking-index" platform="_default"/>
+<PlatformContent
+  includePath="feature-flags/change-tracking-index"
+  platform="_default"
+/>

platform-includes/feature-flags/evaluation-tracking-index/android.mdx

@@ -3,23 +3,83 @@ If you use a third-party SDK to evaluate feature flags, you can enable a Sentry
 - <PlatformLink to="/integrations/launchdarkly">LaunchDarkly</PlatformLink>
 
 ### Generic API
-If you use an unsupported solution, you can use the generic API to manually track feature flag evaluations. These evaluations are held in memory and are sent to Sentry on error and transaction events. **At the moment, we only support boolean flag evaluations.**
+
+If you use an unsupported solution, use the generic API to manually track feature flag evaluations. The SDK stores each evaluation on the current scope. If a span or transaction is active, the SDK also records the evaluation on that active span or transaction. Only boolean flag evaluations are supported.
 
 ```java {3}
 import io.sentry.Sentry;
 
-Sentry.addFeatureFlag("feature_flag.test-flag", false);
+Sentry.addFeatureFlag("test-flag", false);
 Sentry.captureException(new Exception("Something went wrong!"));
 ```
 
 ```kotlin {3}
 import io.sentry.Sentry
 
-Sentry.addFeatureFlag("feature_flag.test-flag", false)
+Sentry.addFeatureFlag("test-flag", false)
 Sentry.captureException(Exception("Something went wrong!"))
 ```
 
 Go to your Sentry project and confirm that your error event has recorded the feature flag "test-flag" and its value "false".
 
+### Custom Scopes
+
+If you use a separate `IScopes` instance, add the feature flag evaluation to that instance. This updates its scope and active span or transaction, without changing the global `Sentry` scope:
+
+```java {1}
+scopes.addFeatureFlag("test-flag", false);
+scopes.captureException(new Exception("Something went wrong!"));
+```
+
+```kotlin {1}
+scopes.addFeatureFlag("test-flag", false)
+scopes.captureException(Exception("Something went wrong!"))
+```
+
+### Scope Callback
+
+Use a scope callback when the evaluation should apply to this capture's local scope instead of remaining on the current scope:
+
+```java {4}
+import io.sentry.Sentry;
+
+Sentry.captureException(new Exception("Something went wrong!"), scope -> {
+  scope.addFeatureFlag("test-flag", false);
+});
+```
+
+```kotlin {4}
+import io.sentry.Sentry
+
+Sentry.captureException(Exception("Something went wrong!")) { scope ->
+  scope.addFeatureFlag("test-flag", false)
+}
+```
+
+Feature flags added in a scope callback don't persist on the current scope. If a span or transaction is active, the SDK still records the evaluation on that active span or transaction.
+
+### Clear Feature Flags
+
+Clear feature flags when they no longer apply, such as after a user signs out or switches accounts:
+
+```java {4}
+import io.sentry.Sentry;
+
+Sentry.configureScope(scope -> {
+  scope.clearFeatureFlags();
+});
+```
+
+```kotlin {4}
+import io.sentry.Sentry
+
+Sentry.configureScope { scope ->
+  scope.clearFeatureFlags()
+}
+```
+
+`clearFeatureFlags()` removes evaluations only from the current scope. It doesn't affect parent or sibling scopes, or evaluations already recorded on an active span or transaction.
 
+Scope evaluations are attached to error and message events. By default, the current scope keeps the latest evaluation for up to 100 flag names. Re-evaluating a flag updates its stored value and makes it the most recent evaluation. When a scope forks, the child receives a copy of these evaluations, and changes to the copy don't affect the parent scope.
 
+Active spans and transactions record evaluations for up to 10 flag names as span attributes using the `flag.evaluation.<name>` key. Re-evaluating a recorded flag updates its value. After 10 flag names are recorded, evaluations for new flag names are ignored. Spans don't inherit evaluations from their parent span.

platform-includes/feature-flags/evaluation-tracking-index/apple.mdx

@@ -0,0 +1,75 @@
+If you use a third-party SDK to evaluate feature flags, use the generic API to manually track feature flag evaluations. The SDK stores each evaluation on the current scope. If a span or transaction is active, the SDK also records the evaluation on that active span or transaction. Only boolean flag evaluations are supported.
+
+### Generic API
+
+Call `SentrySDK.addFeatureFlag` after evaluating a feature flag:
+
+```swift {tabTitle:Swift} {mdExpandTabs}
+import Sentry
+
+SentrySDK.addFeatureFlag(name: "test-flag", result: false)
+SentrySDK.capture(error: error)
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+#import <SentryObjC/SentryObjC.h>
+
+[SentryObjCSDK addFeatureFlagWithName:@"test-flag" result:NO];
+[SentryObjCSDK captureError:error];
+```
+
+Go to your Sentry project and confirm that your error event has recorded the feature flag "test-flag" and its value "false".
+
+### Custom Hub
+
+If you use a custom hub, add the feature flag evaluation to that hub. This updates the custom hub's scope and active span or transaction, without changing the global `SentrySDK` scope:
+
+```swift {tabTitle:Swift} {mdExpandTabs}
+hub.addFeatureFlag(name: "test-flag", result: false)
+hub.capture(error: error)
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+[hub addFeatureFlagWithName:@"test-flag" result:NO];
+[hub captureError:error];
+```
+
+### Scope Callback
+
+Use a scope callback when the evaluation should apply to this capture's local scope instead of remaining on the current scope:
+
+```swift {tabTitle:Swift} {mdExpandTabs}
+SentrySDK.capture(error: error) { scope in
+    scope.addFeatureFlag(name: "test-flag", result: false)
+}
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+[SentryObjCSDK captureError:error withScopeBlock:^(SentryObjCScope * _Nonnull scope) {
+    [scope addFeatureFlagWithName:@"test-flag" result:NO];
+}];
+```
+
+Feature flags added in a scope callback don't persist on the current scope. If a span or transaction is active, the SDK still records the evaluation on that active span or transaction.
+
+### Clear Feature Flags
+
+Clear feature flags when they no longer apply, such as after a user signs out or switches accounts:
+
+```swift {tabTitle:Swift} {mdExpandTabs}
+SentrySDK.configureScope { scope in
+    scope.clearFeatureFlags()
+}
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+[SentryObjCSDK configureScope:^(SentryObjCScope * _Nonnull scope) {
+    [scope clearFeatureFlags];
+}];
+```
+
+`clearFeatureFlags()` removes evaluations from the current scope. It doesn't remove evaluations already recorded on an active span or transaction.
+
+Scope evaluations are attached to error and message events. The current scope keeps the latest evaluation for up to 100 flag names. Re-evaluating a flag updates its stored value and makes it the most recent evaluation.
+
+Active spans and transactions record evaluations for up to 10 flag names as span attributes using the `flag.evaluation.<name>` key. Re-evaluating a recorded flag updates its value. After 10 flag names are recorded, evaluations for new flag names are ignored. Spans don't inherit evaluations from their parent span.

platform-includes/feature-flags/evaluation-tracking-index/java.mdx

@@ -4,20 +4,83 @@ If you use a third-party SDK to evaluate feature flags, you can enable a Sentry
 - <PlatformLink to="/integrations/launchdarkly">LaunchDarkly</PlatformLink>
 
 ### Generic API
-If you use an unsupported solution, you can use the generic API to manually track feature flag evaluations. These evaluations are held in memory and are sent to Sentry on error and transaction events. **At the moment, we only support boolean flag evaluations.**
+
+If you use an unsupported solution, use the generic API to manually track feature flag evaluations. The SDK stores each evaluation on the current scope. If a span or transaction is active, the SDK also records the evaluation on that active span or transaction. Only boolean flag evaluations are supported.
 
 ```java {3}
 import io.sentry.Sentry;
 
-Sentry.addFeatureFlag("feature_flag.test-flag", false);
+Sentry.addFeatureFlag("test-flag", false);
 Sentry.captureException(new Exception("Something went wrong!"));
 ```
 
 ```kotlin {3}
 import io.sentry.Sentry
 
-Sentry.addFeatureFlag("feature_flag.test-flag", false)
+Sentry.addFeatureFlag("test-flag", false)
 Sentry.captureException(Exception("Something went wrong!"))
 ```
 
 Go to your Sentry project and confirm that your error event has recorded the feature flag "test-flag" and its value "false".
+
+### Custom Scopes
+
+If you use a separate `IScopes` instance, add the feature flag evaluation to that instance. This updates its scope and active span or transaction, without changing the global `Sentry` scope:
+
+```java {1}
+scopes.addFeatureFlag("test-flag", false);
+scopes.captureException(new Exception("Something went wrong!"));
+```
+
+```kotlin {1}
+scopes.addFeatureFlag("test-flag", false)
+scopes.captureException(Exception("Something went wrong!"))
+```
+
+### Scope Callback
+
+Use a scope callback when the evaluation should apply to this capture's local scope instead of remaining on the current scope:
+
+```java {4}
+import io.sentry.Sentry;
+
+Sentry.captureException(new Exception("Something went wrong!"), scope -> {
+  scope.addFeatureFlag("test-flag", false);
+});
+```
+
+```kotlin {4}
+import io.sentry.Sentry
+
+Sentry.captureException(Exception("Something went wrong!")) { scope ->
+  scope.addFeatureFlag("test-flag", false)
+}
+```
+
+Feature flags added in a scope callback don't persist on the current scope. If a span or transaction is active, the SDK still records the evaluation on that active span or transaction.
+
+### Clear Feature Flags
+
+Clear feature flags when they no longer apply, such as after a user signs out or switches accounts:
+
+```java {4}
+import io.sentry.Sentry;
+
+Sentry.configureScope(scope -> {
+  scope.clearFeatureFlags();
+});
+```
+
+```kotlin {4}
+import io.sentry.Sentry
+
+Sentry.configureScope { scope ->
+  scope.clearFeatureFlags()
+}
+```
+
+`clearFeatureFlags()` removes evaluations only from the current scope. It doesn't affect parent or sibling scopes, or evaluations already recorded on an active span or transaction.
+
+Scope evaluations are attached to error and message events. By default, the current scope keeps the latest evaluation for up to 100 flag names. Re-evaluating a flag updates its stored value and makes it the most recent evaluation. When a scope forks, the child receives a copy of these evaluations, and changes to the copy don't affect the parent scope.
+
+Active spans and transactions record evaluations for up to 10 flag names as span attributes using the `flag.evaluation.<name>` key. Re-evaluating a recorded flag updates its value. After 10 flag names are recorded, evaluations for new flag names are ignored. Spans don't inherit evaluations from their parent span.