Bolt iOS SDK

Bolt iOS SDK可以使商家将其应用程序与Bolt Checkout集成。

获取SDK

SDK作为包含适用于iOS设备和模拟器的预构建框架的`XCFramework`包提供。支持Swift Package Manager和Cocoapods包管理器。最低iOS目标版本为13.0。

Swift Package Manager

1. 将包添加到Xcode项目

• 转到文件 -> 添加包
• 输入包URL - https://github.com/BoltApp/bolt-ios
• 点击添加包

1. 如果未自动添加，请添加框架到应用程序目标

• 在项目导航器中点击应用程序项目
• 选择应用程序目标
• 选择“通用”选项卡
• 在框架、库和嵌入式内容中点击加号图标
• 添加Bolt模块

Cocoapods

1. 将`pod 'Bolt'`添加到项目的Podfile中
2. 运行pod install

初始化SDK

在使用SDK之前，需要使用客户端属性进行初始化。以下可以指定以下属性

1. 发布密钥：公开可见的标识符，用于识别一个商家部门。此密钥可在Bolt商家仪表板的“管理 -> 开发者 -> API”部分找到。
2. 环境：要使用的Bolt服务器环境，例如`staging`或`production`。

初始化示例

import Bolt

Bolt.ClientProperties.shared.publishableKey = "<key>"
Bolt.ClientProperties.shared.environment = .staging

信用卡标记化工具

信用卡标记化工具提供了一种以PCI合规方式收集和存储信用卡信息的方法。在内部，SDK使用本地生成的客户端公钥/私钥对和服务器公钥加密卡和标记信息。

标记可以转发到商家服务器，商家可以使用它通过Bolt商家授权端点对信用卡进行收费。

使用方法

标记化函数接受信用卡号和卡验证值（CVV）。如果从服务器获得成功响应，则返回一个新生成的卡标记值，该值表示存储的卡。

let tokenizer = Bolt.CreditCardTokenizer()
tokenizer.generateToken(cardNumber: "4111111111111111", cvv: "123") { result in
    switch result {
    case let .success(tokenizedCard):
        print(tokenizedCard)
    case let .failure(error):
        print(error)
    }
}

在测试环境中，可以使用任何CVV与卡号4111 1111 1111 1111一起使用以获得成功的标记化响应。

响应示例

CreditCardToken(
    token: "7dfc9c8c3e69a383da7b203e5b685e72f242ed90298d3e2f3426fd010c8e6219",
    tokenExpiry: 1671140825305, // 15 minutes from time of creation
    last4: "1111",
    bin: "411111",
    network: "visa"
)

处理Bolt用户登录

 

这是启用现有Bolt用户登录所需的步骤

1. 检测用户账户

首先，我们需要检测用户是否有现有的Bolt账户。

• 在您的结账表单中，向电子邮件地址文本字段添加处理器。这可以通过在UIKit中使用UITextField.textFieldDidEndEditing(:)或SwiftUI中使用TextField.onSubmit(of:)来完成。
• 在此处理器中，使用电子邮件地址和您的商家发布密钥（可在Bolt商人仪表板中找到）调用Bolt的DetectAccount API。
• 如果成功，API将返回一个值，指示电子邮件地址是否已注册到Bolt账户

{
    "has_bolt_account": true,
}

• 如果检测到Bolt账户，请按照下一个步骤显示Bolt授权页面。

2. 显示Bolt授权页面

Bolt授权页面显示提示，要求用户输入通过电子邮件或手机发送的一次性密码（OTP）。用户输入OTP后，页面将重定向到包含查询参数中授权码的URL。然后可以将此授权码发送到商家服务器以交换OAuth访问令牌。这可以用于访问Bolt账户API并访问用户信息，例如存储的收货地址和信用卡。

• 创建一个WKWebView对象，并将navigationDelegate属性设置为符合WKNavigationDelegate的对象。
• 为WKNavigationDelegate.webView(_:decidePolicyFor:decisionHandler:)添加实现，用于检测重定向并执行适当的操作。

