Staq 钱包

要求

Xcode 16
Apple Swift 版本 6.0

安装

使用 Swift Package Manager (SPM)

将软件包依赖项添加到您的 Package.swift 文件，并将依赖项添加到 dependencies 数组。这是一个示例

dependencies: [
    .package(url: "https://github.com/staqio/StaqWallet", exact: "2.0.0-beta.3")
]

targets: [
    .target(name: "TargetName", dependencies:[
        "StaqWallet"
    ])
]

运行命令 swift package update 下载软件包及其依赖项。

用法

要启动钱包流程，请导入 StaqWallet 框架并使用它提供的 StaqWalletManager 类。此类使用户能够在设置必要的配置后启动钱包流程。

StaqWalletConfig

一个结构体，表示初始化和验证 StaqWallet SDK 所需的配置参数。

参数

userId：用户的唯一标识符。
secret：用于身份验证的密钥。
email：（可选）用户的电子邮件地址。
language：钱包界面的首选语言。默认为 .en。
walletEnv：钱包运行的环境（例如，生产环境、沙箱环境）。默认为 .production。

用法示例

import StaqWallet

StaqWalletManager.start(
    withConfig: StaqWalletConfig(...),
    fromNavigationController: navigationController
)

导航控制器设置

您必须为 SDK 提供一个 UINavigationController 以用于导航目的。此导航控制器将由 SDK 在内部用于推送和呈现视图。

确保将有效的 UINavigationController 实例传递给 SDK，因为这是正确处理导航所必需的。

Face ID 设置

请务必通过将以下键添加到您的 Info.plist 文件中，在您的应用中启用 Face ID

<key>NSFaceIDUsageDescription</key>
<string>We use Face ID to authenticate your identity quickly and securely.</string>

如果未添加此键，您的应用程序在尝试使用 Face ID 时将会崩溃。

文档扫描和 KYC 验证

对于文档扫描和 KYC 验证等功能，您需要将相机和麦克风权限添加到您的 Info.plist 中

<key>NSCameraUsageDescription</key>
<string>We need access to the camera to capture your documents for verification purposes.</string>
<key>NSMicrophoneUsageDescription</key>
<string>We need access to the microphone to assist in the verification process.</string>

同样，如果缺少这些权限，则在需要相机或麦克风时，应用将会崩溃。

国内用户身份验证重定向

国内用户可以使用 Nafath 服务注册钱包。要启用重定向到 Nafath 应用程序，您需要将以下查询 scheme 添加到您的 Info.plist 中

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>nafath</string>
</array>

这确保您的应用可以检查是否安装了 Nafath 应用，并无缝地重定向用户以完成注册流程。

处理有序包的导航

国内钱包不为显示有序包提供内置导航功能。因此，您必须通过在 StaqWalletManager 类上向 setPackagesNavigationCallback 方法提供导航回调来手动处理导航。

StaqWalletManager.setPackagesNavigationCallback {
    // Implement your custom navigation logic here
}

启动钱包流程的示例代码

以下是在您的 SceneDelegate 中初始化钱包流程的最小实现

import StaqWallet
import UIKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(
        _ scene: UIScene,
        willConnectTo session: UISceneSession,
        options connectionOptions: UIScene.ConnectionOptions
    ) {
        guard let windowScene = scene as? UIWindowScene else { return }
        let window = UIWindow(windowScene: windowScene)
        self.window = window

        let rootViewController = UIViewController()
        let navigationController = UINavigationController(
            rootViewController: rootViewController
        )

        window.rootViewController = navigationController
        window.makeKeyAndVisible()

        let config = StaqWalletConfig(
            userId: "user-id",
            secret: "user-secret",
            email: "user-email",
            language: .en,
        )

        StaqWalletManager.setPackagesNavigationCallback {
            // Implement your custom navigation logic here
        }

        StaqWalletManager.start(
            withConfig: config,
            fromNavigationController: navigationController
        )
    }
}

Staq 钱包支付

StaqWalletPay 类为将钱包支付功能集成到您的应用程序中提供了全面的解决方案。它提供了用于管理钱包余额、创建和检索支付订单以及呈现钱包支付相关用户界面的工具。

概述

StaqWalletPay 是一个单例类，旨在简化钱包支付操作。它支持

