# JS SDK 参考

## 初始化配置

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| container | 是 | DOM 元素或 CSS 选择器，需有明确高度 |
| item | 是 | 检视三档只接受 `{inspect:string}`；editor 另可接受 `{query:string}` |
| tier | 是 | inspect / first_person / third_person / editor |
| getGrant | 是 | 异步回调，调用厂商后端获取短期凭证 |
| embedUrl | 否 | 默认 https://www.cs2view.com/embed；本地只允许 loopback HTTP |
| title | 否 | iframe 的无障碍名称 |
| timeoutMs | 否 | 握手超时，默认 20000；不是下载超时 |

`getGrant` 收到 `openId`、`item`、`tier`、`parentOrigin` 与 `AbortSignal`。取消后不要继续返回旧凭证。SDK 核验 iframe 来源、窗口身份、消息版本和 channel。

## 方法

| 方法 | 行为 |
| --- | --- |
| on(event, listener) | 注册事件，返回取消订阅函数 |
| load(item, tier?) | 创建一次新的收费访问，切换物品；即使参数相同也算新访问 |
| retry() | 重试当前访问的凭证申请或渲染，不自动创建新收费访问 |
| setView(view) | 切换已授权视角；未授权档位会抛错 |
| pause() | 暂停渲染；访问无固定时长限制 |
| resume() | 恢复；不创建新访问 |
| destroy() | 返回 Promise，通知关闭会话并移除 iframe，重复调用安全 |

iframe 重载会产生新的 openId 并重新申请进入。普通框架重渲染时请保留同一个实例。组件销毁时调用 destroy；切换物品时明确调用 load。

## 事件

| 事件 | 数据 | 含义 |
| --- | --- | --- |
| ready | openId | 查看器已准备握手，尚未扣费 |
| authorized | visitId、tier、expiresAt | 本次进入已获准，已产生计费用量；expiresAt 固定为 null |
| progress | percent、label | 加载进度；percent 可为空 |
| loaded | visitId | 当前物品已经显示 |
| error | code、message | 申请、加载或运行错误 |
| expired | code、message | 访问被关闭或撤销，需要用户重新进入；不表示计时到期 |
| view | view | 视角改变 |

隐藏标签页或离开可视区域时 SDK 自动暂停，手动 pause 的状态优先。暂停不会免除已经产生的费用，没有会话倒计时。

## 物品输入

```js
// 仅独立编辑器（tier:'editor'）可使用参数。
{query:'skin=skin%3A7%3A1171&wear=0.1&seed=50&scene=warehouse'}

// 三个检视档只能使用包含物品数据的 Steam 检视链接（编辑器也接受）。
{inspect:'steam://rungame/730/76561202255233023/+csgo_econ_action_preview%20<hex>'}

// 也可提供对应的纯十六进制检视数据。
{inspect:'<hex>'}
```

仅 editor 的 query 支持物品、wear/seed、StatTrak、贴纸、挂件、探员、手套、场景和已授权视角等现有参数。旧的 S/A/D 或 M/A/D 链接不属于本版凭证输入范围。只读检视内不能改武器、手套、探员、印花、挂件或其参数；由厂商调用 load 传入新链接才能开启另一访问。嵌入页不显示 QQ 群、联系我们和 ICP。渲染器自身对不支持的物品属性仍可报错；通过凭证校验不等于游戏像素验收。