开始使用 Connect 嵌入式组件
了解如何在您的网站中嵌入管理平台功能。
用 Connect 嵌入式组件向您的网站添加 Connect 子账户管理平台功能。这些库及其支持的 API 允许您直接在管理平台中授予用户对 Stripe 产品的访问权限。
有关本指南的沉浸式版本，请参见 Connect 嵌入式组件集成快速指南。您也可以从那里下载一个示例集成应用。若要自定义 Connect 嵌入式组件的外观，请在初始化 StripeConnectInstance 时使用 appearance 选项。查看外观参数完整列表。
Initialize Connect.js客户端服务器端
Stripe uses an AccountSession to express your intent to delegate API access to your connected account.
AccountSessions API 返回一个客户端私钥，允许网页客户端内的嵌入式组件访问 Connect 子账户的资源，就好比是您为他们进行 API 调用一样。
创建 AccountSession Server
在单页面应用程序中，您的客户端向您的服务器发起获取账户会话的请求。您可以在服务器上创建新的端点，将客户端私钥返回到浏览器：
Create Account Session API
The Create Account Session API determines component and feature access for Connect embedded components. Stripe enforces these parameters for any components that correspond to the account session. If your site supports multiple user roles, make sure components and features that are enabled for that account session correspond to the current user’s role. For example, you can enable refund management only for administrators of your site, but not for other users. To ensure user role access are enforced, your backend must host the logic that maps your site’s user role to account session components.
设置 Connect.js Client
加载并初始化 Connect.js Client
通过调用您在服务器上创建的新端点，使用您的公钥和一个检索客户端私钥的函数调用 loadConnectAndInitialize。使用返回的 StripeConnectInstance 创建嵌入式组件。初始化 Connect.js 后，您可以随时在 DOM 中挂载或卸载组件。这包括 React 或 Vue 门户中呈现的任何元素。
配置 Connect.js客户端
客户端上 loadConnectAndInitialize 方法采用几个不同的选项来配置 Connect.js。
| 选项 | 描述 | |
|---|---|---|
publishableKey | 您的集成应用的公钥。 | 必填 |
fetchClientSecret | 该函数检索 /v1/account_ 返回的客户端私钥。它告诉 StripeConnectInstance 授权访问哪个账户。该函数还用于检索客户端私钥函数，以在会话到期时刷新会话。 | 必填 |
appearance | 一个用来自定义 Connect 嵌入式组件外观的对象。 | 可选 |
locale | 该参数用于指定 Connect 嵌入式组件所使用的区域。区域设置默认为浏览器的语言。如果不直接支持指定的区域设置，则使用一个合理的替代方案（例如，fr-be 可能回退到 fr-fr）。查看本地化，获取受支持区域的列表。 | 可选 |
fonts | 这是一个自定义字体数组，由 StripeConnectInstance 创建的任何嵌入式组件都可以使用。可以将字体指定为 CssFontSource 或 CustomFontSource 对象。 | 可选 |
自定义 Connect 嵌入式组件的外观
我们提供了一组选项来定制 Connect 嵌入式组件的外观。这些定制会影响我们设计系统中的按钮、图标和其他元素。
在初始化 StripeConnectInstance 时，可以通过向 appearance 对象传递值来设置这些选项。您只能用 Connect.js 选项来修改 Connect 嵌入式组件中的样式。Connect 嵌入式组件的字体系列和背景颜色是可以用 CSS 选择器覆盖的，但 Stripe 不支持覆盖任何其他样式。
const fetchClientSecret = async () => { const response = await fetch('/account_session'); const {client_secret: clientSecret} = await response.json(); return clientSecret; } const stripeConnectInstance = loadConnectAndInitialize({ publishableKey:, fetchClientSecret: fetchClientSecret, fonts: [ { cssSrc: "https://myfonts.example.com/mycssfile.css", }, { src: `url(https://my-domain.com/assets/my-font-2.woff)`, family: 'My Font' } ], appearance: { // See all possible variables below overlays: "dialog", variables: { fontFamily: 'My Font', colorPrimary: "#FF0000", }, }, });"pk_test_TYooMQauvdEDq54NiTphI7jx"
字体对象
stripeConnect. 中的 fonts 对象接受一个由 CssFontSource 或 CustomFontSource 对象组成的数组。
如果您在页面中使用自定义字体（即 . 或 . 文件），则必须在初始化 Connect 嵌入式组件时指定这些文件。这样做可以使 Connect 嵌入式组件正确呈现这些字体。您可以将它们指定为：
CssFontSource
创建 StripeConnectInstance 时，使用此对象传递定义自定义字体的样式表 URL。对于 CssFontSource 对象，您的 CSP 配置必须允许提取与指定为 CssFontSource 的 CSS 文件 URL 相关联的域名。
名称 | 类型 | 示例值 |
cssSrc | 字符串 required | https://fonts. |
一个指向具有 @font-face 定义的 CSS 文件的相对或绝对 URL。使用内容安全策略 (CSP)可能会强制执行附加指令。 | ||
CustomFontSource
创建 StripeConnectInstance 时，使用此对象传递定义自定义字体的样式。
名称 | 类型 | 示例值 |
family | 字符串 required | Avenir |
字体的名称。 | ||
src | 字符串 required | url(https://my-domain. |
一个指向您的自定义字体文件的有效 src 值。这通常（但不总是）是指向带有 .、. 或 . 后缀的文件的链接。 | ||
display | 字符串 optional | auto |
一个有效的 font-display 值。 | ||
style | 字符串 optional | normal |
normal、italic、oblique 中的一个。 | ||
unicodeRange | 字符串 optional | U+0-7F |
有效的 unicode-range 值。 | ||
weight | 字符串 optional | 400 |
一个有效的 font-weight。请注意，这是一个字符串，而非数字。 | ||
外观对象
loadConnectAndInitialize 中的 appearance 对象具有以下可选属性：
名称 | 类型 | 示例值 |
overlays | ‘dialog’（默认） | ‘drawer’ | dialog |
整个 Connect.js 设计系统中使用的覆盖类型。将此设置为 Dialog（对话框）或 Drawer（抽屉）。 | ||
variables | 对象 | {colorPrimary: "#0074D4"} |
请参见外观变量的完整列表。 | ||
初始化后更新 Connect 嵌入式组件
update 方法支持在初始化后更新 Connect 嵌入式组件。这对于在运行时切换外观选项非常有用（无需刷新页面）。为此，请使用您用 initialize 创建的同一个 stripeConnectInstance 对象，并对其调用 update 方法：
stripeConnectInstance.update({ appearance: { variables: { colorPrimary: "#FF0000", }, }, locale: 'en-US', });
备注
并非所有选项（如 fonts）都可更新。该方法支持的选项是 initialize 中提供的选项的子集。它支持更新 appearance 和 locale。
宽度和高度
Connect 嵌入式组件的行为类似于常规的 block HTML 元素。默认情况下，它们采用其父级 HTML 元素的 100% 宽度，并根据内部呈现的内容增加高度。您可以通过指定 HTML 父级的 width 来控制 Connect 嵌入式组件的 width。您不能直接控制 height，因为这取决于呈现的内容，但可以使用 maxHeight 和 overflow: scroll 来限制高度，就像其他 HTML block 元素一样。
验证
我们提供了一组 API 来管理 Connect 嵌入式组件中的账户会话和用户凭证。
刷新客户端私钥
在长时间运行的会话中，来自最初提供的客户端私钥的会话可能会过期。当它过期时，我们会自动用 fetchClientSecret 检索新的客户端私钥并刷新会话。您不需要传入任何附加参数。
import { loadConnectAndInitialize } from "@stripe/connect-js"; // Example method to retrieve the client secret from your server const fetchClientSecret = async () => { const response = await fetch('/account_session'); const {client_secret: clientSecret} = await response.json(); return clientSecret; } const stripeConnectInstance = loadConnectAndInitialize({ publishableKey: "{{PUBLISHABLE_KEY}}", fetchClientSecret: fetchClientSecret, });
退出
我们建议您在用户注销您的应用程序后调用 stripeConnectInstance 上的 logout 来销毁关联的账户会话对象。这将禁用链接到该 stripeConnectInstance 的所有 Connect 嵌入式组件。
// Call this when your user logs out stripeConnectInstance.logout();
CSP 和 HTTP 头的要求
如果您的网站实施了内容安全政策，您需要通过添加以下规则来更新该策略：
frame-srchttps://connect-js.stripe. com https://js.stripe. com img-srchttps://*.stripe. com script-srchttps://connect-js.stripe. com https://js.stripe. com style-srcsha256-0hAheEzaMe6uXIKV4EehS9pu1am1lj/KnnzrOYqckXk=(SHA of empty style element)
If you’re using a CSS file to load web fonts for use with Connect embedded components, its URL must be allowed by your connect-src CSP directive.
设置某些 HTTP 响应头 可启用 Connect 嵌入式组件的全部功能：
- Cross-Origin-Opener-Policy,
unsafe-none。此 (unsafe-none) 是标头的默认值，因此不设置此标头也可以。在 Connect embedded components 中，其他值如same-origin会破坏用户身份验证。
支持的浏览器
我们支持 Stripe 管理平台当前支持的相同浏览器：
- 最近 20 个主要版本的 Chrome 和 Firefox
- 最近两个主要版本的 Safari 和 Edge
- 移动 iOS 系统上最近两个主要版本的 Safari
Connect 嵌入式组件仅在 Web 浏览器中受支持，不能在移动或桌面应用程序内的嵌入式 Web 视图中使用。
本地化
初始化 Connect.js 时，可以传递一个 locale 参数。要将嵌入式组件的区域设置与您网站的区域设置进行匹配，请在 locale 参数中传递您的网站呈现用户界面的区域设置。
locale 参数的默认值由浏览器配置的区域设置确定。如果不直接支持指定的区域设置，则使用一个合理的替代方案（例如，fr-be 可能回退到 fr-fr）。
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 |
| 希腊语（希腊） | 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 |
处理加载错误
如果某个组件加载失败，可以通过向任意嵌入式组件提供一个加载错误处理程序来对该失败做出反应。根据失败原因的不同，可以多次调用加载错误处理程序。加载错误处理程序触发的任何逻辑都必须是幂等的。
The load error object
Every time there’s a load failure, an error object is passed to the load error handler with the following properties.
Name | Type | Example value |
type | authentication_ | |
The type of error | ||
message | string | undefined | Failed to fetch account session |
Further description about the error | ||
Types of load failures
When a component fails to load, we detect the type of failure and map it to one of the types below. If the load error type can’t be determined it is marked as an api_.
| Type | Description |
|---|---|
api_ | Failure to connect to Stripe’s API |
authentication_ | Failure to perform the authentication flow within Connect embedded components |
account_ | Account session creation failed |
invalid_ | Request failed with an 4xx status code, typically caused by platform configuration issues |
rate_ | Request failed because an abnormal request rate was detected |
api_ | API errors covering any other type of problem, such as a temporary problem with Stripe’s servers |
检测嵌入式组件的显示情况
创建组件后，只有在浏览器中加载并解析了该组件的 javascript 才会向用户显示任何用户界面。这可能会导致组件在完成加载后显示为弹出式页面。为避免这种情况，请在创建组件之前显示您自己的加载用户界面，并在显示组件后隐藏用户界面。所有嵌入式组件都可以接受在向用户显示用户界面之前立即调用的回调函数。
不使用前端 npm 包管理工具进行集成
我们建议与我们的 javascript 和 React 封装组件进行集成，它们简化了 Connect 嵌入式组件的加载并为我们支持的接口提供了 TypeScript 定义。如果您的构建系统当前不支持依赖工具包，则可以在没有这些工具包的情况下集成。
手动将 Connect.js 脚本标记添加到您的网站上每个页面的 <head>。
<!-- Somewhere in your site's <head> --> <script src="https://connect-js.stripe.com/v1.0/connect.js" async></script>
在没有 NPM 的情况下使用 Connect.js
Connect.js 加载完成后，它会初始化全局窗口变量 StripeConnect，并调用 StripeConnect.（如果您对此进行了定义）。您可以通过设置 onload 函数并用与 loadConnectAndInitialize 相同的 Connect.js options 调用 StripeConnect. 来安全地初始化 Connect.js。
window.StripeConnect = window.StripeConnect || {}; StripeConnect.onLoad = () => { const stripeConnectInstance = StripeConnect.init({ // This is a placeholder - it should be replaced with your publishable API key. // Sign in to see your own test API key embedded in code samples. // Don’t submit any personally identifiable information in requests made with this key. publishableKey:, fetchClientSecret: fetchClientSecret, }); const payments = stripeConnectInstance.create('payments'); document.body.appendChild(payments); };"pk_test_TYooMQauvdEDq54NiTphI7jx"
Connect 嵌入式组件中的用户身份验证
Connect 嵌入式组件通常不需要用户验证。在某些情况下，Connect 嵌入式组件要求 Connect 子账户使用其 Stripe 账户登录后才能提供必要的功能（例如，使用账户入驻 component)组件时，将信息写入账户的法律实体）。
验证过程中会弹出一个 Stripe 拥有的窗口。Connect 子账户必须先验证后才能继续他们的流程。
以下组件要求 Connect 子账户在某些情况下进行验证：
其他组件可能会在最初呈现后要求在组件内进行身份验证。对于 Stripe 负责在要求发生变化时向其收集最新信息的 Connect 子账户，需要对这些组件和场景进行验证。对于您负责在要求到期或发生变化时向其收集最新信息的 Connect 子账户，Stripe 验证由 disable_stripe_user_authentication Account Session 功能控制。我们建议实施双重验证或同等安全措施作为一种最佳做法。对于支持此功能的账户配置（例如 Custom），如果 Connect 子账户不能偿还负余额，那么需要由您承担。