欢迎使用 @frontegg/ios Swift SDK！此 SDK 提供了一种无缝的方式，将 Frontegg 的身份验证和用户管理功能集成到您的 iOS 应用程序中。

• 项目要求
  • 支持的语言
  • 支持的平台
• 快速入门
  • 准备 Frontegg 工作区
  • 设置托管登录
  • 将 frontegg 包添加到项目
  • 创建 Frontegg plist 文件
  • SwiftUI 集成
    • 添加 Frontegg 包装器
    • 添加自定义加载屏幕
  • UIKit 集成
    • 添加 Frontegg UIKit 包装器
    • 添加自定义 UIKit 加载屏幕（即将推出）
  • 嵌入式 Webview 与 ASWebAuthenticationSession
  • 配置 iOS 关联域名
  • 多应用支持
  • 多区域支持
  • 使用 ASWebAuthenticationSession 登录
  • Passkeys 身份验证
  • FronteggAuth 方法

Swift: 现在支持的最低 Swift 版本为 5.3。

支持主要平台版本，从

• iOS > 14 开始

导航到 Frontegg Portal Settings，如果您没有应用程序，请在注册后按照集成步骤操作。从 Frontegg Portal Domain 复制 FronteggDomain 以供后续步骤使用

• 导航到 Login Method Settings
• 切换托管登录方法
• 添加 {{IOS_BUNDLE_IDENTIFIER}}://{{FRONTEGG_BASE_URL}}/ios/oauth/callback
• 添加 {{FRONTEGG_BASE_URL}}/oauth/authorize
• 将 IOS_BUNDLE_IDENTIFIER 替换为您的应用程序标识符
• 将 FRONTEGG_BASE_URL 替换为您的 frontegg 基本 URL

• 打开您的项目
• 选择 File -> Add Packages
• 在搜索字段中输入 https://github.com/frontegg/frontegg-ios-swift
• 按 Add Package

要设置您的 SwiftUI 应用程序以与 Frontegg 通信，您必须在您的根项目目录下创建一个名为 Frontegg.plist 的新文件，此文件将存储供 Frontegg SDK 使用的变量的值

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN">
<plist version="1.0">
    <dict>
        <key>baseUrl</key>
        <string>https://[DOMAIN_HOST_FROM_PREVIOUS_STEP]</string>
        <key>clientId</key>
        <string>[CLIENT_ID_FROM_PREVIOUS_STEP]</string>
    </dict>
</plist>

• 添加 Frontegg 包装器

  • 要使用 Frontegg SDK，您必须使用 FronteggWrapper 包装您的 Application Scene

    import SwiftUI
    import FronteggSwift
    
    @main
    struct demoApp: App {
        var body: some Scene {
            WindowGroup {
                FronteggWrapper {
                    MyApp()
                }
            }
        }
    }

  • 修改 MyApp.swift 文件以在用户通过身份验证时呈现内容

    1. 添加 @EnvironmentObject var fronteggAuth: FronteggAuth 到
    2. 根据 fronteggAuth.isAuthenticated 呈现您的整个应用程序

    struct MyApp: View {
      @EnvironmentObject var fronteggAuth: FronteggAuth
      
      var body: some View {
        ZStack {
          if fronteggAuth.isAuthenticated {
            [YOU APPLICATION TABS / ROUTER / VIEWS]
          } else  {
            
            Button {
                fronteggAuth.login()
            } label: {
                Text("Login Button")
            }
          }
        }
      }
    }

  • 添加自定义加载屏幕

  要使用您自己的 LoadingView / SplashScreen

  • 在单独的文件中构建您的加载视图
  • 将 LoadingView 作为 AnyView 传递给 FronteggWrapper

    FronteggWrapper(loaderView: AnyView(LoaderView())) {
      MyApp()
    }