UI 管理：呈现用于钱包支付详细信息和操作的模态视图。
钱包管理：获取钱包余额，并具有强大的错误处理能力。
支付订单管理：使用异步方法创建和检索支付订单详细信息。

检索钱包余额

异步获取当前钱包余额。

方法签名

public static func getWalletBalance() async throws -> Double

返回值

钱包的可用余额，类型为 Double。

抛出

WalletPayError.walletNotAvailable：钱包账户不可用。
WalletPayError.notLoggedIn：用户未登录或会话无效。
WalletPayError.server：服务器错误，带有代码和消息。
WalletPayError.unexpected：发生意外错误。

模型

WalletPayError

一个枚举，表示在钱包支付系统中支付操作期间可能发生的错误。

错误情况

notLoggedIn：表示用户未登录或其会话无效。
walletNotAvailable：表示钱包不可用。
server(code: String, message: String)：表示服务器端错误，带有错误代码和描述性消息。
unexpected：表示发生了意外错误。

用法示例

do {
    let balance = try await StaqWalletPay.getWalletBalance()
} catch let error as StaqWalletPay.WalletPayError {
    print("Wallet Pay Error: \(error.errorDescription ?? "Unknown error")")
} catch {
    print("Other Error: \(error.localizedDescription)")
}

PaymentOrderParams

一个结构体，表示在钱包支付系统中创建支付订单所需的参数。

参数

idempotencyKey：用于确保请求幂等性的唯一键。
externalId：订单的可选外部标识符。
totalAmount：支付订单的总金额。
feesAmount：表示费用的总金额的可选部分。
taxAmount：表示税费的总金额的可选部分。
supplierId：履行订单的供应商的唯一标识符。
metaData：订单的可选附加元数据。

初始化器

public init(
    idempotencyKey: String = UUID().uuidString,
    externalId: String? = nil,
    totalAmount: Double,
    feesAmount: Double?,
    taxAmount: Double?,
    supplierId: String,
    metaData: [String: String] = [:]
)

支付订单 UI

钱包支付 UI 是 SwiftUI 和 UIKit 组件的组合，用于处理与支付相关的工作流程。这些组件包括用于显示钱包详细信息的视图和用于处理用户支付交互的模态视图。

WalletPayView

概述

WalletPayView 是一个 SwiftUI 视图，可以动态渲染两种类型的布局

内联视图 (inline)：钱包支付详细信息的紧凑表示形式。
细分视图 (breakdown)：显示支付订单参数的详细视图。

参数

variant：指定布局类型（inline 或 breakdown）。
state：管理钱包支付视图的行为和余额的状态对象 (WalletPayViewState)。
params：支付订单的参数 (StaqWalletPay.PaymentOrderParams)。

用法示例

struct ContentView: View {
    @StateObject var state = WalletPayViewState(
        isSelected: false,
        balance: 100.0
    )

    var body: some View {
        WalletPayView(
            variant: .breakdown,
            state: state,
            params: StaqWalletPay.PaymentOrderParams(...)
        )
        .onTapGesture {
            state.isSelected.toggle()
        }
    }
}

UIWalletPayView

概述

UIWalletPayView 是一个 UIKit 包装器，用于将 WalletPayView 嵌入到基于 UIKit 的项目中。它使用 UIHostingController 来无缝集成 SwiftUI 视图。

属性

frame：视图的框架矩形，以点为单位测量。
variant：Wallet Pay 视图的布局类型（inline 或 breakdown）。
state：管理钱包支付视图的行为和余额的状态对象 (WalletPayViewState)。
params：支付订单的参数 (StaqWalletPay.PaymentOrderParams)。

用法示例

class ViewController: UIViewController {
    var walletPayView: UIWalletPayView!

    override func viewDidLoad() {
        super.viewDidLoad()

        walletPayView = UIWalletPayView(
            frame: CGRect(x: 0, y: 0, width: 300, height: 150),
            variant: .inline,
            state: WalletPayViewState(isSelected: false, balance: 100.0),
            params: StaqWalletPay.PaymentOrderParams(...)
        )

        let tapGesture = UITapGestureRecognizer(
            target: self,
            action: #selector(handleTap)
        )
        walletPayView.addGestureRecognizer(tapGesture)

        view.addSubview(walletPayView)
        walletPayView.center = view.center
    }

