> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subotiz SDK

<Info>
  **文档索引**

  获取完整文档索引：[https://developer.subotiz.com/llms.txt](https://developer.subotiz.com/llms.txt)
  您可以通过该文件了解全部可用页面，再进一步浏览所需内容。
</Info>

## 使用说明

### CDN地址

```text theme={null}
https://cdn.subotiz.com/static/subotiz/v0/subotiz.js
```

### SDK实例化

通过以下代码完成SDK实例创建：

```javascript theme={null}
const subotiz = window.Subotiz()
```

### 预热Checkout（推荐）

此方法用于提前加载Checkout所需资源，使后续打开Checkout时首屏展示更快。

`prewarm`是挂载在`Subotiz`上的**静态方法**，无需创建SDK实例即可调用。预热在页面空闲时进行，不影响您页面的正常加载。

<Tip>
  **建议在引入subotiz.js后尽早调用**，无需等待`initEmbeddedCheckout`，以预留充足的预热时间。
</Tip>

#### 方法调用示例

```html theme={null}
<!-- 引入SDK，建议异步加载以避免阻塞页面 -->
<script
  async
  src="https://checkout.subotiz.com/static/subotiz/v0/subotiz.js"
  onload="window.Subotiz.prewarm({ environment: 'PRODUCTION' })"
></script>

<!-- 自定义域名商家： -->
<!--
<script
  async
  src="https://checkout.subotiz.com/static/subotiz/v0/subotiz.js"
  onload="window.Subotiz.prewarm({ checkoutUrl: 'https://pay.merchant.com' })"
></script>
-->
```

#### 参数说明

Options (可选) object类型

| 属性          | 类型                       | 必填 | 默认值        | 描述                                                                                         |
| ----------- | ------------------------ | -- | ---------- | ------------------------------------------------------------------------------------------ |
| environment | 'SANDBOX' ｜ 'PRODUCTION' | 否  | 'SANDBOX'  | 当前环境设置，需与初始化Checkout时保持一致<br />'SANDBOX' - 沙盒环境（默认值）<br />'PRODUCTION'  - 生产环境             |
| checkoutUrl | string                   | 否  |            | 自定义Checkout域名，提供时优先于`environment`。<br />**必须与后续实际使用的Checkout域名一致**，否则预热不生效                 |
| trigger     | 'domready' ｜ 'immediate' | 否  | 'domready' | 预热触发时机<br />'domready' - 页面DOM就绪后自动预热（默认值，推荐）<br />'immediate' - 调用后立即预热，适用于您希望自行控制预热时机的场景 |

### 初始化嵌入式Checkout

此方法用于初始化嵌入式Checkout支付组件，返回Checkout实例。

#### 方法调用示例

```javascript theme={null}
const checkout = await subotiz.initEmbeddedCheckout({
    fetchSessionUrl: async() =>{
        // 从服务端获取sessionURL示例
        const response = await fetch('/api/session');
        const data = await response.json();
        return data.sessionUrl;
    },
    environment: 'SANDBOX',  // 'SANDBOX' | 'PRODUCTION'
    
});
```

#### 参数说明

Options (必传) object类型

| 属性              | 类型                       | 必填 | 默认值       | 描述                                                                                                                                             |
| --------------- | ------------------------ | -- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| fetchSessionId  | `()=>Promise<string>`    | 否  |           | 回调函数 `fetchClientSecret() => Promise<string>` 获取 Checkout Session id。<br />`fetchSessionId`与`fetchSessionUrl`必须要提供⼀个，同时提供时仅调⽤`fetchSessionId`  |
| fetchSessionUrl | `()=>Promise<string>`    | 否  |           | 回调函数 `fetchClientSecret() => Promise<string>` 获取 Checkout Session URL。<br />`fetchSessionId`与`fetchSessionUrl`必须要提供⼀个，同时提供时仅调⽤`fetchSessionId` |
| environment     | 'SANDBOX' ｜ 'PRODUCTION' | 否  | 'SANDBOX' | 当前环境设置<br />'SANDBOX' - 沙盒环境（默认值）<br />'PRODUCTION'  - 生产环境                                                                                    |
| onComplete      | ()=>void                 | 否  |           | 支付完成时的回调函数仅在创建Checkout Session时将`redirect_on_completion` 设置为 `if_required` 时触发，即用户不接受自动重定向时触发该回调                                               |

### 挂载Checkout组件

需先创建容器DOM元素，再将Checkout组件挂载到该容器中。

#### 操作示例

```html theme={null}
<!-- 创建容器 -->
<div id="your_domElement">
  <!-- Checkout组件将在此处显示 -->
</div>

<script>
  // 挂载组件
  checkout.mount('#your_domElement');
</script>
```

#### 参数说明

* selector **必传** string类型，容器元素的CSS选择器（如`#your_domElement`）

### 卸载Checkout组件

从DOM中卸载已挂载的Checkout组件，后续可通过`mount`重新挂载。

```javascript theme={null}
checkout.unmount();
```