From a18ee934cd5e243789bc26926996b0635666e29e Mon Sep 17 00:00:00 2001
From: Guilherme Souza <ogrsouza@gmail.com>
Date: Thu, 6 Aug 2026 05:37:47 -0300
Subject: [PATCH] docs(auth): handle incoming deep link URLs on Swift (#48774)

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Docs update.

## What is the current behavior?

The Swift tab in the [Native Mobile Deep Linking
guide](https://supabase.com/docs/guides/auth/native-mobile-deep-linking?platform=swift)
only covers registering a custom URL scheme (Info.plist config). Unlike
the React Native, Flutter, and Kotlin tabs, it never shows the runtime
code that actually consumes the incoming URL and completes the sign-in,
so a Swift developer following the guide is left without a working
implementation.

Linear:
[SDK-83](https://linear.app/supabase/issue/SDK-83/swift-improve-docs-on-how-to-handle-deep-link-url)

## What is the new behavior?

Added a "Handling the incoming URL" section to the Swift tab with:
- SwiftUI: `onOpenURL` calling `supabase.auth.handle(url)`
- UIKit app delegate lifecycle:
`application(_:didFinishLaunchingWithOptions:)` and
`application(_:open:options:)`
- UIKit scene delegate lifecycle: `scene(_:openURLContexts:)`
- A note pointing to `session(from:)` for callers that need the returned
`Session` or custom error handling

`handle(url)` and its usage patterns match the current `supabase-swift`
reference spec (`supabase_swift_v2.yml`) and source.

Also added `UIKit` to the docs spelling allowlist
(`supa-mdx-lint/Rule003Spelling.toml`) since it isn't in the dictionary.

## Additional context

`pnpm lint:mdx` passes on the changed file. `pnpm build:guides-markdown`
fails, but on a pre-existing unrelated issue (missing generated
`database-advisors.json`), not on this change.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added Swift guidance for handling authentication deep links in SwiftUI
and UIKit apps.
* Documented deep-link behavior during cold launches and scene-based URL
delivery.
* Clarified when to use `handle(_:)` and `session(from:)`, including
error-handling considerations.
* Updated the SwiftUI tutorial to pass authentication URLs directly to
the recommended handler.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../auth/native-mobile-deep-linking.mdx       | 64 +++++++++++++++++++
 supa-mdx-lint/Rule003Spelling.toml            |  1 +
 2 files changed, 65 insertions(+)

diff --git a/apps/docs/content/guides/auth/native-mobile-deep-linking.mdx b/apps/docs/content/guides/auth/native-mobile-deep-linking.mdx
index e08ddeb5567..b21b0f44898 100644
--- a/apps/docs/content/guides/auth/native-mobile-deep-linking.mdx
+++ b/apps/docs/content/guides/auth/native-mobile-deep-linking.mdx
@@ -345,6 +345,70 @@ With Deep Linking, you can configure this redirect to open a specific page. This
       </plist>
     ```
 
+### Handling the incoming URL
+
+    Once the OS opens your app via the redirect URL, pass that URL to `supabase.auth.handle(_:)` to complete the sign-in.
+
+    #### SwiftUI
+
+    Use the `onOpenURL` view modifier on your root view:
+
+    ```swift
+    SomeView()
+      .onOpenURL { url in
+        supabase.auth.handle(url)
+      }
+    ```
+
+    #### UIKit: App delegate
+
+    Forward the URL from `application(_:open:options:)`, and from `didFinishLaunchingWithOptions` if the app was launched cold via the link:
+
+    ```swift
+    func application(
+      _ application: UIApplication,
+      didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) -> Bool {
+      if let url = launchOptions?[.url] as? URL {
+        supabase.auth.handle(url)
+      }
+
+      return true
+    }
+
+    func application(
+      _ app: UIApplication,
+      open url: URL,
+      options: [UIApplication.OpenURLOptionsKey: Any]
+    ) -> Bool {
+      supabase.auth.handle(url)
+      return true
+    }
+    ```
+
+    #### UIKit: Scene delegate
+
+    Forward the URL from `SceneDelegate.swift`, handling both a cold launch (via `scene(_:willConnectTo:options:)`) and a URL received while the scene is already running (via `scene(_:openURLContexts:)`):
+
+    ```swift
+    func scene(
+      _ scene: UIScene,
+      willConnectTo session: UISceneSession,
+      options connectionOptions: UIScene.ConnectionOptions
+    ) {
+      for context in connectionOptions.urlContexts {
+        supabase.auth.handle(context.url)
+      }
+    }
+
+    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
+      guard let url = URLContexts.first?.url else { return }
+      supabase.auth.handle(url)
+    }
+    ```
+
+    `handle(_:)` is a convenience wrapper that calls `session(from:)` and logs any error. See the [Auth API reference](/docs/reference/swift/auth-api) for details, or call `session(from:)` directly if you need the returned `Session` or want control over error handling.
+
     <$Partial path="universal_links_apple.mdx" />
 
   </TabPanel>
diff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.toml
index 37ede15dfc7..5930697ca85 100644
--- a/supa-mdx-lint/Rule003Spelling.toml
+++ b/supa-mdx-lint/Rule003Spelling.toml
@@ -419,6 +419,7 @@ allow_list = [
     "Transformers.js",
     "tsquery",
     "Twilio",
+    "UIKit",
     "Undici",
     "UnionPay",
     "Unsplash",