• 添加 Frontegg UIKit 包装器

  • 将 Frontegg 添加到 AppDelegate 文件

      func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
          // Override point for customization after application launch.
    
          FronteggApp.shared.didFinishLaunchingWithOptions()
        
          return true
      }

  • 创建 AuthenticationController 类，该类扩展自 FronteggSwift 中的 AbstractFronteggController

      //
      //  AuthenticationController.swift
      //
      
      import UIKit
      import FronteggSwift
      
      class AuthenticationController: AbstractFronteggController {
      
          override func navigateToAuthenticated(){
              // This function will be called when the user is authenticated
              // to navigate your application to the authenticated screen
              
              let mainStoryboard: UIStoryboard = UIStoryboard(name: "Main", bundle: nil)
              
              // TODO: Set Storyboard ID 'authenticatedScreen' for your authenticated screen
              let viewController = mainStoryboard.instantiateViewController(withIdentifier: "authenticatedScreen")
              self.view.window?.rootViewController = viewController
              self.view.window?.makeKeyAndVisible()
          }
      
      }

  • 为 AuthenticationController 创建一个新的 ViewController

    1. 将 viewController 的类更改为 AuthenticationController
    2. 将 Storyboard ID 设置为 fronteggController
    3. 确保视图控制器是初始视图控制器

  • 为 Frontegg 通用链接设置 SceneDelegate

      func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
          if let url = URLContexts.first?.url,
              url.startAccessingSecurityScopedResource() {
              defer  {
                  url.stopAccessingSecurityScopedResource()
              }
              if url.absoluteString.hasPrefix( FronteggApp.shared.baseUrl ) {
                  if(FronteggApp.shared.auth.handleOpenUrl(url)){
                      // Display your own Authentication View Controller
                      // to handle after oauth callback
                      window?.rootViewController = AuthenticationController()
                      window?.makeKeyAndVisible()
                      return
                  }
              }
              
          }
      }
      func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
          if let url = userActivity.webpageURL {
              if(FronteggApp.shared.auth.handleOpenUrl(url)){
                  // Display your own Authentication View Controller
                  // to handle after oauth callback
                  window?.rootViewController = AuthenticationController()
                  window?.makeKeyAndVisible()
                  return
              }
          }
      }

  • 通过 FronteggApp.shared.auth 访问经过身份验证的用户

        
      //
      //  ExampleViewController.swift
      //
      
      import UIKit
      import SwiftUI
      import FronteggSwift
      import Combine
      
      
      class ExampleViewController: UIViewController {
      
          // Label to display logged in user's email
          @IBOutlet weak var label: UILabel!
          var showLoader: Boolean = true
          
          override func viewDidLoad() {
              super.viewDidLoad()
              // Do any additional setup after loading the view.
              
              // subscribe to isAuthenticated and navigate to login page
              // if the user is not authenticated
    
              let fronteggAuth = FronteggApp.shared.auth
              self.label.text = fronteggAuth.user?.email ?? "Unknown"
          }
           
          @IBAction func logoutButton (){
              FronteggApp.shared.auth.logout() { _ in
                  window?.rootViewController = AuthenticationController()
                  window?.makeKeyAndVisible()  
              }
          }
    
      }
      

Frontegg SDK 支持两种身份验证方法

• 嵌入式 Webview
• ASWebAuthenticationSession

默认情况下，Frontegg SDK 将使用嵌入式 Webview，要使用 ASWebAuthenticationSession，您必须在 Frontegg.plist 文件中将 embeddedMode 设置为 NO

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN">
<plist version="1.0">
    <dict>
        <key>baseUrl</key>
        <string>https://[DOMAIN_HOST_FROM_PREVIOUS_STEP]</string>
        <key>clientId</key>
        <string>[CLIENT_ID_FROM_PREVIOUS_STEP]</string>

        <!-- START -->
        <key>embeddedMode</key>
        <true/>
        <!-- END -->
    </dict>
</plist>

配置您的 iOS 关联域名是 Magic Link 身份验证/重置密码/激活帐户所必需的。

