Tích hợp Server cho XMDT
Server của bạn chỉ cần gọi đúng một API. Nó không bao giờ gửi đi hay nhận về họ tên, ngày sinh, số điện thoại hay mã OTP của người chơi.
| Môi trường | Base URL |
|---|---|
| Dev | https://api-xmdt.dev.alogame.vn |
| Prod | https://api-xmdt.alogame.vn |
Cả hai đều đang hoạt động. secret_key là riêng theo từng môi trường — key mint cho dev không dùng được cho prod và ngược lại. Xem Lấy secret bên dưới.
| Lệnh gọi | Khi nào | Vì sao |
|---|---|---|
POST /xmdt/session | Mỗi khi client của bạn cần mở màn hình XMDT, và cả những lúc bạn cần biết chắc người chơi đã xác thực hay chưa | Mint một token ngắn hạn cho SDK — secret HMAC của bạn không bao giờ đến tay thiết bị. Phản hồi của nó cũng mang xmdtCompleted, đọc trực tiếp từ Alogame, không đi qua thiết bị người chơi — đó là câu trả lời đáng tin của bạn. |
Lấy secret
Liên hệ đầu mối Alogame Operations của bạn để bật XMDT cho gameId của bạn. Bạn sẽ được cấp một secret_key đúng một lần, ngay lúc nó được sinh ra — không thể lấy lại lần hai, nên hãy lưu ngay vào hệ thống quản lý secret của bạn, không lưu trong file config rồi lỡ commit vào version control.
Dev và prod được bật riêng biệt, mỗi bên có secret_key của riêng mình — xin cả hai nếu bạn cần test ở dev trước khi chuyển bản build thật sang prod.
Ký request
Lệnh gọi này dùng sơ đồ ký sau, đơn giản hơn các hợp đồng thanh toán của Alogame: không timestamp, không cửa sổ chống replay, không cần sort field.
X-Signature: HMAC-SHA256(secret_key, raw_request_body), hex viết thường
Nội dung được ký là byte thô của JSON body đúng như khi gửi đi — không phải bản đã serialize lại hay sort lại.
Nếu framework của bạn parse JSON rồi bạn ký trên bản serialize lại, thứ tự key, khoảng trắng, và cách format số đều có thể khác với những gì bạn thực sự gửi đi, và chữ ký sẽ không khớp. Hãy chụp lại raw body trước khi JSON parser của bạn tiêu thụ nó (xem hướng dẫn xác thực API thanh toán — hiện chỉ có bản tiếng Anh — để có ví dụ theo từng ngôn ngữ làm đúng việc này — cùng nguyên lý áp dụng ở đây dù công thức ký khác).
const crypto = require("crypto");
function signXmdtBody(rawBody, secret) {
return crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
}
import hmac, hashlib
def sign_xmdt_body(raw_body: bytes, secret: str) -> str:
return hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
function signXmdtBody(string $rawBody, string $secret): string {
return hash_hmac('sha256', $rawBody, $secret);
}
Gửi nó dưới header X-Signature, Content-Type: application/json, cho lệnh gọi dưới đây. Không có header service-id riêng — gameId trong body chính là giá trị được kiểm tra.
POST /xmdt/session — mint session token
Gọi lệnh này mỗi khi client của bạn sắp mở màn hình XMDT (AlogameKycSdk.show()).
Request
{
"gameId": "your_game_id",
"username": "player_account_name",
"serverId": "server_01",
"roleId": "character_123"
}
| Field | Bắt buộc | Ghi chú |
|---|---|---|
gameId | Có | Game code đã đăng ký của bạn |
username | Có | Định danh ổn định riêng của bạn cho từng người chơi — đây, không phải device ID, là thứ gắn một người chơi với bản ghi XMDT của họ |
serverId | Không | Bỏ qua nếu game của bạn chưa có bước chọn server tại thời điểm này |
roleId | Không | Bỏ qua nếu người chơi chưa chọn nhân vật |
BODY='{"gameId":"your_game_id","username":"player_account_name"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST https://api-xmdt.dev.alogame.vn/xmdt/session \
-H "Content-Type: application/json" \
-H "X-Signature: $SIG" \
-d "$BODY"
Response
{
"sessionToken": "opaque-token-hand-this-to-your-client",
"expiresAt": "2026-08-07T12:15:00Z",
"xmdtRequired": true,
"xmdtCompleted": false
}
| Field | Ý nghĩa |
|---|---|
sessionToken | Đưa thẳng cho client của bạn — đây là thứ AlogameKycSdk.setGameRole() cần. Có hiệu lực 15 phút. |
xmdtRequired | Form của SDK có hiện nút đóng hay không. Được Alogame Operations set theo từng game; bạn không cấu hình cái này theo từng lệnh gọi. |
xmdtCompleted | Người chơi này đã có bản ghi XMDT đầy đủ — client của bạn có thể bỏ qua việc gọi show() hoàn toàn nếu muốn tránh mở màn hình vô nghĩa. |
Token chỉ dùng được một lần cho bước collect và hết hạn sau 15 phút — mint một token mới cho mỗi lần gọi show(), không nên cache rồi dùng lại qua nhiều session.
Dùng lệnh này làm bước kiểm tra đáng tin cậy
Không dựa vào riêng callback onResult của SDK để cho qua bất cứ điều gì — callback đó đến từ thiết bị người chơi, và một client bị mod có thể báo thành công mà chưa từng xác thực gì cả. Tại đúng thời điểm bạn cần tin vào câu trả lời (ví dụ: cho người chơi vào một trận đấu), hãy gọi lại chính API này và đọc xmdtCompleted từ phản hồi. Không có route trạng thái riêng: trường này đáng tin vì nó đến trực tiếp từ Alogame qua cùng một lệnh gọi server-to-server đã ký — không bao giờ đi qua thiết bị người chơi.
Hãy cache kết quả true ở phía bạn thay vì mint lại mỗi lần đăng nhập — một bản ghi đã hoàn tất sẽ không quay lại trạng thái chưa hoàn tất, và việc mint bị giới hạn tốc độ theo từng người chơi (xem phần Lỗi dưới đây).
Lỗi
| HTTP | code | Ý nghĩa |
|---|---|---|
| 400 | invalid_request | JSON sai định dạng, hoặc thiếu gameId/username |
| 401 | missing_headers | Không gửi header X-Signature |
| 401 | invalid_signature | Chữ ký không khớp — kiểm tra lại bạn đã ký đúng raw body |
| 403 | unknown_service | gameId chưa được đăng ký hoặc đang bị inactive |
| 409 | xmdt_disabled | XMDT chưa được bật cho gameId của bạn — liên hệ Operations |
| 409 | email_required_unsupported | Game của bạn có cấu hình yêu cầu xác thực email mà luồng SDK này chưa hỗ trợ — liên hệ Operations |
| 429 | rate_limited | Quá nhiều request mint cho người chơi/IP này trong một khoảng thời gian ngắn — chờ rồi thử lại, không có chi tiết về giới hạn nào bị chạm |
| 500 | internal_error | Thử lại với backoff |
Mọi response lỗi đều có cùng dạng {"code": "...", "message": "..."}.