LogoMkSaaS文档

积分

如何在 MkSaaS 中设置和使用积分系统

MkSaaS 提供了一个灵活、模块化的积分系统,用于奖励用户、启用按使用付费功能,并支持各种商业模式。本文档解释了如何在 MkSaaS 中启用、配置和使用积分系统。

设置

开始使用积分系统:

  1. 在配置中启用积分
    • 打开 src/config/website.tsx 并找到 credits 部分。
    • 设置 enableCredits: true 以启用积分系统。
    • 设置 enableForFreePlan: true 以允许免费用户购买积分,默认只有付费订阅用户可以购买积分套餐。
    • 设置 registerGiftCredits 以配置注册时是否赠送积分、赠送的积分数量和过期时间。
src/config/website.tsx
export const websiteConfig = {
  // ...其他配置
  credits: {
    enableCredits: true, // 启用积分系统
    enableForFreePlan: true, // 允许免费用户购买积分
    registerGiftCredits: {
      enable: true, // 注册时赠送积分
      credits: 10, // 赠送的积分数量
      expireDays: 30, // 可选:积分过期天数
    },
    packages: {
      basic: {
        id: 'basic',
        credits: 100,
        price: {
          priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC!,
          amount: 990,
          currency: 'USD',
        },
        popular: false,
      },
      // ...其他套餐
    },
  },
  // ...其他配置
}
  1. 配置产品价格计划中的积分
  • src/config/website.tsx 中找到 price.plans 部分。
  • 设置 credits 字段为 true 以启用这个价格计划中的积分。
  • 设置 amount 字段为 100 以设置这个价格计划中的积分数量。
src/config/website.tsx
export const websiteConfig = {
  // ...其他配置
  price: {
    plans: {
      free: {
        id: 'free',
        // ...其他配置
        isFree: true,
        isLifetime: false,
        credits: {
          enable: true,
          amount: 50,
          expireDays: 30,
        },
      },
      // ...其他价格计划
    },
  },
  // ...其他配置
}
  1. 配置积分套餐
    • credits.packages 下定义积分套餐,默认有 4 个积分套餐。
    • 每个套餐包括 id积分数量价格(Stripe priceId,见下面的 设置 Stripe 价格 ID)和可选字段如 popularexpireDays
    • 货币单位为美元,目前仅支持美元。
src/config/website.tsx
packages: {
  basic: {
    id: 'basic',
    credits: 100,
    price: {
      priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC!,
      amount: 990,
      currency: 'USD',
    },
    popular: false,
    expireDays: 30,
  },
  // ...
}
  1. 设置 Stripe价格 ID
    • Stripe 价格 ID 用于将积分套餐链接到 Stripe 产品和价格。
    • 在 Stripe Dashboard 中创建一个新产品,并为每个积分套餐设置价格。
    • 将每个积分套餐的 Stripe 价格 ID 添加到 .env 文件中:
.env
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_STANDARD=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_PREMIUM=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_ENTERPRISE=price_...

Credits

  1. 为积分套餐设置翻译
    • src/config/credits-config.tsx 中定义积分套餐名称和描述。
    • 对应的是不同语言的翻译文件,例如 src/messages/en.jsonsrc/messages/zh.json 等。
src/config/credits-config.tsx
export function getCreditPackages(): Record<string, CreditPackage> {
  const t = useTranslations('CreditPackages');
  const creditConfig = websiteConfig.credits;
  const packages: Record<string, CreditPackage> = {};

  // 为每个计划添加翻译内容
  if (creditConfig.packages.basic) {
    packages.basic = {
      ...creditConfig.packages.basic,
      name: t('basic.name'),
      description: t('basic.description'),
    };
  }

  // 在这里添加其他套餐...
  return packages;
}
  1. 设置定时发放积分的任务

如果你的产品满足下面的条件之一,那么你需要设置定时发放积分的任务。

  • 产品的价格计划中有免费计划,并且免费用户每个月都可以免费领取积分
  • 产品的价格计划中有终身制计划,并且终身制用户每个月都可以领取积分
  • 产品的价格计划中有按年订阅计划,并且订阅用户每个月都可以领取积分

请参考 Cron Jobs 文档,设置定时发放积分的任务。

如果您正在设置环境,现在可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。

环境配置

设置环境变量


积分系统架构

积分系统是模块化的,由以下组件组成:

credits.ts
types.ts
client.ts
server.ts

这种架构允许您:

  • 定义和管理积分套餐
  • 跟踪用户积分余额和交易
  • 与 Stripe 集成进行积分购买
  • 使用 Server Action进行安全的积分操作
  • 通过 hooks 和 stores 在 React 组件中访问积分状态

核心功能

  • 购买积分:用户如果积分不足可以购买积分套餐。
  • 注册赠送积分:可选择为新用户赠送积分。
  • 积分过期:为每个套餐或赠品设置积分过期天数。
  • 跟踪积分余额:安全查询当前用户积分。
  • 积分交易:查看详细的交易历史(购买、使用、过期等)。
  • 自定义套餐:定义任意数量的套餐,具有不同的数量、价格和属性。
  • 国际化:支持翻译的套餐名称和描述。
  • 安全 Server Action:所有积分操作都受到保护和验证。
  • Zustand Store:在应用程序中全局管理积分状态,并通过 hooks 在 React 组件中使用。

最佳实践

  1. 仅在需要时启用:仅当您的商业模式需要积分时才设置 enableCredits: true
  2. 验证所有操作:使用提供的 Server Action 进行所有积分操作以确保安全性和验证。
  3. 自定义套餐:调整积分数量、价格和过期时间以适合您的用例。
  4. 跟踪交易:使用交易日志来审计和调试积分使用。
  5. 处理过期:如果您希望积分过期,请为套餐或赠品设置 expireDays
  6. 国际化:在 UI 中使用翻译 hooks 处理套餐名称和描述。
  7. 错误处理:始终处理错误并在 UI 中显示用户友好的消息。

下一步

现在您了解了如何在 MkSaaS 中使用积分,您可能想要探索这些相关功能: