开始使用 Connect 嵌入式组件
了解如何在您的网站中嵌入管理平台功能。
使用 Connect 嵌入式组件向您的网站添加关联账户管理平台功能。这些库及其支持的 API 允许您直接在您的管理平台和移动应用中为用户提供对 Stripe 产品的访问权限。
设置 StripeConnect客户端服务器端
Stripe 使用 AccountSession 来表达您将 API 访问权限授予 Connect 子账户的意图。
AccountSessions API 返回一个客户端密钥，允许嵌入式组件访问关联账户的资源，就像您在为它们进行 API 调用一样。
创建 AccountSession Server
您的应用必须向您的服务器发起请求才能获取账户会话。目前，仅支持账户注册。您可以在服务器上创建一个新端点，该端点将客户端密钥返回给应用：
创建 Account Session API
Create Account Session API 确定 Connect 嵌入式组件的组件和功能访问权限。Stripe 对与账户会话对应的任何组件都强制执行这些参数。如果您的应用支持多个用户角色，请确保为该账户会话启用的组件和功能与当前用户的角色相对应。例如，您可以只为您网站的管理员启用 refund management，而不能为其他用户启用。若要确保强制访问用户角色，必须将网站的用户角色映射到账户会话组件。
安装 StripeConnect SDK Client
Stripe iOS SDK 是开源的，有完整的文档，并且与支持 iOS 15 或更高版本操作系统的应用程序兼容。
设置相机授权 Client-side
Stripe Connect iOS SDK 要求访问设备的摄像头来捕捉身份文件。要使您的应用能够请求相机访问权限，请执行以下操作：
- 在 Xcode 中打开您项目的 Info.plist。
- 添加
NSCameraUsageDescription密钥。 - 添加一个字符串值，向用户解释为什么您的应用程序需要相机访问权限，例如：
该应用程序将使用相机拍摄您的身份证件照片。
查看 Apple 文档，了解有关请求相机授权的更多信息。
初始化 EmbeddedComponentManager Client
使用 StripeAPI. 设置您的公钥，并通过调用您在服务器上创建的新端点获取客户端密钥的闭包来实例化 EmbeddedComponentManager。要创建组件，请在您上面实例化的 EmbeddedComponentManager 上调用适当的创建方法。这将返回一个控制器，您可以使用它在应用中呈现该组件。
@_spi(PrivateBetaConnect) import StripeConnect import UIKit class MyViewController: UIViewController { let errorView: UIView func fetchClientSecret() async -> String? { let url = URL(string: "https://{{YOUR_SERVER}}/account_session")! var request = URLRequest(url: url) request.httpMethod = "POST" do { // Fetch the AccountSession client secret let (data, _) = try await URLSession.shared.data(for: request) let json = try JSONSerialization.jsonObject(with: data) as? [String : Any] errorView.isHidden = true return json?["client_secret"] as? String } catch let error { // Handle errors on the client side here print("An error occurred: \(error)") errorView.isHidden = false return nil } } override func viewDidLoad() { super.viewDidLoad() // This is your test publishable API key. STPAPIClient.shared.publishableKey = "{{PUBLISHABLE_KEY}}", let embeddedComponentManager = EmbeddedComponentManager( fetchClientSecret: fetchClientSecret ) let controller = embeddedComponentManager.createAccountOnboardingController() controller.present(from: self) } }
Configure the Embedded Component Manager客户端
参见代码参考 。
自定义 Connect 嵌入式组件的外观
嵌入式组件 Figma UI 工具包包含每个组件、常见模式和一个示例应用程序。您可以使用它来可视化和设计网站中的嵌入式用户界面。
我们提供了一组选项来定制 Connect 嵌入式组件的外观。这些定制会影响我们设计系统中的按钮、图标和其他元素。
必要的弹出窗口
嵌入式组件中的某些行为（例如用户验证）必须在经过验证的 WebView 中呈现。您无法定制嵌入式组件以消除此类 WebView。
初始化 EmbeddedComponentManager 时，可以使用 EmbeddedComponentManager.Appearance 设置这些选项。
func fetchClientSecret() async -> String? { let url = URL(string: "https://{{YOUR_SERVER}}/account_session")! var request = URLRequest(url: url) request.httpMethod = "POST" do { let (data, _) = try await URLSession.shared.data(for: request) let json = try JSONSerialization.jsonObject(with: data) as? [String : Any] return json?["client_secret"] as? String } catch { return nil } } // Specify custom fonts var customFonts: [CustomFontSource] = [] let myFont = UIFont(name: "My Font", size: 16)! let fontUrl = Bundle.main.url(forResource: "my-font-2", withExtension: "woff")! do { let customFontSource = try CustomFontSource(font: myFont, fileUrl: fontUrl) customFonts.append(customFontSource) } catch { print("Error loading custom font: \(error)") } // Customize appearance var appearance = EmbeddedComponentManager.Appearance() appearance.typography.fontfont.base = myFont appearance.typography.fontSizeBase = 16 // Unscaled font size appearance.colors.primary = UIColor { traitCollection in if traitCollection.userInterfaceStyle == .dark { UIColor(red: 0.455, green: 0.424, blue: 1.000, alpha: 1.0) } else { UIColor(red: 0.404, green: 0.365, blue: 1.000, alpha: 1.0) } } STPAPIClient.shared.publishableKey = "{{PUBLISHABLE_KEY}}", let embeddedComponentManager = EmbeddedComponentManager( appearance: appearance, fonts: customFonts, fetchClientSecret: fetchClientSecret )
当 Connect 嵌入式组件的 UITraitCollection 被更新时，使用动态提供程序的外观颜色会自动应用于 Connect 嵌入式组件，包括暗色模式和辅助功能对比度。默认外观不包括暗色模式颜色，因此您必须为 EmbeddedComponentManager 指定具有动态颜色的外观，才能在您的应用中支持暗色模式。
指定字体大小时，请使用针对设备的默认大小等级显示的未缩放字体大小。嵌入式组件会根据它的 UITraitCollection 自动缩放字号。
查看 iOS 上的外观选项完整列表。
使用自定义字体
如果您在应用程序中使用自定义字体（例如，从应用程序二进制文件中嵌入的 . 或 . 文件中），则必须在初始化 EmbeddedComponentManager 时指定传入 fonts 参数的 CustomFontSource 中的字体文件。这样 Connect 嵌入式组件便可以访问字体文件，从而正确呈现这些字体。
appearance 中指定的字体必须使用在初始化时传递到 EmbeddedComponentManager 的受支持的系统字体或 CustomFontSource 才能正确呈现。
参见参考文档 。
初始化后更新 Connect 嵌入式组件
调用 update 方法，更改初始化后嵌入式组件的外观：
var appearance = EmbeddedComponentManager.Appearance() appearance.colors.primary = UIColor.red manager.update(appearance: appearance)
验证
我们提供了一组 API 来管理 Connect 嵌入式组件中的账户会话和用户凭证。
刷新客户端私钥
在长时间运行的会话中，来自最初提供的客户端私钥的会话可能会过期。当它过期时，我们会自动用 fetchClientSecret 检索新的客户端私钥并刷新会话。您不需要传入任何额外参数。
func fetchClientSecret() async -> String? { var request = URLRequest(url: URL(string: "https://{{YOUR_SERVER}}/account_session")!) request.httpMethod = "POST" do { let (data, _) = try await URLSession.shared.data(for: request) let json = try JSONSerialization.jsonObject(with: data) as? [String : Any] return json?["client_secret"] as? String } catch let error { return nil } } STPAPIClient.shared.publishableKey = "{{PUBLISHABLE_KEY}}", let embeddedComponentManager = EmbeddedComponentManager( fetchClientSecret: fetchClientSecret )
本地化
Connect 嵌入式组件支持以下地区：
| 语言 | 区域代码 |
|---|---|
| 保加利亚语（保加利亚） | bg-BG |
| 中文（简体） | zh-Hans |
| 中文（繁体 - 香港） | zh-Hant-HK |
| 中文（繁体 - 台湾） | zh-Hant-TW |
| 克罗地亚语（克罗地亚） | hr-HR |
| 捷克语（捷克） | cs-CZ |
| 丹麦语（丹麦） | da-DK |
| 荷兰语（荷兰） | nl-NL |
| 英语（澳大利亚） | en-AU |
| 英语（印度） | en-IN |
| 英语（爱尔兰） | en-IE |
| 英语（新西兰） | en-NZ |
| 英语（新加坡） | en-SG |
| 英语（英国） | en-GB |
| 英语（美国） | en-US |
| 爱沙尼亚语（爱沙尼亚） | et-EE |
| 菲律宾语（菲律宾） | fil-PH |
| 芬兰语（芬兰） | fi-FI |
| 法语（加拿大） | fr-CA |
| 法语（法国） | fr-FR |
| 德语（德国） | de-DE |
| Greek (Greece) | el-GR |
| 匈牙利语（匈牙利） | hu-HU |
| 印度尼西亚语（印度尼西亚） | id-ID |
| 意大利语（意大利） | it-IT |
| 日语（日本） | ja-JP |
| 朝鲜语（韩国） | ko-KR |
| 拉脱维亚语（拉脱维亚） | lv-LV |
| 立陶宛语（立陶宛） | lt-LT |
| 马来语（马来西亚） | ms-MY |
| 马耳他语（马耳他） | mt-MT |
| 挪威语（波克默尔语）（挪威） | nb-NO |
| 波兰语（波兰） | pl-PL |
| 葡萄牙语（巴西） | pt-BR |
| 葡萄牙语（葡萄牙） | pt-PT |
| 罗马尼亚语（罗马尼亚） | ro-RO |
| 斯洛伐克语（斯洛伐克） | sk-SK |
| 斯洛文尼亚语（斯洛文尼亚） | sl-SI |
| 西班牙语（阿根廷） | es-AR |
| 西班牙语（巴西） | es-BR |
| 西班牙语（拉丁美洲） | es-419 |
| 西班牙语（墨西哥） | es-MX |
| 西班牙语（西班牙） | es-ES |
| 瑞典语（瑞典） | sv-SE |
| 泰语（泰国） | th-TH |
| 土耳其语（土耳其） | tr-TR |
| 越南语（越南） | vi-VN |
Connect 嵌入式组件中的用户身份验证
Connect 嵌入式组件通常不需要用户验证。在某些场景中，Connect 嵌入式组件要求关联账户在访问组件以提供必要功能之前使用其 Stripe 账户登录（例如，在账户注册组件中向账户法律实体写入信息的情况）。其他组件可能在首次呈现后需要在组件内进行验证。
当要求变更时，若由 Stripe 负责收集更新后的信息，则关联账户需要进行验证。对于要求到期或变更时由您负责收集更新后的信息的关联账户（如 Custom 账户），Stripe 验证由 disable_stripe_user_authentication 账户会话功能控制。我们建议将实施双重验证 (2FA) 或等效安全措施作为最佳实践。对于支持此功能的账户配置（如 Custom 账户），如果关联账户无法偿还负余额，则由您承担责任。
需要验证的组件
关联账户将在您的应用中看到经过验证的 WebView。关联账户必须先进行验证，才能在 WebView 中继续其工作流程。
Stripe 托管的验证流程会显示您在 Connect 设置中设置的品牌名称、颜色和图标，且在验证完成前不会使用来自嵌入式组件管理器的定制外观和字体。
以下组件要求关联账户在特定场景下进行验证：
处理加载错误
如果组件不加载，可以通过实施组件的 didFailLoadWithError 委托方法对失败做出反应。根据失败的原因，可能会多次调用 didFailLoadWithError 方法。由 didFailLoadWithError 触发的任何逻辑都必须是幂等的。
// All components emit load errors. This example uses AccountOnboarding. // All components support didFailLoadWithError. class MyViewController: UIViewController, AccountOnboardingControllerDelegate { func openAccountOnboarding() { let accountOnboardingController = embeddedComponentManager.createAccountOnboardingController(); accountOnboardingController.delegate = self accountOnboardingController.present(from: self) } // MARK: - AccountOnboardingControllerDelegate func accountOnboarding(_ accountOnboarding: AccountOnboardingController, didFailLoadWithError error: Error) { print("Account onboarding failed to load with error '\(error)'") } }