为了将您的 iOS 关联域名添加到您的 Frontegg 应用程序，您需要在每个集成的 Frontegg 环境中更新您希望与该环境一起使用的 iOS 关联域名。向 https://api.frontegg.com/vendors/resources/associated-domains/v1/ios 发送一个 POST 请求，并附带以下有效负载

{
    “appId”:[YOUR_ASSOCIATED_DOMAIN]
}

为了使用我们的 API，请按照本指南生成供应商令牌。

接下来，您需要将您的关联域名添加到您的 iOS 应用程序。为此，请按照以下步骤操作

1. 在 Xcode 中打开您的项目。
2. 在项目导航器中选择您的项目。
3. 选择您的目标。
4. 选择 Signing & Capabilities 选项卡。
5. 展开 Associated Domains 部分。
6. 单击 + 按钮。
7. 以 applinks:[YOUR_ASSOCIATED_DOMAIN] 格式输入您的关联域名。
8. 以 webcredentials:[YOUR_ASSOCIATED_DOMAIN] 格式输入您的关联域名。
9. 单击 Done。

[YOUR_ASSOCIATED_DOMAIN] 是您希望与您的 iOS 应用程序一起使用的关联域名。例如，如果您想使用 https://example.com 作为您的关联域名，您将输入 applinks:example.com 和 webcredentials:example.com。

本指南概述了配置您的 iOS 应用程序以支持多个应用程序的步骤。

将 applicationId 添加到 Frontegg.plist 文件

<plist version="1.0">
  <dict>
    <key>applicationId</key>  
    <string>your-application-id-uuid</string>
    <key>baseUrl</key>
    <string>https://your-domain.fronteg.com</string>
    <key>clientId</key>
    <string>your-client-id-uuid</string>
  </dict>
</plist>

本指南概述了配置您的 iOS 应用程序以支持多个区域的步骤。

首先，调整您的 Frontegg.plist 文件以处理多个区域

修改:

• 删除现有的 baseUrl 和 clientId 键。
• 添加一个名为 regions 的新数组键。此数组将保存每个区域的字典。

Frontegg.plist 示例结构

<key>regions</key>
<array>
<dict>
    <key>key</key>
    <string>us-region</string>
    <key>baseUrl</key>
    <string>https://us-region-api.frontegg.com</string>
    <key>clientId</key>
    <string>your-client-id-for-us-region</string>
</dict>
<!-- Add additional regions in a similar format -->
</array>

对于每个区域，在应用程序的设置中配置关联的域。 这对于正确的 API 路由和身份验证至关重要。

关联域名配置示例: demo-multi-region.entitlements

按照 配置 iOS 关联域名 将您的 iOS 关联域名添加到您的 Frontegg 应用程序。

最后一步是为用户实现一个 UI 以选择他们的区域。这可以用您认为合适的任何方式完成。示例应用程序使用一个简单的选择器视图，允许用户选择他们的区域。

重要注意事项

• 切换区域：要切换区域，请更新 UserDefaults 中的选择。 如果出现问题，可能需要重新安装应用程序。
• 数据隔离：确保数据处理和 API 是特定于区域的，以防止区域之间的数据泄漏。

选择欧盟区域	选择美国区域

区域选择 UI 示例

import SwiftUI
import FronteggSwift

struct SelectRegionView: View {
    @EnvironmentObject var fronteggAuth: FronteggAuth
    
    var body: some View {
        VStack(alignment: .leading) {
            Text("Welcome to MyApp")
                .font(.largeTitle)
            
            Text("Select your region:")
                .padding(.top, 8)
                .padding(.bottom, 20)
                .font(.title2)
            
            
            ForEach(fronteggAuth.regionData, id: \.key.self) { item in
                Button(action: {
                    FronteggApp.shared.initWithRegion(regionKey: item.key)
                }) {
                    VStack(alignment: .leading) {
                        Text("Region - \(item.key.uppercased())")
                            .font(.title2)
                            .padding(.bottom, 1)
                        Text("\(item.baseUrl)")
                            .font(.caption)
                            .tint(.black)
                            .padding(.bottom, 8)
                    }
                }
                .frame(maxWidth: .infinity, alignment: .leading)
                .contentShape(Rectangle())
            }
            
            Spacer()
            
        }
        .padding()
        .navigationTitle("Region")
    }
}

