stigg-widgets

Stigg Widgets — 即插即用 UI

Stigg 提供预构建的 React 组件（自 v0.2.1 起支持 Next.js SSR）和用于最常见定价／账单 UI 场景的原生 JS 客户端 SDK。这些是呈现付费墙、客户门户、结账和信用额度余额 UI 的标准方式，无需从头构建。Vue 和 Embed SDK 也已推出，详见 docs.stigg.io；以下模式同样适用。

开始之前

根据总览 stigg 技能：先搜索。 Widget 属性会不断变化；Storybook 是实时的事实来源。

Agent 如何读取 Storybook

https://widgets.stigg.io/ 上的 Storybook 由 JavaScript 渲染（基本的 HTTP 获取只会返回标题）。但它提供了机器可读索引——GET https://widgets.stigg.io/index.json 会返回完整的 story ID 列表（格式为 widgets-<component>--<variant>）。每当用户提到 widgets 时，都应获取该索引，然后参阅 docs.stigg.io/documentation/snap-in-widgets/<widget> 下各 widget 的文档页面，了解属性和代码片段。

完整的 Agent 操作指南——发现工作流、story ID 类别、各 widget 的规范文档路径，以及基本的 WebFetch 为什么只会返回标题：references/storybook.md。

Widget 一览

Widget	用途	参考
付费墙／定价表	公开定价页面或应用内升级提示	references/paywall.md
客户门户	应用内自助服务：订阅、用量、账单、套餐选择器	references/customer-portal.md
结账	类似购物车的应用内支付体验	references/checkout.md
Credits widgets（余额、使用率、用量图表、授予额度表、自动充值状态、自动充值配置）	面向客户的信用额度池 UI	references/credit-widgets.md

设置

所有 widget 都应置于 <StiggProvider>（React）或其他框架 SDK 中的对应组件内。请使用可发布密钥（client-），切勿使用服务器密钥。

import { StiggProvider } from '@stigg/react-sdk';

export function App() {
  return (
    <StiggProvider apiKey="<STIGG_CLIENT_API_KEY>" customerId="<LOGGED_IN_CUSTOMER_ID>">
      <NestedComponents />
    </StiggProvider>
  );
}

Next.js：相同，@stigg/react-sdk 支持 SSR，无需单独的包。原生 JS：@stigg/js-client-sdk。Vue：@stigg/vue-sdk 采用相同的 provider 结构，详见 docs.stigg.io。

生产环境设置必须包含客户端安全加固（HMAC SHA256 签名的客户令牌）。请在可发布密钥的详情面板中进行配置。详见 stigg-api/references/auth.md。

组合：客户门户 + 付费墙

CustomerPortal 组件支持组合——将 Paywall 作为插槽／属性传入：

<CustomerPortal
  paywallComponent={<Paywall />}
  theme={...}
  textOverrides={...}
/>

这样便会使用相同的付费墙配置来设置门户中的“套餐选择器”部分。

组合：模块化客户门户

如果默认门户布局不适合你的应用，可在 CustomerPortalProvider 下分别组合各个部分：

import {
  CustomerPortalProvider,
  CustomerUsageData,
  PaymentDetailsSection,
  // SubscriptionsOverview, AddonsList, Promotions, InvoicesSection, ...
} from '@stigg/react-sdk';

function App() {
  return (
    <CustomerPortalProvider theme={...} textOverrides={...}>
      <CustomerUsageData />
      <PaymentDetailsSection />
    </CustomerPortalProvider>
  );
}

主题

有两种方式：

1. 无代码 Widget Designer：在 Stigg 应用中设置颜色、字体排版和布局。非工程团队成员也可以进行调整。
2. 代码级主题设置：在各组件上使用 theme={...} 属性，并使用自定义 CSS 定位文档中说明的 stigg 前缀类（例如 stigg-payment-details-section-layout、stigg-{plan.id}、stigg-compatible-addon-{addon.id}、stigg-entitlement-feature-{feature.id}）。