    @objc private func handleTap() {
        walletPayView.isSelected.toggle()
    }
}

WalletPayDetailsModalView

概述

WalletPayDetailsModalView 是一个 SwiftUI 模态视图，用于显示详细的钱包支付信息，例如余额和支付参数，并提供用户交互选项。

参数

isPresented：一个绑定，用于确定是否呈现模态视图。
balance：要显示的当前钱包余额。
params：支付订单的参数 (StaqWalletPay.PaymentOrderParams)。
didDismiss：一个可选的闭包，在模态视图被关闭时执行。
didTapConfirm：一个可选的闭包，在点击确认按钮时执行。该闭包接收一个 dismiss 函数，允许以编程方式关闭模态视图。

用法示例

struct WalletPayDetailsExampleView: View {
    @State private var isDetailsPresented = false

    var body: some View {
        VStack { ... }
            .overlay {
                WalletPayDetailsModalView(
                    isPresented: $isDetailsPresented,
                    balance: 150.0,
                    params: StaqWalletPay.PaymentOrderParams(...),
                    didDismiss: {
                        print("Modal dismissed")
                    },
                    didTapConfirm: { dismiss in
                        print("Confirm tapped")
                        dismiss()
                    }
                )
            }
    }
}

钱包支付详情

概述

呈现钱包支付详细信息模态视图，使用户能够查看支付详情、查看钱包余额并确认操作。

方法签名

public static func presentWalletPayDetails(
    from parent: UIViewController,
    balance: Double,
    params: StaqWalletPay.PaymentOrderParams,
    didDismiss: (() -> Void)? = nil,
    didTapConfirm: ((_ dismiss: () -> Void) -> Void)? = nil
)

参数

parent：将从中呈现模态视图的父视图控制器。
balance：钱包的当前余额。
params：钱包支付操作所需的参数 (StaqWalletPay.PaymentOrderParams)。
didDismiss：一个可选的闭包，在模态视图被关闭时调用。
didTapConfirm：一个可选的闭包，在点击确认按钮时调用。该闭包提供了一个 dismiss 函数，可以调用该函数来关闭模态视图。

用法示例

StaqWalletPay.presentWalletPayDetails(
    from: self,
    balance: 150.0,
    params: params,
    didDismiss: {
        print("Modal dismissed")
    },
    didTapConfirm: { dismiss in
        print("Payment confirmed")
        dismiss()
    }
)

支持组件

WalletPayViewType

WalletPayViewType 是一个枚举，用于指定 WalletPayView 的布局类型。

情况

.inline：钱包支付的紧凑表示形式。
.breakdown：包含支付订单参数的详细视图。

WalletPayViewState

WalletPayViewState 是一个可观察对象，用于跟踪钱包支付视图的状态。它旨在与 SwiftUI 无缝协作，允许在状态更改时进行动态更新。

属性

isSelected：一个布尔值，指示视图是否被选中。
balance：当前钱包余额。

支付订单管理

概述

StaqWalletPay 类提供管理支付订单的功能，包括创建新的支付订单和检索现有订单的详细信息。

创建支付订单

使用指定的参数异步创建新的支付订单。

方法签名

public static func createPaymentOrder(
    params: StaqWalletPay.PaymentOrderParams
) async throws -> CreatePaymentOrderResponse

参数

params：PaymentOrderParams 的实例，其中包含支付订单所需的详细信息。

抛出

WalletPayError

返回值

CreatePaymentOrderResponse：一个响应，其中包含已创建的支付订单的详细信息。

获取支付订单详情

通过其唯一标识符获取现有支付订单的详细信息。

方法签名

public static func getPaymentOrderDetails(
    orderId: String
) async throws -> PaymentOrderDetails

参数

orderId：一个字符串，表示支付订单的唯一标识符。

抛出

WalletPayError

返回值

PaymentOrderDetails：一个对象，其中包含有关支付订单的详细信息。

如果您有任何问题、需要澄清或想更详细地讨论任何内容，请随时通过电子邮件与我联系。我总是很乐意提供帮助和支持。您可以通过 [d.lunov@staq.io] 联系我，我会尽力及时回复。请随时联系！