# @funnelsgrove/sdk 中文文档

规范地址：https://npmcn.com/package/%40funnelsgrove/sdk/

版本：0\.4\.0
npm 元数据更新时间：2026-09-17T12:22:25.669Z
中文译文更新时间：2026-11-15T19:11:27.054Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40funnelsgrove/sdk
原文对照：https://npmcn.com/package/%40funnelsgrove/sdk/?lang=original
项目主页：https://github.com/The-Solid-Grove/funnelsgrove#readme
源码仓库：https://github.com/The-Solid-Grove/funnelsgrove

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：16.4 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-09-16T16:04:36.067Z
- 最新版本发布：2026-09-17T12:22:25.521Z
- 近 30 天下载量：4939（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

在网络应用程序中嵌入漏斗Grove付费墙

## 安装

```sh
npm install @funnelsgrove/sdk
```

也可以使用：`pnpm add @funnelsgrove/sdk`、`yarn add @funnelsgrove/sdk`、`bun add @funnelsgrove/sdk`

## README

# @ funnelsgrove/ sdk (英语)

在网络应用中直接嵌入已出版的FunnelsGrove付费墙. 没有后端, 需要密钥,或付费墙会话。 一揽子计划没有框架依赖性.

```sh
npm install @funnelsgrove/sdk
```

执行是释放候选人。 npm 目前包含 仅限元数据 `0.0.0-bootstrap.0` 保留,没有可执行的SDK代码.

## 在前端挂载

```ts
import { mountPaywall } from '@funnelsgrove/sdk';

const paywall = mountPaywall({
  container: '#paywall',
  paywallUrl: 'https://pay.example.com/paywall',
  ...(currentUser.funnelsGroveUserId
    ? { userId: currentUser.funnelsGroveUserId }
    : { email: currentUser.email }),
  returnUrl: '/billing/complete',
  onReady: ({ userId }) => console.log('Paywall ready for FG user', userId),
  onComplete: () => console.log('Payment confirmed'),
  onError: (error) => showPaymentError(error.message),
});

// On route change, modal close, or component cleanup:
paywall.destroy();
```

`paywallUrl` 是已公布的付费墙路由,没有查询参数或一个 碎片。 生产中使用HTTPS;支持本地host HTTP进行开发. 已出版的漏斗供应其公开的FG密钥和漏斗配置.

提供 FG `userId` 或电子邮件. `userId` 是现有的 FG 公开 `user_id`范围 到这个漏斗和测试/生活环境。 这不是你申请的账号 或者FG的内部行ID。 未知的ID 失败而不创建用户或退后 到电子邮件。 仅通过电子邮件,FG实现常态化并再用,或创建犬类用户. 同一邮件的同步请求汇合到一个用户上 。 如果两个字段都是 但是,它们必须匹配或解析失败。 决议不会改变 现有用户的电子邮件或购买历史. `onReady({ userId })` 显示选中的 FG ID; 挂载保存用于后续的提供者返回 。 如果电子邮件表在 paywall 解决另一个所有者, 它显示在 iframe 内部的冲突并保留 当前购买者; 从应用程序中重新打开以选择不同的账户.

这遵循了FG的公测身份模式. 浏览器提供的ID/电子邮件不是 证明一个经认证的应用账户的所有权。 此 SDK 不改变 现有公共用户API的访问模式.

## 补全并返回 URL

`returnUrl` 是可选的。 相对的 URL 在应用页面中解决 。 在FG之后 校验成功离职,SDK呼叫 `onComplete` 每个挂载一次 导航父窗口到 `returnUrl`。没有它,呼叫者处理 导航 尚未支付或未支付的付款没有重新定向。 目的地被保留下来了 ; 无法替换儿童信息。 已配置的重定向仍然运行 若为 `onComplete` 抛出; 使用回调同步通知和处理 在您的应用程序中调用错误 .

使用已核实的帐单webhooks/订阅状态来批准和取消访问, 包括延期和取消。 浏览器调用和重定向只告诉 用来刷新状态的应用程序.

`onError` 收到一个 `PaywallError` 与 `code`数字 :

-   `paywall_unavailable`:重开付费墙或纠正其配置/身份.
-   `confirmation_pending`: 保留框并使用 **检查付款状况**。 。 。 .
-   `payment_failed`: 保留机框让买家再试一次.

SDK 检查消息来源、发送窗口和 iframe 实例,并调整 iframe高处. 设置使用 `postMessage`; 用户身份和 应用程序返回 URL 在 ifram/ 提供者 URL 中缺失 。 提供者的成功/失败 返回 重新装入 FG 付费墙并恢复原挂载的设置 亲子关系。 在重定向时保持母机挂起 。 被替换的父母或 提供者返回到顶级窗口需要从应用程序重新打开. 固门还原也使用了 `sessionStorage` 用于其退出 ID; 被屏蔽 存储可以防止重定向恢复。 内置取出不需要存储 .

## 支付安排和推出

漏斗使用其现有的 Stale/ Solidgate 检查出局,包括符合条件 钱包。 iframe已经 `allow="payment *"`登记/核查应用程序和漏斗 用于 Apple Pay 的域名,并与提供者配置 Google Pay 。 托管 `frame-ancestors` 应用 `frame-src` 政策必须允许预期的起源. 真正的钱包和 3DS 需要提供者/浏览器接受; 本地定着不 建立这种支持.

按依赖顺序公布SDK、运行时间、分析和付款,部署 匹配 API,然后重建目标漏斗。 旧漏斗不懂 这个嵌入式协议。 API 图像在本地 SDK/ 运行时 tarball 之前创建本地 SDK/ runtime tarball npm发布,但促销的CLI门需要公布的包件文物.

这是一套无害环境管理方案。 类型脚本支持 `moduleResolution: "NodeNext"` 或者说 `"Bundler"`。没有导入服务器; `@funnelsgrove/sdk/embed` 是内部 FG跑时桥. 犬科行为和测试绘图在 [`docs/product-specs/sdk.md`](https://npmcn.com/package/docs/product-specs/sdk.md#embedded-paywalls)。 。 。 .

## 常见问题

### @funnelsgrove/sdk 是什么？

在网络应用程序中嵌入漏斗Grove付费墙

### 如何安装 @funnelsgrove/sdk？

在项目目录运行 npm install @funnelsgrove/sdk，或使用 pnpm add / yarn add / bun add。

### @funnelsgrove/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @funnelsgrove/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @funnelsgrove/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @funnelsgrove/sdk 可以商用吗？

@funnelsgrove/sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @funnelsgrove/sdk 的下载量有多少？

根据 npm 官方下载统计，@funnelsgrove/sdk 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,939 次，日均约 165 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @funnelsgrove/sdk 还在维护吗？

最新版本 0\.4\.0 发布于 2026/09/17（1 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/09/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。