iOS

应的官方页面地址

此 SDK 的目的是能够通过 Passwordless.dev 管理系统轻松地将通行密钥集成到您的 iOS App 中。

apple-app-site-association

Apple 要求设置关联域名以执行通行密钥注册和断言。有关设置 apple-app-site-association 的更多详细信息，请参阅 Apple 文档。

对于通行密钥，您需要为您的 App 设置一个 webcredentials 部分。

iOS SDK 入门

要求

• 最低 iOS 版本： iOS 16

• 额外功能：

  • 关联域名是添加 AASA 文件托管的域名所必需的。

Swift 包管理器

您可以通过 Swift 包管理器将 SDK 添加到项目中。然后，您可以使用 import Passwordless 来访问 SDK 功能。

CocoaPods

SDK 可以通过 CocoaPods 添加到您的项目中。在 Podfile 中指定以下内容：

pod 'Passwordless', '~> 1.0.0'

初始化

SDK 提供了一个 PasswordlessClient 对象，该对象需要使用一个 PasswordlessConfig 配置进行初始化。配置包含与 Passwordless.dev 交互所需的 API URL 和 API 密钥。它还需要依赖方 ID，该 ID 代表您服务器上的域名，该域名托管了一个包含您的 App 团队 ID 和包 ID 的 apple-app-site-association 文件。

您需要注册 Passwordless.dev 以获取 API 密钥。

下面是一个配置示例：

let passwordlessClient = PasswordlessClient(
    config: PasswordlessConfig(
        apiKey: "<YOUR API KEY>",
        rpId: "demo.passwordless.dev"
    )
)

注册

1. 使用给定的用户名从您的公共 RESTful API 请求注册令牌。

2. 通过 register(token:) 将注册令牌传递给 PasswordlessClient 。将提示用户使用生物识别创建所需的本地私钥以进行验证，并将公钥发送到 Passwordless.dev API。完成后，将返回一个验证令牌。请参阅错误部分以了解可能抛出的错误。

let verifyToken = try await passwordlessClient.register(token: registrationToken)

1. 将验证令牌传递给您的公共 RESTful API 以进行验证并返回一个授权令牌。用户现在已登录到您的 App 了。

Registration Flow

登录

通行密钥登录主要有两种方式：自动填充和别名。同时也提供了用于更高级用例的 signinWithDiscoverable() 和 signIn(userId:)。

A. 自动填充

当用户点击用户名字段时，键盘将出现。如果用户点击键盘上方的自动填充选项，那么这就是自动填充方式。为了正常工作，您必须在视图首次出现时调用 signInWithAutofill。这样，当键盘出现时，操作系统将准备好要显示的结果。

1. 在视图首次出现时调用 signInWithAutofill()。完成后，将返回一个验证令牌。

   • 此函数将等待用户点击自动填充项目、在通行密钥对话框中取消或发生错误。

   • 如果抛出错误，您的 App 需要决定是否重新启动自动填充登录过程。

   • 如果它没有运行，则键盘将不会显示任何选项，因此通常只有在 授权已取消 的情况下才需要重新启动该过程。

   • 获取 授权错误 可能表明您的 App 中某些配置不正确，因此最好不要再次运行自动填充以防止无限循环错误。请参阅错误部分以了解可能抛出的错误。

let verifyToken = try await passwordlessClient.signInWithAutofill()

1. 将验证令牌传递给您的公共 RESTful API 以进行验证并返回一个授权令牌。用户现在已登录到您的 App 了。

Auto Fill Sign in Flow

B. 别名

当用户输入用户名并点击视图中的按钮进行登录时，将显示供用户选择的不同的通行密钥窗口版本。

1. 使用给定的别名调用 signIn(alias:)。完成后，将返回一个验证令牌。请参阅错误部分以了解可能抛出的错误。

let verifyToken = try await passwordlessClient.signIn(alias: username)

1. 将验证令牌传递给您的公共 RESTful API 以进行验证并返回一个授权令牌。用户现在已登录到您的 App 了。

Alias Sign in Flow

C. 可被发现

如果您想手动显示通行密钥模态，而不使用快捷键或让用户输入别名。

D. 用户 ID

如果您已经有了用户 ID，并想进行断言过程。

错误响应

PasswordlessClient 对象可能会抛出以下错误：

错误	描述
authorizationCancelled	操作系统授权被密钥凭证提供程序取消。
authorizationError(Error)	来自密钥凭证提供程序的操作系统授权失败。
internalErrorDecodingJson(Error)	从网络响应中解码 JSON 到对象时出现问题。
internalErrorEncodingPayload(Error)	从对象编码 JSON 以进行网络请求时出现问题。
internalErrorInvalidURL(String)	使用的网络请求 URL 无效。
internalErrorNetworkRequestFailed(Error)	在进行网络请求时发生错误。
internalErrorNetworkRequestResponseError(Int?, PasswordlessErrorResponse?)	网络请求发生错误，如果可用，将提供状态码和错误响应。
internalErrorUnableToDecodeChallenge	提供的挑战格式不正确。
internalErrorUnableToEncodeUserId	用户 ID 无法被编码为 Base64 URL。

对于 internalErrorNetworkRequestResponseError，可以提供 PasswordlessErrorResponse，其中包含关于响应中错误的详细信息。以下是一个可能返回的响应错误示例：

{
  "type": "https://docs.passwordless.dev/errors#missing_register_token",
  "title": "The token you sent was not correct. The token used for this endpoint should start with 'register_'. Make sure you are not sending the wrong value.",
  "status": 400,
  "errorCode": "missing_register_token"
}

下面是一个如何在您的 App 中查看此示例的示例：

do {
    let verifyToken = try await passwordlessClient.signIn()
}
catch PasswordlessClientError.authorizationCancelled {
    print("Cancelled")
}
catch let PasswordlessClientError.internalErrorNetworkRequestResponseError(code, response) {
    print("Network Error occurred. Response status code: \(code ?? -1)")
    dump(response)
}
catch {
    print("Some other error occurred: \(error)")
}