feat(apple): User interaction instrumentation

src/platforms/apple/common/performance/instrumentation/automatic-instrumentation.mdx

@@ -164,6 +164,67 @@ SentrySDK.start { options in
 }];
 ```
 
+## User Interaction Instrumentation
+
+<Alert level="info" title="Important">
+
+This is an experimental feature and requires an opt-in. Experimental features are still a work-in-progress and may have bugs. We recognize the irony.
+
+</Alert>
+
+The UI instrumentation, once enabled, captures transactions for clicks. The UI instrumentation is disabled by default, but you can enable it by setting:
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.enableUserInteractionTracing = true
+}
+```
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.enableUserInteractionTracing = YES;
+}];
+```
+
+The SDK composes the transaction name out of the host `UIViewController` and the method that the `UIView` is calling; for example, `YourApp_LoginUIViewController.loginButton`. The transaction operation is set to `ui.action` plus the interaction type `click`. The transaction finishes automatically after it reaches the specified [idleTimeout](/platforms/android/configuration/options/#idle-timeout) and all of its child spans are finished. The `idleTimeoout` defaults to `3000` milliseconds (three seconds).
+
+<Note>
+
+If the UI transaction has idled, but didn't have any child spans added, it will be dropped.
+
+</Note>
+
+The SDK binds user interaction transactions to the `Scope` automatically if there's no other transaction set. Because of that, you can create spans using manual instrumentation, and those spans will be automatically associated with the running UI transaction.
+
+```Swift
+import Sentry
+
+func loadUserDataOnClick() {
+    let span = SentrySDK.span
+    let innerSpan = span?.startChild(operation: "loadUserData")
+    // omitted code
+    innerSpan?.finish()
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+- (void)loadUserDataOnClick {
+    id<SentrySpan> span = SentrySDK.span;
+    id<SentrySpan> innerSpan = [span startChildWithOperation:@"loadUserData"];
+    // omitted code
+    [innerSpan finish];
+}
+```
+
+When the user interaction transaction is not finished yet, but the user makes a new interaction, or the SDK starts a new UIViewController transaction, the SDK automatically finishes the previous user interaction transaction. This is because only one transaction can be bound to the scope at a time. However, if the same view has been interacted with (for example, a `UIButton` was clicked again within the `idleTimeout` window), the idle timer will be reset and the transaction duration will be extended with the `idleTimeout` value.
+
 ## Opt Out
 
 You can opt out of UIViewController, App Start, Slow and Frozen Frames, and HTTP Instrumentation using options: