Twilio Verify iOS

• 关于
• 依赖
• 要求
• 文档
• 安装
• 使用
• 运行示例应用
• 运行示例后端
• 使用示例应用
• 日志记录
• 错误
• 更新因子的推送令牌
• 删除因子
• 清除本地存储
• 重新安装并持久化因子
• 通知扩展
• 贡献
• 许可证

Twilio Verify Push SDK 帮助您通过在您自己的移动应用程序中添加低摩擦、安全、经济高效的“推送验证”因子来验证用户。这项完全托管的 API 服务允许您通过安全通道在应用内无缝验证用户，而没有一次性密码 (OTP) 的风险、麻烦或成本。本项目提供一个 SDK 来为您的 iOS 应用实现 Verify Push。

无

• iOS 10+
• Swift 5.2
• Xcode 13.x

SDK API 文档

CocoaPods 是 Cocoa 项目的依赖管理工具。有关使用和安装说明，请访问他们的网站。要使用 CocoaPods 将 TwilioVerify 集成到您的 Xcode 项目中，请在您的 Podfile 中指定它

pod 'TwilioVerify', '~> 2.2.2'

Carthage 是一个去中心化的依赖管理器，它可以构建您的依赖项并为您提供二进制框架。要使用 Carthage 将 TwilioVerify 集成到您的 Xcode 项目中，请在您的 Cartfile 中指定它

github "twilio/twilio-verify-ios" -> 2.2.2

自从 TwilioVerifySDK 的 2.2.2 版本以来，预构建的 asset fat 版本 .framework 已被弃用，为通用框架 .xcframework 让路。请确保使用 Carthage 的新版本 0.38.0，该版本已发布以支持 xcframework asset。通过使用此版本或更高版本，Carthage 将下载并解压缩 release 版本中附加的 TwilioVerifySDK.framework.zip，从而生成可以在 Carthage 的 build 文件夹中找到的 TwilioVerifySDK.xcframework。

Swift Package Manager 是一个用于自动化 Swift 代码分发的工具，并已集成到 swift 编译器中。它仍处于早期开发阶段，但 TwilioVerify 确实支持在 iOS 上使用它。

一旦您设置好 Swift 包，将 TwilioVerify 添加为依赖项就像将其添加到 Package.swift 的 dependencies 值中一样容易。

dependencies: [
    .package(url: "https://github.com/twilio/twilio-verify-ios.git", .upToNextMajor(from: "2.2.2"))
]

如果您想接收作为推送通知的挑战，您应该向 APNs 注册您的应用。更多信息请访问 此处

注意

SDK 应该从 Swift 类中使用。请参阅 TwilioVerifyAdapter 类 中的示例

自从 2.2.2 版本以来，目标已从 TwilioVerify 更改为 TwilioVerifySDK。从旧版本迁移将意味着更新您文件中所有导入，请参阅 TwilioVerifyAdapter 类 中的示例

有关在基本的 Verify Push 实现中使用此 SDK 的分步指南，请参阅 Verify Push 快速入门。

• 克隆仓库
• 将 Bundle Identifier 更改为唯一的名称，以便 Apple 的推送通知服务器可以将推送定向到此应用
• 启用推送通知
• 从您的后端获取访问令牌生成 URL （运行示例后端）。您将使用它来创建因子
• 使用 Release 作为构建配置运行 TwilioVerifyDemo 项目

当您的应用已经知道用户正尝试在与被挑战的已注册设备相同的设备上完成操作（主动登录、进行交易等）时，您可以静默批准挑战。

您可以为因子启用“静默批准挑战”选项。启用后，当应用在前台运行时，为该因子收到的每个作为推送通知的挑战都将被静默批准，因此不需要用户交互。该选项将为会话保存，因此选择不会被持久化。

• 使用相同的 APNs 配置，为示例应用配置 推送凭据
• 使用示例应用的推送凭据，配置 Verify 服务
• 前往：https://www.twilio.com/code-exchange/verify-push-backend
• 使用 Quick Deploy to Twilio 选项
  • 您应该登录您的 Twilio 帐户
  • 输入您上面创建的 Verify Service Sid，您可以在 此处 找到它
  • 部署应用程序
  • 按 Go to live application
  • 您将看到起始页。复制 URL 并将 index.html 替换为 access-token。（例如 https://verify-push-backend-xxxxx.twil.io/access-token）。这将是您的 Access Token generation URL

• 在因子列表中按 Create factor（点击右上角的 + 号）
• 输入要使用的身份。此值应为 UUID，用于标识用户以防止使用 PII 信息
• 输入 Access token URL（访问令牌生成 URL，包括路径，例如 https://verify-push-backend-xxxxx.twil.io/access-token）
• 按 Create factor
• 复制因子 Sid

• 前往 Create Push Challenge 页面（示例后端中的 /challenge 路径）
• 输入您在因子创建中使用的 identity
• 输入您添加的 Factor Sid
• 输入 message。您将在推送通知和挑战视图中看到该消息
• 输入挑战的详细信息。您将在挑战视图中看到它们。您可以使用 Add more Details 按钮添加更多详细信息
• 按 Create challenge 按钮
• 您将在您的设备上收到一个推送通知，显示挑战消息。
• 应用将在因子信息下方，在 Challenge 部分中显示挑战信息
• 批准或拒绝挑战
• 挑战更新后，您将在后端的 Create Push Challenge 视图中看到挑战状态

默认情况下，日志记录被禁用。要启用它，您可以实现 LoggerService 并调用 addLoggingService 来设置您自己的日志记录服务（请注意，您可以根据需要添加任意数量的日志记录服务），或者通过调用 enableDefaultLoggingService 来启用默认日志记录服务。您的多个实现和默认实现可以同时工作，但您可能只想在开发过程中启用它，在发布应用时启用它是危险的。

您可能只想记录 SDK 中发生的某些进程，或者您只想记录所有内容，为此，SDK 允许您设置日志级别。

• error：报告不应发生的行为。
• info：警告正在执行的操作的特定信息。
• debug：详细信息。
• networking：网络工作的特定数据，例如请求正文、标头、响应代码、响应正文。
• all：启用 error、info、debug 和 networking。

要开始日志记录，请启用默认日志记录服务或/并传递您的自定义实现

var builder = TwilioVerifyBuilder()
#if DEBUG
  builder = builder.enableDefaultLoggingService(withLevel: .all)
                   .addLoggingService(MyOwnLoggerService1())
                   .addLoggingService(MyOwnLoggerService2())
#endif
twilioVerify = try builder.build()

您可以按照下一个示例控制 此处 列出的 Verify API 错误代码

twilioVerify.createFactor(withPayload: payload, success: { factor in
  // Success
}) { error in
  let apiError = error.originalError as? NetworkError
    
  if case let .failureStatusCode(response) = apiError {
    // Gets Verify API error response
    var errorResponse = response
    
    if let code = errorResponse.apiError?.code,
        let message = errorResponse.apiError?.message {
      print("Code: \(code) - \(message)")
    }
  }
}

请查看 此处 的示例

您可以访问关联的错误来获取错误的原因

twilioVerify.updateChallenge(withPayload: payload, success: {
  // Success
},failure: { error in
  if case .inputError(let detail) = error, let inputError = detail as? InputError {
    switch inputError {
      // Handle other cases here, in this example expired challenge case
      case .expiredChallenge: return
      default: return
    }
  }
})

您可以在 此处 找到验证的关联错误

有关更多详细信息，请查看 此处 的特定内部操作错误

如果因子的推送令牌发生更改，您可以调用 TwilioVerify.updateFactor 方法来更新因子的推送令牌

let updateFactorPayload = UpdatePushFactorPayload(sid: factorSid, pushToken: newPushToken)
twilioVerify.updateFactor(withPayload: payload, success: { factor in
  // Success
}) { error in
  // Error
}

请参阅示例应用中的 FactorListPresenter。您应该更新所有因子的推送令牌。

您可以调用 TwilioVerify.deleteFactor 方法来删除因子

