Bỏ qua đến nội dung

Tài liệu kỹ thuật

Tích hợp LRS trong một buổi chiều.

Sự kiện anti-cheat

Game server gửi mỗi lần phát hiện hành vi đáng ngờ; LRS áp luật của tổ chức (bỏ qua, gắn cờ hoặc cấm) và phát lại thay đổi theo thời gian thực qua WebSocket.

EndpointPOSThttps://api.lrsvn.com/v1/anticheat/events

Cần API key có scope anticheat:ingest. Mỗi sự kiện phải có external_ref riêng — gửi lặp cùng mã sẽ bị từ chối thay vì tạo sự kiện thứ hai.

Yêu cầu

cURL
curl -X POST https://api.lrsvn.com/v1/anticheat/events \
  -H "Authorization: Bearer $LRS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "match-88231-evt-0042",
    "player_id": "player_10293",
    "signature": "aimbot.snap.v3",
    "confidence": 97.5,
    "device": { "os": "Windows 11", "gpu": "RTX 4060" }
  }'

Tham số

Tham sốKiểuMô tả
external_refstringMã sự kiện do game server đặt, tối đa 200 ký tự; trùng mã → 409.
player_idstringMã người chơi trong game, tối đa 200 ký tự.
signaturestringChữ ký hành vi đã phát hiện, tối đa 300 ký tự (ví dụ aimbot.snap.v3).
confidencenumberĐộ tin cậy, từ 0 đến 100.
deviceobjectKhông bắt buộc. Thông tin thiết bị; không quá 16.000 ký tự khi mã hoá JSON.

Phản hồi

HTTP
HTTP/1.1 201 Created

{
  "id": "ace_4b9d0e72",
  "action": "ban",
  "enforcement_status": "pending",
  "cursor": 1842
}

Luật xử lý

Hành động do luật của tổ chức quyết định (GET và PUT /anticheat/rules; mặc định ban_threshold là 95, automatic_ban tắt, whitelist rỗng):

actionĐiều kiệnenforcement_status
ignoreNgười chơi nằm trong whitelist.not_required
banautomatic_ban bật và confidence ≥ ban_threshold.pending, sau đó succeeded hoặc failed
flagCác trường hợp còn lại.not_required

Lệnh ban chỉ thật sự có hiệu lực khi enforcement_status là succeeded — tức là game server đã xác nhận.

Nhận sự kiện thời gian thực

Kết nối WebSocket tới wss://api.lrsvn.com/ws/anticheat (không có tiền tố /v1) bằng API key có scope anticheat:read, gửi trong header Authorization khi bắt tay:

JavaScript
import WebSocket from "ws";

const socket = new WebSocket("wss://api.lrsvn.com/ws/anticheat?after=0&action=ban", {
  headers: { Authorization: "Bearer " + process.env.LRS_API_KEY },
});

socket.on("message", (raw) => {
  const { cursor, change, event } = JSON.parse(raw.toString());
  // change là "created" hoặc "action". Lưu cursor để nối lại đúng chỗ.
});
Tham số truy vấnMô tả
afterCursor đã nhận cuối cùng. Mặc định 0: phát lại từ đầu.
player_idTuỳ chọn: chỉ nhận sự kiện của người chơi này.
signatureTuỳ chọn: lọc theo chữ ký hành vi.
actionTuỳ chọn: lọc theo hành động (flag, ban, ignore…).
org_idKhông cần với API key (khoá đã gắn sẵn tổ chức); chỉ dùng cho phiên đăng nhập trên website.

Mỗi thông điệp có dạng:

JSON
{
  "cursor": 1842,
  "change": "created",
  "event": {
    "id": "ace_4b9d0e72",
    "player_id": "player_10293",
    "signature": "aimbot.snap.v3",
    "confidence": 97.5,
    "action": "ban",
    "device": { "os": "Windows 11", "gpu": "RTX 4060" },
    "false_positive": false,
    "automatic": true,
    "enforcement_status": "pending",
    "enforcement_revision": 1,
    "enforced_action": "",
    "created_at": "2026-09-30T10:12:03Z"
  }
}

Khi mất kết nối, nối lại với after bằng cursor cuối cùng đã nhận và loại trùng theo event.id. Nếu khoá bị thu hồi, mất scope hoặc thành viên bị gỡ khỏi tổ chức, máy chủ đóng kết nối với mã 1008. Máy chủ gửi ping mỗi 20 giây.

Xử lý nhầm lẫn

Khi người chơi bị nhận diện nhầm, bỏ qua sự kiện và đánh dấu nhận diện nhầm (scope anticheat:write). Nếu lệnh xử lý đã áp dụng, LRS gửi yêu cầu gỡ tới hệ thống thực thi và enforcement_status chuyển về pending cho tới khi có xác nhận:

cURL
curl -X POST https://api.lrsvn.com/v1/anticheat/events/$EVENT_ID/action \
  -H "Authorization: Bearer $LRS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "action": "ignore", "false_positive": true, "reason": "Người chơi đã được xác minh." }'

action là warn, ban hoặc ignore; false_positive: true chỉ hợp lệ với ignore; reason tối đa 1.000 ký tự.

Mã lỗi

HTTPMãKhi nào
402usage_payment_requiredHoá đơn phí theo lượt anti-cheat đã quá hạn từ 14 ngày.
409invalid_stateexternal_ref đã tồn tại.
422validation_errorSự kiện không hợp lệ (fields.event), hoặc fields.action sai.
429rate_limitedQuá 1.000 sự kiện/phút cho mỗi tổ chức.
503provider_unavailableLuật cần cấm nhưng chưa cấu hình hệ thống thực thi.
503pricing_unavailableĐơn giá anti-cheat chưa được cấu hình.