跳转到主要内容

​
快速开始

本指南带你从零完成一个 Profy 应用的接入：创建应用 → 用户授权 → 上报计费事件。

​
前置条件

  • 已注册 Profy 账号并通过创作者认证
  • Node.js >= 18（用于运行示例）

​
第一步：创建应用

  1. 进入 Profy Studio
  2. 点击「创建应用」，输入应用名称
  3. 创建成功后，记录 App ID 和 App Secret
App Secret 仅在创建时完整展示。请妥善保管，不要提交到代码仓库。

​
第二步：配置回调地址

在应用管理页面 → 开发配置 → 回调地址，添加你的回调 URL。
  • 生产环境必须使用 HTTPS
  • 本地开发可使用 http://localhost
http://localhost:5180/callback

​
第三步：安装 SDK

npm install @profy-ai/sdk

bun add @profy-ai/sdk

pip install profy-sdk
# 含可选的 SQLAlchemy 自动建表支持：
pip install profy-sdk[sqlalchemy]

​
第四步：发起 OAuth 授权

将用户重定向到 Profy 授权页面： 
https://app.profy.cn/oauth/authorize?client_id={APP_ID}&redirect_uri={CALLBACK_URL}&scope=events:write&response_type=code
参数说明
client_id你的 App ID
redirect_uri与后台配置一致的回调地址
scope请求的权限，当前支持 events:write
response_type固定为 code
用户同意授权后，Profy 会将用户重定向到你的回调地址，并附带授权码： 
http://localhost:5180/callback?code=abc123...

​
第五步：用授权码换取 Token

在你的后端服务中，使用 SDK 将授权码换成 Access Token： 
import { ProfyApp } from "@profy-ai/sdk";

const profy = new ProfyApp({
  clientId: process.env.PROFY_APP_ID,
  clientSecret: process.env.PROFY_APP_SECRET,
});

// 用户授权后，回调地址收到 code
const token = await profy.exchangeCode(code, "http://localhost:5180/callback");

// token 包含：
// - accessToken:  JWT 格式，1 小时有效
// - refreshToken: 90 天有效，支持自动续期
// - expiresAt:    过期时间戳（毫秒）
永远不要在前端直接调用 exchangeCode。 App Secret 必须保存在后端，授权码交换只能在服务端完成。

​
第六步：上报计费事件

当用户在你的应用中触发了付费操作，调用 SDK 上报事件： 
const result = await profy.reportEvent("generate_report", {
  token,
  metadata: { source: "web", userId: "user-123" },
});
SDK 会自动处理 Token 刷新——如果 Access Token 过期，会先用 Refresh Token 续期再重试。

​
完整示例

import { Hono } from "hono";
import { ProfyApp, type TokenData } from "@profy-ai/sdk";

const profy = new ProfyApp({
  clientId: process.env.PROFY_APP_ID!,
  clientSecret: process.env.PROFY_APP_SECRET!,
});

let tokenStore: TokenData | null = null;

const app = new Hono();

// 处理 OAuth 回调
app.post("/api/exchange", async (c) => {
  const { code } = await c.req.json();
  tokenStore = await profy.exchangeCode(code, "http://localhost:5180/callback");
  return c.json({ ok: true });
});

// 上报计费事件
app.post("/api/report", async (c) => {
  if (!tokenStore) return c.json({ error: "Not authenticated" }, 401);
  const result = await profy.reportEvent("generate_report", { token: tokenStore });
  return c.json(result);
});

export default app;

​
脚手架模板

我们提供了一个完整的前后端脚手架项目，包含 Vite 前端 + Hono 后端，开箱即用： → profy-app-template 
git clone https://github.com/user/profy-app-template.git
cd profy-app-template
cp .env.example .env  # 填入 App ID 和 App Secret
npm install && npm run dev

​
流程图

​
下一步

SDK 完整指南

双语言 SDK 详细用法 + Token 持久化（Contrib）

API 参考

查看完整的 OAuth 端点和 Events API 文档

计费事件配置

了解如何在 Studio 中配置事件定价