两种方式可以结合使用。请重新获取文档，以查看当前完整的 CSS 类列表。

文本覆盖

可以通过 textOverrides 覆盖默认文案：

const textOverrides = {
  manageSubscription: 'Manage',
  usageTabTitle: 'Usage',
  addonsTabTitle: 'Add-ons',
  promotionsTabTitle: 'Promotions',
  paywallSectionTitle: 'Plans',
  // ...
};

<CustomerPortal textOverrides={textOverrides} paywallComponent={<Paywall />} />

完整的键列表见文档——如需查找特定键，请搜索 text overrides。

多租户（多活跃订阅）

对于允许每位客户拥有多个订阅的产品（工作区／项目），请在各处传入 resourceId——包括 Paywall、CustomerPortal、Checkout 和 credit widgets：

<Paywall resourceId="workspace-abc" onPlanSelected={({ plan, customer }) => { ... }} />

<CustomerPortal
  resourceId="workspace-abc"
  paywallComponent={<Paywall resourceId="workspace-abc" />}
/>

还需要在 JS 客户端上调用 stigg.setResource('workspace-abc')（离开该上下文时调用 clearResource()），以确保权益检查按正确范围执行。

为付费墙选择渲染器

Stigg 的 Paywall 会通过 onPlanSelected 暴露客户的意图。请根据 intentionType 进行分支处理：

<Paywall
  onPlanSelected={({ plan, intentionType }) => {
    switch (intentionType) {
      case SubscribeIntentionType.START_TRIAL:
        // provision trial subscription
        break;
      case SubscribeIntentionType.REQUEST_CUSTOM_PLAN_ACCESS:
        // redirect to a contact form
        break;
      case SubscribeIntentionType.UPGRADE_PLAN:
      case SubscribeIntentionType.DOWNGRADE_PLAN:
        // open the Checkout widget or your custom flow
        break;
    }
  }}
/>

缓存刷新

执行会修改客户的操作（配置、更新、授予）后，JS 客户端上的缓存可能会短暂显示陈旧数据。SDK 提供了刷新方法——请参阅 React / JS SDK 页面中的缓存刷新部分。

何时不应使用此技能

• 在后端进行无头门控（无 UI）→ stigg-entitlements。
• 建模功能 / 计划 / 附加项 → stigg-pricing-modeling。
• 以编程方式配置 / 取消订阅 → stigg-subscriptions。
• 定义额度货币 / 授予额度 → stigg-credits。

常见错误

错误	修正方法
在小组件设置中嵌入服务器密钥	始终使用可发布密钥（前缀为 client-）。它在设计上为只读，可安全地随浏览器包发布。
在生产环境中跳过客户端安全措施	可发布密钥是公开可见的。请启用 HMAC 签名客户令牌。
在应用 UI 中硬编码计划名称 / 价格	使用小组件——它们会自动反映目录变更。硬编码副本会逐渐过时。
在支持多个有效订阅的产品上忘记设置 resourceId	小组件会针对错误的订阅（或不针对任何订阅）。对每个需要它的小组件都传入该参数。
尝试通过覆盖 <div> 选择器来设置小组件样式	使用文档中说明的 stigg-* CSS 类——它们稳定且使用了命名空间。
组合门户，却忘记使用 CustomerPortalProvider 包装	各子部分将无法访问客户 / 主题上下文。
凭记忆读取小组件属性，而不是查阅 Storybook	打开 https://widgets.stigg.io/index.json 查看实时故事列表，然后在浏览器中打开 Storybook UI 查看属性表。编写前请再次确认。
在没有有效订阅的情况下尝试渲染客户门户	某些部分（计划选择器 / 付费墙）可用；其他部分（付款详情 / 发票）则需要付费订阅或已连接的计费提供方。请在应用中妥善处理这种情况。