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.

LR License — Tổng quan

LR License cấp phép phần mềm của bạn (script FiveM, launcher, công cụ Windows): phần mềm gọi init → activate → check → end, mọi câu trả lời được ký Ed25519.

Bạn bán khoá bản quyền cho phần mềm của mình; phần mềm hỏi LRS khoá có hợp lệ không. Bật dịch vụ và tạo ứng dụng ở /app/license, rồi nhúng app_id cùng khoá công khai vào phần mềm.

Luồng gọi

Gốc của client API là https://api.lrsvn.com/v1/license/client. Mọi lệnh đều là POST JSON, không cần API key:

BướcEndpointViệc
1POST /license/client/initTuỳ chọn, lúc khởi động: ứng dụng còn chạy không, phiên bản và bản dựng có hợp lệ không.
2POST /license/client/activateGửi khoá và HWID, nhận session. Chiếm một chỗ phiên (và một chỗ thiết bị khi ràng buộc hwid).
3POST /license/client/heartbeatMỗi next_heartbeat_in giây (mặc định 20): giữ phiên "sống". Không tính vào hạn mức ngày.
4POST /license/client/checkĐịnh kỳ (SDK mặc định 5 phút): kiểm tra lại khoá và gia hạn phiên.
5POST /license/client/endKhi thoát: đóng phiên, trả chỗ phiên ngay. Thiết bị vẫn giữ chỗ.

Mỗi lần gọi gửi app_id và một nonce mới. Mọi câu trả lời là JSON có ok, code, message, nonce, server_time, app_id và được ký trong header X-LR-Signature. Phần mềm chỉ tin câu trả lời sau khi xác minh chữ ký.

Kết luận về khoá luôn là HTTP 200: { "ok": false, "code": "key_expired" } là câu trả lời bình thường, không phải lỗi HTTP. Phần mềm tự hiển thị thông báo theo code; message là câu tiếng Việt có sẵn.

Ràng buộc, phiên đồng thời và heartbeat

Hai giới hạn độc lập, đặt cho ứng dụng (tab Cài đặt hoặc API quản lý) và ghi đè được trên từng khoá.

Ràng buộc thiết bị (binding)

  • hwid (mặc định): khoá gắn với tối đa max_devices máy, activate bắt buộc gửi HWID, máy mới khi đã đủ nhận device_limit. Đổi máy cần người bán reset thiết bị.
  • none: không đếm thiết bị — khoá chạy trên máy nào cũng được, HWID (nếu gửi) chỉ được ghi lại theo phiên. Trong câu trả lời, license.max_devices và license.devices là null. Dùng khi chỉ muốn giới hạn số phiên cùng lúc.

Khoá ghi đè bằng trường binding (null = theo ứng dụng).

Số phiên cùng lúc

max_concurrent_sessions đếm phiên đang sống trên cả khoá (mọi máy cộng lại), ở cả hai chế độ. Ứng dụng mới mặc định 1; 0 = không giới hạn; khoá ghi đè được (null = theo ứng dụng).

Khi khoá đã đủ phiên, activate làm theo session_overflow của ứng dụng:

  • reject (mặc định): phiên mới nhận session_limit kèm retry_at.
  • kick_oldest: phiên cũ nhất bị thay, phần mềm ở đó nhận session_replaced ở lần heartbeat/check kế tiếp.

Cùng một máy kích hoạt lại (ràng buộc hwid, cùng HWID) luôn thay phiên cũ của chính nó, không bị session_limit. end trả chỗ ngay.

Heartbeat

Khi khoá có giới hạn phiên (max_concurrent_sessions khác 0), phiên chỉ sống khi phần mềm còn gửi heartbeat hoặc check. Im lặng quá heartbeat_timeout_seconds (30–600 giây, mặc định 60) thì phiên hết hạn (session_expired) và nhường chỗ — phần mềm bị tắt ngang hay mất điện không giữ chỗ mãi. Không giới hạn phiên thì phiên im lặng vẫn sống tới session_expires_at.