func webView(
    _ webView: WKWebView,
    decidePolicyFor navigationAction: WKNavigationAction,
    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
) {
    guard let urlString = navigationAction.request.url?.absoluteString,
          let url = URL(string: urlString) else {
        return decisionHandler(.allow)
    }

    // NOTE: replace 'mobileapp' below with the prefix used for your app for Bolt login
    if urlString.hasPrefix("mobileapp://"), let range = urlString.range(of: "authorization_code=") {
        // We have a redirect with auth code in the query parameters
        let index = urlString.distance(from: urlString.startIndex, to: range.upperBound)
        let startIndex = urlString.index(urlString.startIndex, offsetBy: index)
        let authCode = String(urlString[startIndex...])
        decisionHandler(.allow)
        // Pass authCode to backend to exchange for OAuth access token
        // WebView can be dismissed at this point
    } else if urlString == parent.url.absoluteString {
        // This is the original URL request - open as normal
        decisionHandler(.allow)
    } else {
        // Open other links in the system browser, e.g. Terms of Use, Privacy Policy
        UIApplication.shared.open(url)
        decisionHandler(.cancel)
    }
}

• 获取Bolt授权URL并将其加载到webview中。可以安全地强制解包该URL，它只有在初始化步骤中未设置可发布密钥时才会返回nil。

let url = Bolt.Login.getAuthorizationURL(email: "[email protected]")!
webView.load(.init(url: url))

• 在UIKit中将WKWebView嵌入到UIViewController中，或在SwiftUI中将它嵌入到UIViewRepresentable中，并以全屏模态呈现。应使用全屏模态以确保有足够的空间显示键盘和网页中的任何错误消息。

收到授权码后，将其传递给您的后端服务器，后端服务器可以使用Bolt的OAuthToken端点来交换访问令牌。该访问令牌可用于使用Bolt的Account API访问用户信息。

实现结算分析（可选）

商家可以调用一个跟踪结算流程事件的分析方法。这是可选步骤，对于收集用户从结算到付款的购物旅程数据很有用。在结算流程的特定点可以跟踪几个预定义的事件。例如，当从购物车中点击结算按钮时进行的调用示例

Bolt.Analytics.log(.checkoutButtonTapped)

事件列表

事件在Bolt.Analytics.Event枚举中定义

事件名称	何时跟踪事件
checkoutButtonTapped	从购物车中点击结算按钮
checkoutLoadSuccess	初始结算屏幕已完全加载
checkoutLoadError	发生错误，阻止加载结算屏幕
shippingAddressEntryBegan	用户开始输入收货地址信息
shippingDetailsFullyEntered	用户已填写收货地址屏幕上的所有字段
shippingContinueButtonTapped	用户点击收货地址屏幕上的按钮以继续结算过程
shippingMethodSelected	用户选择或切换运输方式
boltAccountExistenceCheckRequested	调用Bolt DetectAccount API以检查Bolt账户是否存在
boltAccountExistenceCheckReceived	Bolt DetectAccount API响应已接收
boltAccountCreationCheckboxTapped	用户勾选Bolt账户创建复选框
boltLoginScreenDisplayed	显示OTP提示以进行用户登录
boltLoginScreenClosed	关闭OTP提示
boltLogOutButtonTapped	用户点击按钮退出Bolt账户
paymentDetailsFullyEntered	用户已填写支付屏幕上的所有字段或选择已保存的支付方式
paymentMethodSelected	用户选择新的支付方式
paymentButtonTapped	用户点击支付按钮
paymentSuccessful	订单成功提交
paymentFailed	订单在支付步骤失败

添加自定义数据

可以在所有事件或特定事件中包含自定义属性。这些属性是键值对，其中键是String，值是符合Encodable的任何类型。要添加到所有事件，请使用setCommonProperties函数。例如，要添加表示用户是否已登录到商家账户的属性，请

Bolt.Analytics.setCommonProperties(["merchantLoggedIn": true])

要将属性添加到特定事件，请使用函数中的additionalProperties参数log

Bolt.Analytics.log(.checkoutButtonTapped, ["merchantLoggedIn": true])

账户创建复选框

可以添加一个复选框到结算界面，以便用户在下订单时创建Bolt账户。为了在文本中添加图片，可以使用NSAttributedString和NSTextAttachment。提供了一个 SwiftUI 执行示例在CreateAccountView.swift。它使用UIViewRepresentable包装一个被设置为包含文本和Bolt标志的属性的UILabel。

示例应用

示例文件夹包含一个示例应用，演示了使用信用卡标记器、Bolt用户登录、结账分析以及账户创建复选框的使用。