twilioVerify.deleteFactor(withSid: factorSid, success: {
  // Success
}) { error in
  // Error
}

您可以调用 TwilioVerify.clearLocalStorage 方法来清除本地存储

do {
  try twilioVerify.clearLocalStorage()
} catch {
  // Handle error
}

• 调用此方法不会删除 Verify Push API 中的因子，因此您需要从后端删除它们，以防止在获取身份的因子时出现无效/已删除的因子。
• 由于 Keychain 用于存储，因此如果在执行 Keychain 操作时发生错误，此方法可能会失败。

默认情况下，出于安全原因，创建的因子和密钥对在应用卸载并重新安装后不会在设备中持久存在。但是，可以更改此默认行为并在重新安装后持久化因子和密钥对，因为两者都保存在 keychain 中。

注意 这在未来的 iOS 版本中可能会更改，但它将继续适用于 iOS 15 及更低版本。在应用卸载时保留 keychain 项目可能存在安全隐患。您不应依赖此行为，如果此行为发生更改，则应提供重新注册因子的替代方法。

要在重新安装后持久化因子，请在创建 TwilioVerify 实例时使用 TwilioVerifyBuilder.setClearStorageOnReinstall 方法。默认值为 true，因此因子将在重新安装时删除。将其更改为 false 以持久化因子。

let builder = TwilioVerifyBuilder().setClearStorageOnReinstall(false)
let twilioVerify = try builder.build()

推送令牌将在重新安装后更改。更新推送令牌以接收挑战的推送通知，如 更新因子的推送令牌 中所述

SDK 使用 kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly 来 保存因子和密钥对。根据 Apple 的说法，

具有此属性的项目不会迁移到新设备。因此，从不同设备的备份恢复后，这些项目将不会存在。

通知扩展 是一种应用扩展，允许开发者在远程通知传递给用户之前修改或处理其内容。

请按照 Apple 的修改新交付通知中的内容指南创建通知扩展。

为了能够在通知扩展中使用 Verify SDK，有必要使用 App Groups，这将允许应用扩展能够从应用程序读取 KeyChain 存储。否则，SDK 将无法读取通知扩展中存储的任何因子或挑战。

let builder = TwilioVerifyBuilder()
let twilioVerify = try builder.setAccessGroup("group.com.example.AppSuite").build()

使用 setAccessGroup 方法设置用于 keychain 访问的应用组。

请考虑到通知扩展的生命周期大约只有 30 秒，因此如果由于某种原因，应用扩展在该期限到期之前未处理远程通知内容，它将显示原始内容。

请参阅 Notification Extension 分支，以查看在 VerifyDemoApp 中使用通知扩展和 SDK 的实现示例。

使用 App Groups 共享因子

首次设置 setAccessGroup 配置时，因子数据将迁移以使用 kSecAttrAccessGroup Keychain 的属性。如果迁移失败，将发送错误日志，而不是在初始化期间抛出错误，数据仍可用于主应用程序，但可能不适用于应用扩展。

停止从 App Groups 共享因子

通过从 setAccessGroup 配置中删除 App Group，新因子将不会通过 Keychain 应用组共享。

let builder = TwilioVerifyBuilder()
let twilioVerify = try builder.build()

要停止共享使用 App Groups 创建的现有因子，请从 Xcode 中的 App/App Extension 配置中取消选中 App Group，如下所示

App/App Extension -> App Groups -> 取消选中 App Group

这将限制对因子的访问，并且不会影响最初创建数据的主应用程序。

本文档是 Twilio Verify SDK 的隐私清单。它概述了此 SDK 中实施的隐私实践，提供了对我们如何处理数据和尊重用户隐私的全面理解。

此隐私清单的主要目的是帮助开发者和组织向 Apple 提供有关此 SDK 中使用的隐私实践的详细信息。

要使用此隐私清单，只需在需要向 Apple 或任何其他相关方提供有关此 SDK 中使用的隐私实践的信息时参考相关部分即可。

本项目欢迎贡献。请查看我们的 贡献指南 以了解更多关于如何开始的信息。

Apache © Twilio Inc.