如果您希望用户在重新安装应用程序后不保持登录状态，请将 keepUserLoggedInAfterReinstall 属性添加到 Frontegg.plist 文件中

<plist version="1.0">
  <dict>
    <key>keepUserLoggedInAfterReinstall</key>
    <false/>
    ...
  </dict>
</plist>

默认情况下，keepUserLoggedInAfterReinstall 为 true。

从 1.2.9 版本开始，Frontegg SDK 引入了对 ASWebAuthenticationSession 的支持，从而增强了登录体验。这一新功能允许更简化和安全的身份验证过程。

添加了一个 loginWithPopup 方法，其中包含用于适应 ASWebAuthenticationSession 集成的参数

• window：指定将显示登录视图控制器的窗口。 如果未提供此参数，SDK 将默认使用键窗口。
• ephemeralSession：一个布尔标志，指示会话是否应为临时会话。 默认情况下，此值设置为 true。
• loginHint：用于登录过程中使用的登录提示的可选参数。 默认值为 nil。
• loginAction：一个定义要使用的登录操作的可选参数。 它也默认为 nil。
• completion：登录过程结束后调用的完成处理程序。

以下示例演示了如何在 UIKit 和 SwiftUI 应用程序中将 ASWebAuthenticationSession 与 Frontegg SDK 一起使用。

对于使用 UIKit 的开发人员，可以按如下方式启动登录过程

import UIKit
import FronteggSwift

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
    }

    @IBAction func loginButtonTapped() {
        FronteggAuth.shared.loginWithPopup(window: self.view.window) { result in
            switch result {
            case .success(let user):
                print("User logged in: \(user)")
            case .failure(let error):
                print("Error logging in: \(error)")
            }
        }
    }
}

对于那些喜欢 SwiftUI 的人来说，集成同样简单

import SwiftUI
import FronteggSwift

struct ContentView: View {
    @EnvironmentObject var fronteggAuth: FronteggAuth
    
    var body: some View {
        VStack {
            if fronteggAuth.isAuthenticated {
                Text("User Authenticated")
            } else {
                Button("Login") {
                    fronteggAuth.loginWithPopup()
                }
            }
        }
    }
}

Passkeys 提供无缝的无密码身份验证体验，利用平台级别的生物识别身份验证和 WebAuthn。按照以下步骤将 passkeys 功能集成到您的 iOS 应用程序中。

1. iOS 版本：确保您的项目面向 iOS 15 或更高版本，以支持必要的 WebAuthn API。
2. 关联域名：配置您应用的关联域名以启用 passkeys 功能。
3. Frontegg SDK 版本：使用 Frontegg iOS SDK 版本 1.2.24 或更高版本。

Passkeys 要求在您的应用中正确配置关联域名。请按照以下步骤操作

1. 设置关联域名功能:

   • 在 Xcode 中打开您的项目。
   • 转到 Signing & Capabilities 选项卡。
   • 在 + Capability 部分下添加 Associated Domains。
   • 以以下格式输入您的应用的域名

     webcredentials:[YOUR_DOMAIN]
     

     示例

     webcredentials:example.com
     

2. 托管 WebAuthn 配置文件:

   • 将 .well-known/webauthn JSON 文件添加到您的域名服务器，结构如下

     {
       "origins": [
         "https://example.com",
         "https://subdomain.example.com"
       ]
     }

   • 确保可以在 https://example.com/.well-known/webauthn 公开访问此文件。

3. 测试关联域名:

   • 使用 Apple 的 Associated Domains Validator 验证您的关联域名配置是否有效。

