用途:在 React 前端渲染定价并打开 Freemius Checkout 叠加层,让用户购买订阅或一次性/充值(积分)产品,结果由服务端同步。
主要能力:提供 CheckoutProvider(持有单个叠加层实例,暴露 useCheckout())、Subscribe(订阅定价表,含月/年切换)、Topup(一次性/充值定价表,billing_cycle 为 lifetime)、Paywall(功能受限时展示对应表格)以及自定义按钮。定价数据来自服务端 GET /api/checkout/pricing,前端不直接调用 Freemius API。
使用方式:安装前端 SDK:npm install @freemius/checkout。用服务端创建的 checkout 初始化 Provider,并指定 syncEndpoint="/api/purchase" 与 onPurchase 回调;调用 useCheckout().open({ plan_id, billing_cycle, show_confirmation_dialog: false }) 打开叠加层。组件以可编辑的 shadcn/ui 风格源码提供,可通过 npx shadcn@latest add https://shadcn.freemius.com/all.json 安装;非 shadcn/React 应用可下载 Starter Kit 作为参考自行实现。
限制与注意:叠加层是浏览器中唯一运行的部分,secretKey/apiKey 不得进入客户端;购买成功回调 POST 到后端,由后端重新获取权威购买并更新权益,付费墙在服务端以 HTTP 402 强制。叠加层同步与托管重定向是两个独立端点,不可合并。沙箱模式由 FREEMIUS_SANDBOX 环境变量控制,接受测试信用卡。计划与定价以 Freemius Dashboard 为唯一来源;充值模态需产品中存在仅 lifetime 价格的计划。已订阅用户不应看到普通订阅按钮,以免重复扣费。具体框架适配与端点细节见对应参考文档。