Phần mềm dùng SDK dưới 0.2 chỉ check 5 phút một lần và không gửi heartbeat. Ứng dụng tạo trước khi có heartbeat giữ thời gian chờ 600 giây; nếu bạn bật giới hạn phiên với thời gian chờ dưới 300 giây, hãy cập nhật SDK trước, nếu không phiên của bản cũ sẽ bị coi là đã dừng.

Chọn timeout: ngắn thì chỗ được trả nhanh sau khi phần mềm sập, nhưng heartbeat dày hơn (mỗi khoảng ⅓ timeout); dài thì ít lưu lượng nhưng người dùng chờ lâu hơn trước khi mở lại trên máy khác. 60 giây hợp với đa số phần mềm.

Lưu ý chuyển đổi: ứng dụng tạo trước khi có tính năng này được đặt max_concurrent_sessions = 0 (không giới hạn) để phần mềm đang chạy không bị ảnh hưởng. Muốn giới hạn, hãy cập nhật phần mềm gửi heartbeat trước, rồi mới hạ số phiên.

app_id

app_id có dạng lapp_…, xem ở /app/license › ứng dụng › Tổng quan. Đây là mã công khai: ai cũng thấy được trong phần mềm, nên nó không phải bí mật. Người lạ biết app_id không dùng hết được hạn mức ngày của bạn — hạn mức chỉ tính lượt gọi có khoá hoặc phiên hợp lệ.

Khoá ký và xoay vòng

Mỗi ứng dụng có khoá ký Ed25519 riêng. Khoá bí mật nằm ở LRS; bạn nhúng khoá công khai (kid dạng lsk_… cùng 32 byte ở dạng base64url, hoặc hex cho C/C++) vào phần mềm.

  • active: khoá đang dùng. LRS ký mọi câu trả lời bằng mọi khoá chưa ngừng.
  • Xoay khoá (nút ở tab Tổng quan, cần phiên đăng nhập Owner/Admin): khoá cũ thành previous, khoá mới thành active. Trong thời gian này mỗi câu trả lời có hai chữ ký (kid=…, kid2=…), nên bản phần mềm cũ (nhúng khoá cũ) và bản mới (nhúng khoá mới) đều chạy.
  • Ngừng khoá cũ (retire): khi mọi người dùng đã lên bản mới, ngừng khoá previous. Từ đó LRS không ký bằng nó nữa; bản cũ chỉ nhúng khoá đó sẽ báo invalid_signature.

Mỗi lần chỉ có một khoá previous. Để không phải phát hành lại khi xoay, hãy nhúng sẵn khoá hiện tại và khoá kế tiếp ngay khi vừa xoay.

Dùng SDK hay tự gọi

Có SDK chính thức cho Node/TypeScript (chạy được trong script server FiveM), C# (.NET 8), C++17 và Python ≥ 3.9. SDK tự sinh nonce, xác minh chữ ký, so nonce và app_id, lấy HWID, chạy heartbeat và check định kỳ, và tách lỗi mạng (network_error kèm thời gian chờ) khỏi kết luận đã ký.

  • Tải gói .zip ở /app/license › Tổng quan (mục Tải SDK, kèm mẫu mã điền sẵn app_id và khoá công khai) hoặc trang công khai /services/lr-license.
  • Tệp nằm ở https://lrsvn.com/sdk/: manifest.json liệt kê bản mới nhất, kiểm tra tải về bằng SHA256SUMS.

Chỉ tự gọi API khi ngôn ngữ của bạn không có SDK. Khi đó bắt buộc làm đủ các bước ở trang Xác minh chữ ký — có mẫu Go, PHP và JavaScript (WebCrypto).

Quản lý khoá từ máy chủ cửa hàng (tạo khoá khi có đơn, thu hồi, đổi máy) dùng API quản lý với API key lrs_… — không bao giờ nhúng API key đó vào phần mềm.