Frontegg SDK 提供了一种在您的应用程序中注册 passkeys 的简单方法。

import FronteggSwift

func registerPasskeys() {
    if #available(iOS 15.0, *) {
        FronteggAuth.shared.registerPasskeys()
    } else {
        print("Passkeys are only supported on iOS 15 or later.")
    }
}

要使用 passkeys 对用户进行身份验证，请使用 SDK 提供的以下方法

import FronteggSwift

func loginWithPasskeys() {
    if #available(iOS 15.0, *) {
        FronteggAuth.shared.loginWithPasskeys { result in
            switch result {
            case .success(let user):
                print("User logged in: \(user)")
            case .failure(let error):
                print("Error logging in: \(error)")
            }
        }
    } else {
        print("Passkeys are only supported on iOS 15 or later.")
    }
}

FronteggAuth 接口为使用 Frontegg 的 iOS 应用程序提供身份验证功能。它包括用于用户身份验证、令牌管理、租户切换等方法。

确保已将 Frontegg SDK 添加到您的 Swift 项目。有关安装步骤，请参阅官方文档。

• accessToken: ReadOnlyObservableValue<String?> - 访问令牌；如果用户未授权，则为 null。
• refreshToken: ReadOnlyObservableValue<String?> - 刷新令牌；如果用户未授权，则为 null。
• user: ReadOnlyObservableValue<User?> - 用户数据；如果用户未授权，则为 null。
• isAuthenticated: ReadOnlyObservableValue<Boolean> - 如果用户已通过身份验证，则为 true。
• isLoading: ReadOnlyObservableValue<Boolean> - 如果进程正在运行，则为 true。
• initializing: ReadOnlyObservableValue<Boolean> - SDK 正在初始化时为 true。
• showLoader: ReadOnlyObservableValue<Boolean> - 如果应显示加载 UI，则为 true。
• refreshingToken: ReadOnlyObservableValue<Boolean> - 如果令牌刷新正在进行中，则为 true。

• baseUrl: String - Frontegg 基本 URL。
• clientId: String - Frontegg 客户端 ID。
• applicationId: String? - Frontegg 应用程序 ID。
• isMultiRegion: Boolean - 如果启用了多区域模式，则为 true。
• regions: List<RegionConfig> - 可用区域列表。
• selectedRegion: RegionConfig? - 当前选择的区域。
• isEmbeddedMode: Boolean - 如果启用了嵌入模式，则为 true。
• useAssetsLinks: Boolean - 是否使用资产链接。
• useChromeCustomTabs: Boolean - 是否使用 Chrome Custom Tabs。
• mainActivityClass: Class<*>? - 主活动类引用。

启动登录流程，显示 Frontegg 登录框。

• 参数
  • completion (可选) - 登录完成时调用。
  • loginHint (可选) - 预填充登录字段。

注销用户，清除认证数据。

• 参数
  • completion (可选) - 注销完成后调用。

切换当前用户的租户。

• 参数
  • tenantId - 新租户的 ID。
  • completion (可选) - 切换完成后调用。

如果需要，刷新身份验证令牌。

• 参数
  • attempts - 令牌刷新尝试次数。
• 返回： 如果令牌成功刷新，则返回 true，否则返回 false。

使用通行密钥登录。

• 参数
  • completion (可选) - 登录完成或失败时调用。

注册通行密钥以进行身份验证。

• 参数
  • completion (可选) - 注册完成或失败时调用。

异步请求静默授权。

• 参数
  • refreshToken - 刷新令牌。
  • deviceTokenCookie (可选) - 用于额外身份验证的设备令牌。
• 返回： 成功验证后的 User 对象。
• 抛出： 失败时抛出 FronteggError。

使用回调请求授权。

• 参数
  • refreshToken - 刷新令牌。
  • deviceTokenCookie (可选) - 设备令牌。
  • completion - 接收身份验证结果（User 或 FronteggError）。