Back to Details

autumn-add-usage-tracking

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Autumn Usage Tracking

Autumn使用追踪

Always consult docs.useautumn.com for code examples and latest API.
Autumn tracks feature usage and enforces limits. Backend checks required for security.
如需代码示例和最新API，请务必参考docs.useautumn.com。
Autumn可追踪功能使用情况并执行限制。出于安全考虑，必须进行后端校验。

Quick Reference

快速参考

Core Pattern

核心模式

check → work → track
check → work → track

Check Response

校验响应

FieldDescription
allowed
Can customer proceed
balance
Units remaining
included_usage
Total usage included in plan
unlimited
No limit enforced
字段描述
allowed
客户是否可继续操作
balance
剩余可用额度
included_usage
套餐包含的总使用额度
unlimited
无使用限制

Feature Types

功能类型

TypeBehavior
boolean
Access granted or denied
metered
Usage tracked against limit
credit_system
Pool for multiple features
类型行为
boolean
授予或拒绝访问权限
metered
根据限制追踪使用情况
credit_system
为多个功能提供共享额度池

Security Model

安全模型

LayerPurposeTrust
FrontendUX (show/hide UI)Untrusted
BackendEnforcementRequired
层级用途可信度
前端用户体验（显示/隐藏UI）不可信
后端执行权限限制必须依赖（可信）

Backend Implementation

后端实现

typescript
import { Autumn } from "autumn-js";

const autumn = new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY });

// 1. Check
const { data } = await autumn.check({ customer_id, feature_id: "api_calls" });
if (!data.allowed) return { error: "Limit reached" };

// 2. Work
const result = await doWork();

// 3. Track
await autumn.track({ customer_id, feature_id: "api_calls", value: 1 });
return result;
python
from autumn import Autumn

autumn = Autumn('am_sk_test_xxx')

response = await autumn.check(customer_id="user_123", feature_id="api_calls")
if not response.allowed:
    raise HTTPException(403, "Limit reached")

result = await do_work()
await autumn.track(customer_id="user_123", feature_id="api_calls", value=1)
typescript
import { Autumn } from "autumn-js";

const autumn = new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY });

// 1. Check
const { data } = await autumn.check({ customer_id, feature_id: "api_calls" });
if (!data.allowed) return { error: "Limit reached" };

// 2. Work
const result = await doWork();

// 3. Track
await autumn.track({ customer_id, feature_id: "api_calls", value: 1 });
return result;
python
from autumn import Autumn

autumn = Autumn('am_sk_test_xxx')

response = await autumn.check(customer_id="user_123", feature_id="api_calls")
if not response.allowed:
    raise HTTPException(403, "Limit reached")

result = await do_work()
await autumn.track(customer_id="user_123", feature_id="api_calls", value=1)

React Implementation

React实现

tsx
import { useCustomer } from "autumn-js/react";

const { check, refetch } = useCustomer();

const handleAction = async () => {
  const { data } = await check({ featureId: "messages" });
  if (!data?.allowed) {
    showUpgradePrompt();
    return;
  }
  
  await performAction();
  await refetch();
};
tsx
import { useCustomer } from "autumn-js/react";

const { check, refetch } = useCustomer();

const handleAction = async () => {
  const { data } = await check({ featureId: "messages" });
  if (!data?.allowed) {
    showUpgradePrompt();
    return;
  }
  
  await performAction();
  await refetch();
};

Displaying Usage

显示使用情况

tsx
const { customer } = useCustomer();
const feature = customer?.features?.api_calls;

<p>{feature?.balance} / {feature?.included_usage}</p>
tsx
const { customer } = useCustomer();
const feature = customer?.features?.api_calls;

<p>{feature?.balance} / {feature?.included_usage}</p>

Credit Systems

信用系统

Track the underlying metered feature, not the credit system:
typescript
// Config: credits → api_calls (1), image_gen (10)

// Wrong
await autumn.track({ customer_id, feature_id: "credits", value: 10 });

// Right - Autumn deducts 10 credits automatically
await autumn.track({ customer_id, feature_id: "image_gen", value: 1 });
请追踪底层的计量型功能，而非信用系统本身：
typescript
// Config: credits → api_calls (1), image_gen (10)

// Wrong
await autumn.track({ customer_id, feature_id: "credits", value: 10 });

// Right - Autumn deducts 10 credits automatically
await autumn.track({ customer_id, feature_id: "image_gen", value: 1 });

Common Gotchas

常见注意事项

  1. Track after success - Only track if work completes successfully
  2. Backend required - Frontend checks can be bypassed
  3. Credit systems - Track metered features, not the credit pool
  4. Idempotency - Use 
    idempotency_key
    to prevent double-counting
  5. Batch tracking - Pass higher 
    value
    for bulk operations
  1. 成功后再追踪 - 仅当操作成功完成时才进行追踪
  2. 必须启用后端校验 - 前端校验可能被绕过
  3. 信用系统 - 追踪计量型功能，而非信用额度池
  4. 幂等性 - 使用
    idempotency_key
    避免重复统计
  5. 批量追踪 - 批量操作时传入更大的
    value
    值

Resources

相关资源