docs(apple): Document extendAppLaunch API for standalone app starts

docs/platforms/apple/common/features/experimental-features.mdx

@@ -32,6 +32,8 @@ Enable <PlatformLink to="/profiling/#continuous-profiling">Continuous Profiling<
 
 Enable <PlatformLink to="/tracing/instrumentation/automatic-instrumentation/#standalone-app-start-tracing">`enableStandaloneAppStartTracing`</PlatformLink> to send app start data as a dedicated transaction instead of attaching it to the first UIViewController transaction. You can use a custom <PlatformLink to="/configuration/options/#tracesSampler">`tracesSampler`</PlatformLink> to set a dedicated sample rate for app start transactions by checking for the `app.start` operation.
 
+You can also <PlatformLink to="/tracing/instrumentation/automatic-instrumentation/#extending-the-app-launch">extend the app launch</PlatformLink> beyond `didFinishLaunchingNotification` notification to include post-launch work like initial data loading using `SentrySDK.extendAppLaunch()` _(since 9.15.0)_. The method returns the extended app launch span, which you can use to add child spans that break down the extended launch period. Call `finish()` on the returned span when your app is fully ready.
+
 ## Crash & Error Handling
 
 ### Persisting Traces When Crashing

docs/platforms/apple/common/tracing/instrumentation/automatic-instrumentation.mdx

@@ -267,6 +267,132 @@ SentrySDK.start { options in
 }];
 ```
 
+#### Extending the App Launch
+
+<Alert>
+
+Available since [version 9.15.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#9150).
+
+</Alert>
+
+By default, the standalone app start transaction ends when the `didFinishLaunchingNotification` notification is posted (after `application(_:didFinishLaunchingWithOptions:)` function returns). If your app performs additional work after that — such as loading initial data from a server or database — you can extend the app start transaction to include that time by calling `SentrySDK.extendAppLaunch()`.
+
+Call `extendAppLaunch()` after `SentrySDK.start(options:)` and before `application(_:didFinishLaunchingWithOptions:)` returns, so the SDK doesn't automatically finish the app start transaction. The method returns the extended app launch span, which you can use to add child spans that break down the extended launch period. Call `finish()` on the returned span when your app is fully ready. This adds an "Extended App Start" child span covering the time between the two calls.
+
+![Extended App Start](./img/extended-app-start.png)
+
+**UIKit:**
+
+```swift {tabTitle:Swift}
+import Sentry
+
+class AppDelegate: UIResponder, UIApplicationDelegate {
+    var appStartSpan: (any Span)?
+
+    func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) -> Bool {
+        SentrySDK.start { options in
+            options.dsn = "___PUBLIC_DSN___"
+            options.experimental.enableStandaloneAppStartTracing = true
+        }
+        appStartSpan = SentrySDK.extendAppLaunch()
+
+        let configSpan = appStartSpan?.startChild(
+            operation: "app.init",
+            description: "fetch remote config"
+        )
+        fetchRemoteConfig()
+        configSpan?.finish()
+
+        return true
+    }
+
+    // Later, when your app is fully ready:
+    func onDataLoaded() {
+        appStartSpan?.finish()
+    }
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+@interface AppDelegate ()
+@property (nonatomic, strong) id<SentrySpan> appStartSpan;
+@end
+
+- (BOOL)application:(UIApplication *)application
+    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+    [SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+        options.dsn = @"___PUBLIC_DSN___";
+        options.experimental.enableStandaloneAppStartTracing = YES;
+    }];
+    self.appStartSpan = [SentrySDK extendAppLaunch];
+
+    id<SentrySpan> configSpan = [self.appStartSpan startChildWithOperation:@"app.init"
+                                                               description:@"fetch remote config"];
+    [self fetchRemoteConfig];
+    [configSpan finish];
+
+    return YES;
+}
+
+// Later, when your app is fully ready:
+- (void)onDataLoaded {
+    [self.appStartSpan finish];
+}
+```
+
+You can also call `SentrySDK.finishExtendedAppLaunch()` instead of `finish()` on the span — both are equivalent.
+
+**SwiftUI:**
+
+```swift {tabTitle:Swift}
+import Sentry
+
+@main
+struct MyApp: App {
+    var appStartSpan: (any Span)?
+
+    init() {
+        SentrySDK.start { options in
+            options.dsn = "___PUBLIC_DSN___"
+            options.experimental.enableStandaloneAppStartTracing = true
+        }
+        appStartSpan = SentrySDK.extendAppLaunch()
+
+        let configSpan = appStartSpan?.startChild(
+            operation: "app.init",
+            description: "load configuration"
+        )
+        loadConfiguration()
+        configSpan?.finish()
+    }
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView(onReady: {
+                appStartSpan?.finish()
+            })
+        }
+    }
+}
+```
+
+<Alert>
+
+`extendAppLaunch()` returns the extended app launch span, or `nil` if the SDK is not started or the app start transaction was already created. The return value is `@discardableResult`, so existing code that doesn't use the return value will continue to work.
+
+`extendAppLaunch()` must be called before the `didFinishLaunchingNotification` notification is posted. If called after the app start transaction has already been created, it returns `nil` and the SDK logs a warning.
+
+Calling `finishExtendedAppLaunch()` without a prior `extendAppLaunch()` call, or after the extended launch was already finished, is a no-op.
+
+These APIs are only available on iOS, tvOS, and visionOS, and require `enableStandaloneAppStartTracing` to be enabled.
+
+</Alert>
+
 ## Slow and Frozen Frames
 
 This feature is available for iOS, tvOS, and Mac Catalyst.