包
后端包 & 新手指南
复制页面
官方Lia后端客户端和为TypeScript、Python、PHP和Go的安全启动项目。
官方服务器客户端用于 TypeScript/JavaScript,Python,PHP和Go。它们调用相同的app-scopedLia服务器API。测试密钥查看测试记录;正式密钥需要正式的应用程序并查看正式记录。
#生成后端
npx @lia-labs/create-app@latest backend选择 Node.js HTTP 或 Express,FastAPI 或 Django,PHP HTTP,或 Go HTTP。生成的后端可验证短期玩家会话和付费交易,保持 SQLite 的库存并附有唯一收据,成功授予后确认交付,并在一次退款后进行逆向处理。Node 起始项目还包括服务器发布的奖励挑战和一个有限的、分页的恢复扫描。
CLI 从不会要求您将密钥粘贴到终端参数中或将其写入前端。设置 LIA_SERVER_KEY 和 LIA_WEBHOOK_SECRET 在您的服务器上。创建 coins-100 产品在Lia 开发者中,然后更改服务器拥有的授权映射以匹配您的实际产品。持久化 data/ 在耐用的卷上。对于多个应用程序实例,将示例 SQLite 存储替换为共享的事务数据库。在生产托管中配置 HTTPS 和特定于应用程序的速率限制。
框架集成示例包含在内 Express, Next.js App Router, Hono, FastAPI, Django 和 Laravel。框架适配器无法确定您的游戏'的权益或反作弊规则;这些仍为服务器所有应用程序代码。
#安装到现有后端
| 语言 | 包/源代码 | 安装 |
|---|---|---|
| JavaScript / TypeScript | @lia-labs/server | npm install @lia-labs/server |
| Python | lia-labs-server | pip install 'lia-labs-server @ git+https://github.com/The-Lia-Labs/lia-server-python.git@v0.1.0' |
| PHP | lia-labs/server | 在下面添加公司GitHub VCS存储库,然后 composer require lia-labs/server:^0.1.0 |
| Go | github.com/The-Lia-Labs/lia-server-go | go get github.com/The-Lia-Labs/lia-server-go@v0.1.0 |
Python可以从其标记的GitHub源代码安装;它尚未列在PyPI上。PHP可以通过Composer VCS安装;它尚未列在Packagist上。
{"repositories":[{"type":"vcs","url":"https://github.com/The-Lia-Labs/lia-server-php"}]}节点支持ESM和CommonJS,并包含TypeScript类型。Python提供 LiaClient 和 AsyncLiaClient。PHP 需要 8.2+ 和 cURL;生成的库存起始器还需要 PDO SQLite。Go'的客户端使用标准库;其生成的库存启动器使用 SQLite 到 CGO,需要C编译器。不要在浏览器包中导入这些包。
#验证玩家身份
import {LiaClient} from '@lia-labs/server';
const lia = new LiaClient(process.env.LIA_SERVER_KEY!);
const player = await lia.requireSession(sessionFromLia);
const {products} = await lia.listProducts();Python: lia.require_session(session); PHP: $lia->requireSession($session); 转到: client.RequireSession(ctx, session).
前端发送由 Lia.init() 或 Lia.session(),不是玩家ID或您的服务器密钥。结果's exp 是Unix 毫秒。客户端验证响应'模式,玩家形态和过期时间。当会话过期时重新生成前端会话。API本身验证签名和应用所有权。
#操作
共享的机器可读合约是 操作合约。以下名称是TypeScript/PHP名称。Python 使用 snake_case 和关键字参数;Go 使用 PascalCase, context.Context, lia.Params 和 lia.RequestOptions.
| 区域 | 方法 |
|---|---|
| 会话 | verifySession, requireSession |
| 目录 | listProducts |
| 购买 | getCharge, deliverCharge, refundCharge, listPendingCharges |
| LIA 奖励 | payReward, getPool |
| 通知 | sendNotification |
| 奖励广告 | verifyAd, createAdChallenge, claimAdChallenge |
| 多人游戏大厅 | listTables, saveTable, sitAtTable, removeTable |
| 权威分数 | listLeaderboards, saveLeaderboard, getLeaderboard, submitScore, moderateScore |
| 仅服务器存储 | getPlayerStorage, setPlayerStorage |
| 网络钩子 | listWebhookEvents, replayWebhookEvent,原始签名验证和事件构造 |
| 分析 | getAnalytics, exportAnalytics |
存储写入需要 expectedVersion; 冲突是 HTTP 409. JSON null 是一个有效的存储值。对此存储的浏览器访问是只读的,并与会话绑定'的玩家。得分必须来自服务器验证的游戏行为;将不受信任的得分传递到服务器端点并不会使其具有权威性。
#购买和重试
- 使用服务器密钥获取费用。检查
playerId,mode,productId和一个paid/delivered状态。 - 在一个数据库事务中,按以下方式插入唯一收据 模式 + 充电 ID 并且仅在收据是新的情况下才授予映射的权益。
- 提交库存,然后调用
deliverCharge。即使已授予库存,也请重试该确认。 - 使用每个光标页面解决待处理的已付费费用。退款必须重新与Lia核对,并在您的数据库中撤销一次。
所有客户端默认使用15秒的请求预算和最多两次重试。它们会重试临时HTTP/网络故障,遵守 Retry-After,拒绝经过身份验证的重定向,并从错误中省略原始错误正文。突变在调用内保持相同的生成的Idempotency-Key和序列化正文。 在跨进程重启或单独调用时重试时,传递一个稳定的业务密钥。
await lia.deliverCharge({id: charge.id}, {idempotencyKey: `deliver:${charge.id}`});Python使用 idempotency_key=...; PHP 作为第二个参数;Go 使用 lia.RequestOptions{IdempotencyKey: ...}。会话验证是一个读取类型的POST,不会创建不必要的幂等性记录。 LiaError 包括代码,HTTP 状态,请求 ID 和重试延迟。永远不要将 503 视为无效玩家或已完成的购买。安全 GETs 和会话验证有有限的重试次数;财务上的精确一次行为也依赖于 API'和你的数据库'的独特商业收据。
#已签名的webhook
验证 未处理的原始字节在解析JSON之前 与 constructWebhookEvent (Node), construct_webhook_event (Python), Webhooks::constructEvent (PHP), ConstructWebhookEvent (Go)。使用 Lia-Signature 标题和您的应用'的网络钩子密钥。验证会拒绝被修改的负载以及超过五分钟的过去或未来时间戳。未知的已签名事件类型可以被确认,但不授予任何东西; test:true 探针从不授予库存。
Lia 保留一个持久的待发送消息队列,具有稳定的事件 ID。它会立即尝试发送,然后在 1 分钟后,5 分钟,30 分钟,2 小时,8 小时,24 小时和 48 小时后再次尝试。每次尝试都会获得一个新的签名时间戳。使用 listWebhookEvents,并在修复处理程序后重放事件。即使在重放后,也通过稳定的业务收据去重。在履行提交之前不要返回2xx。
#奖励挑战
在您的服务器上创建一个带有服务器拥有上下文和玩家 ID 的挑战。返回 challengeId 传递给前端并作为 rewardContextId 请求奖励广告时。绑定/声明检查玩家、应用模式、广告格式、年龄、完成情况和重复使用。声明 本身不授予库存; 授权你的游戏'在你自己的交易中,每个广告一次授权。
实时有价值的奖励需要 providerVerified:true. 新的证明流程还需要更新的原生Lia主机来发送每条广告的SSV随机数和AdMob SSV回调配置。仅后端支持无法升级已安装的应用程序。测试模式下的原生完成是模拟证据,绝不是真实提供者签名的证明。
SDK Demo 中的真实广告每个 UTC 日最多请求 3 次,间隔至少 30 分钟。购买和 LIA 奖励仍为模拟。请更新 Lia 以使用此功能。
#分析
报告包括每日活跃玩家、购买和付费者转化率、按格式的广告遥测以及D1/D7/D30留存率。CSV包含活动、广告和留存记录类型。留存率收集从本版本开始;历史群体不会被虚构。不完整的广告展示覆盖返回空指标。SDK报告的收入是一个估计值,不是最终的AdMob收益或开发者付款声明。
在 Lia Developers 中管理赛季、隐藏或恢复分数、查看 Webhook 投递尝试并重新发送事件。分析功能包含团队应用和 CSV 导出。测试数据与正式数据保持隔离。
#验证
来自公司 lia-sdk 仓库:
npm install
python3 -m venv .venv
.venv/bin/pip install -e backends/python
LIA_PYTHON=.venv/bin/python npm run test:backends
npm run test:create-app安装 Postman CLI,PHP 使用 cURL 和 Go。这会通过本地第一方 Postman HTTP 模拟运行所有四个真实客户端,包括临时故障、重复修改、会话过期、重定向、截止时间、网络钩子篡改。它不会接触生产数据。参见 scripts/developer-server-features-local-test.mjs 在 API 仓库中进行单独的集成测试,以针对真实的本地 Worker 实现进行测试。
自动翻译。英语是真实来源。 阅读英文