积分
如何在 MkSaaS 中设置和使用积分系统
MkSaaS 提供了一个灵活、模块化的积分系统,用于奖励用户、启用按使用付费功能,并支持各种商业模式。本文档解释了如何在 MkSaaS 中启用、配置和使用积分系统。
设置
开始使用积分系统:
- 在配置中启用积分
- 打开
src/config/website.tsx
并找到credits
部分。 - 设置
enableCredits: true
以启用积分系统。 - 设置
enableForFreePlan: true
以允许免费用户购买积分,默认只有付费订阅用户可以购买积分套餐。 - 设置
registerGiftCredits
以配置注册时是否赠送积分、赠送的积分数量和过期时间。
- 打开
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,
},
// ...其他套餐
},
},
// ...其他配置
}
- 配置产品价格计划中的积分
- 在
src/config/website.tsx
中找到price.plans
部分。 - 设置
credits
字段为true
以启用这个价格计划中的积分。 - 设置
amount
字段为100
以设置这个价格计划中的积分数量。
export const websiteConfig = {
// ...其他配置
price: {
plans: {
free: {
id: 'free',
// ...其他配置
isFree: true,
isLifetime: false,
credits: {
enable: true,
amount: 50,
expireDays: 30,
},
},
// ...其他价格计划
},
},
// ...其他配置
}
- 配置积分套餐
- 在
credits.packages
下定义积分套餐,默认有 4 个积分套餐。 - 每个套餐包括
id
、积分数量
、价格
(Stripe priceId,见下面的设置 Stripe 价格 ID
)和可选字段如popular
、expireDays
。 - 货币单位为美元,目前仅支持美元。
- 在
packages: {
basic: {
id: 'basic',
credits: 100,
price: {
priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC!,
amount: 990,
currency: 'USD',
},
popular: false,
expireDays: 30,
},
// ...
}
- 设置 Stripe价格 ID
- Stripe 价格 ID 用于将积分套餐链接到 Stripe 产品和价格。
- 在 Stripe Dashboard 中创建一个新产品,并为每个积分套餐设置价格。
- 将每个积分套餐的 Stripe 价格 ID 添加到
.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_...
- 为积分套餐设置翻译
- 在
src/config/credits-config.tsx
中定义积分套餐名称和描述。 - 对应的是不同语言的翻译文件,例如
src/messages/en.json
、src/messages/zh.json
等。
- 在
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;
}
- 设置定时发放积分的任务
如果你的产品满足下面的条件之一,那么你需要设置定时发放积分的任务。
- 产品的价格计划中有免费计划,并且免费用户每个月都可以免费领取积分
- 产品的价格计划中有终身制计划,并且终身制用户每个月都可以领取积分
- 产品的价格计划中有按年订阅计划,并且订阅用户每个月都可以领取积分
请参考 Cron Jobs 文档,设置定时发放积分的任务。
如果您正在设置环境,现在可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。
环境配置
设置环境变量
积分系统架构
积分系统是模块化的,由以下组件组成:
credits.ts
types.ts
client.ts
server.ts
这种架构允许您:
- 定义和管理积分套餐
- 跟踪用户积分余额和交易
- 与 Stripe 集成进行积分购买
- 使用 Server Action进行安全的积分操作
- 通过 hooks 和 stores 在 React 组件中访问积分状态
核心功能
- 购买积分:用户如果积分不足可以购买积分套餐。
- 注册赠送积分:可选择为新用户赠送积分。
- 积分过期:为每个套餐或赠品设置积分过期天数。
- 跟踪积分余额:安全查询当前用户积分。
- 积分交易:查看详细的交易历史(购买、使用、过期等)。
- 自定义套餐:定义任意数量的套餐,具有不同的数量、价格和属性。
- 国际化:支持翻译的套餐名称和描述。
- 安全 Server Action:所有积分操作都受到保护和验证。
- Zustand Store:在应用程序中全局管理积分状态,并通过 hooks 在 React 组件中使用。
最佳实践
- 仅在需要时启用:仅当您的商业模式需要积分时才设置
enableCredits: true
。 - 验证所有操作:使用提供的 Server Action 进行所有积分操作以确保安全性和验证。
- 自定义套餐:调整积分数量、价格和过期时间以适合您的用例。
- 跟踪交易:使用交易日志来审计和调试积分使用。
- 处理过期:如果您希望积分过期,请为套餐或赠品设置
expireDays
。 - 国际化:在 UI 中使用翻译 hooks 处理套餐名称和描述。
- 错误处理:始终处理错误并在 UI 中显示用户友好的消息。
下一步
现在您了解了如何在 MkSaaS 中使用积分,您可能想要探索这些相关功能: