MeeAgent SDK
Thư viện JavaScript nhỏ cho game H5 phát hành trên meeagent.app. Người chơi đăng nhập bằng tài khoản MeeGame (số điện thoại hoặc email), game nhận thông tin người chơi và gọi được API MeeGame thay họ.
| Phiên bản | 1.0.0 |
|---|---|
| Script | https://meeagent.app/sdk/v1.js (khoảng 5 KB, không phụ thuộc thư viện nào) |
| API | https://api.meeagent.app |
| Trình duyệt | Chrome, Safari, Firefox, Edge bản mới; WebView Android / iOS |
Nhúng SDK
Thêm một dòng vào trang game, trước script của game:
<script src="https://meeagent.app/sdk/v1.js"></script>
SDK tạo biến toàn cục MeeAgent. Gọi init một lần khi game mở, với game là slug của game trong kho (xem Đăng ký game):
const { user } = await MeeAgent.init({ game: 'ten-game-cua-ban' });
if (user) console.log('Xin chào', user.name);
else console.log('Đang chơi dưới dạng khách');
Bản v1 luôn tải từ đường dẫn cố định /sdk/v1.js. Sửa lỗi trong v1 không phá vỡ code cũ; thay đổi lớn sẽ ra /sdk/v2.js.
Ví dụ đầy đủ
Một trang có nút đăng nhập / đăng xuất và hiện tên người chơi:
<!doctype html>
<html lang="vi">
<meta charset="utf-8">
<button id="btn">Đăng nhập</button>
<span id="who">Khách</span>
<script src="https://meeagent.app/sdk/v1.js"></script>
<script>
const btn = document.getElementById('btn');
const who = document.getElementById('who');
function render(user) {
who.textContent = user ? user.name : 'Khách';
btn.textContent = user ? 'Đăng xuất' : 'Đăng nhập';
}
MeeAgent.on('auth', render); // gọi lại mỗi khi đăng nhập / đăng xuất
MeeAgent.init({ game: 'bat-sao' }).then(({ user }) => render(user));
btn.onclick = async () => {
if (MeeAgent.isLoggedIn()) return MeeAgent.logout();
try { await MeeAgent.login(); } // phải gọi trong sự kiện bấm, nếu không trình duyệt chặn cửa sổ
catch (e) { console.log(e.message); } // người chơi đóng cửa sổ
};
</script>
MeeAgent.init(options)
Khởi động SDK và kiểm phiên đăng nhập đã lưu trên máy. Trả về Promise<{ user, game }>.
| Tham số | Kiểu | Mô tả |
|---|---|---|
game | string, bắt buộc | Slug của game trong kho, ví dụ bat-sao. |
user là null nếu người chơi chưa đăng nhập hoặc phiên đã hết hạn. Mất mạng lúc khởi động thì SDK vẫn chạy ở chế độ khách và ghi cảnh báo ra console, không ném lỗi.
MeeAgent.login() / MeeAgent.logout()
login() mở cửa sổ đăng nhập của meeagent.app. Người chơi đăng nhập hoặc tạo tài khoản ở đó; cửa sổ tự đóng và trả mã phiên về cho game. Trả về Promise<user>.
- Phải gọi từ sự kiện người dùng (bấm, chạm). Gọi lúc tải trang thì trình duyệt chặn cửa sổ và Promise bị từ chối.
- Promise bị từ chối nếu người chơi đóng cửa sổ.
- Đã đăng nhập rồi thì trả ngay người chơi hiện tại.
logout() huỷ phiên trên máy chủ và xoá mã phiên trên máy. Trả về Promise<void>.
MeeAgent.user
Người chơi hiện tại hoặc null. MeeAgent.isLoggedIn() trả true / false.
{
"id": 42,
"login": "0901234567", // số điện thoại hoặc email đã chuẩn hoá
"name": "Cường",
"created_at": 1763600000 // giây Unix
}
Dùng id làm khoá người chơi trong dữ liệu của game. login là thông tin riêng tư của người chơi: không hiển thị công khai, không gửi sang dịch vụ khác.
MeeAgent.api(path, options)
Gọi API MeeGame, tự gắn mã phiên của người chơi. Trả về JSON đã phân tích; lỗi HTTP ném Error có status và data.
const { user } = await MeeAgent.api('/v1/me');
// gửi JSON: truyền object vào body
await MeeAgent.api('/v1/duong-dan', { method: 'POST', body: { diem: 1200 } });
Máy chủ trả 401 (phiên hết hạn, bị đăng xuất ở máy khác) thì SDK tự xoá phiên và phát sự kiện auth với null.
MeeAgent.games() / MeeAgent.game(slug)
games() trả danh sách game trong kho. game() trả thông tin game hiện tại (hoặc game có slug truyền vào): tên, mô tả, ảnh bìa, icon, màu chủ đạo, phiên bản.
MeeAgent.on(event, handler)
Đăng ký sự kiện. Trả về hàm để huỷ đăng ký.
| Sự kiện | Dữ liệu | Khi nào |
|---|---|---|
ready | { user, game } | Sau khi init() xong. |
auth | user hoặc null | Đăng nhập, đăng xuất, hoặc phiên hết hạn. |
Đăng ký game
Game H5 lên kho bằng một bản ghi kind: "link", trỏ tới địa chỉ chạy game. Hiện chỉ quản trị MeeAgent thêm được game; gửi cho quản trị: slug, tên, mô tả ngắn, địa chỉ game (HTTPS), ảnh bìa 16:9 và icon vuông.
curl -X PUT https://api.meeagent.app/v1/admin/games/ten-game-cua-ban \
-H "authorization: Bearer $ADMIN_TOKEN" -H "content-type: application/json" \
-d '{
"title": "Tên game",
"tagline": "Một câu giới thiệu",
"description": "Mô tả dài hơn",
"genre": "Giải đố",
"kind": "link",
"link_url": "https://ten-game.example.com/",
"accent": "#7A2BF5",
"status": "live"
}'
Sau khi có bản ghi, game hiện ở trang chủ meeagent.app và trong kho game của app MeeGame. Cửa sổ đăng nhập chỉ trao mã phiên cho đúng origin của link_url (giao thức + tên miền + cổng), nên game phải chạy đúng ở địa chỉ đã đăng ký.
Chạy thử ở máy
Khi phát triển, cửa sổ đăng nhập chấp nhận http://localhost và http://127.0.0.1 ở mọi cổng, chưa cần đăng ký game:
npx serve . # hoặc python3 -m http.server 8080
# mở http://localhost:8080 rồi bấm Đăng nhập
Mở trang bằng file:// sẽ không đăng nhập được vì không có origin; hãy chạy qua một máy chủ tĩnh như trên.
REST API
SDK chỉ là lớp mỏng trên các endpoint công khai này (CORS mở, trả JSON):
| Endpoint | Mô tả |
|---|---|
GET /v1/health | Kiểm máy chủ |
GET /v1/home | Game nổi bật, danh sách game, tin mới |
GET /v1/games · /v1/games/:slug | Kho game |
GET /v1/news?game=&limit= · /v1/news/:id | Tin tức |
POST /v1/auth/register | { login, password, name } → { token, user } |
POST /v1/auth/login | { login, password } → { token, user } |
GET /v1/me | Người chơi của mã phiên (Authorization: Bearer <token>) |
POST /v1/auth/logout | Huỷ phiên |
Mã phiên sống 90 ngày và tự gia hạn khi người chơi còn dùng. Sai mật khẩu 5 lần thì tài khoản bị khoá 10 phút.
Bảo mật
- Mật khẩu chỉ nhập ở trang của meeagent.app, game không bao giờ thấy mật khẩu.
- Mã phiên được lưu trong
localStoragecủa tên miền game. Không ghi mã phiên ra log, không gửi sang máy chủ khác ngoàiapi.meeagent.app. - Mã phiên có toàn quyền với tài khoản người chơi. Chỉ nhúng script của bên thứ ba mà bạn tin cậy vào trang game.
- Điểm số, xu, vật phẩm gửi từ trình duyệt đều sửa được. Việc gì liên quan tới tiền hay xếp hạng phải được máy chủ của game kiểm lại: gửi mã phiên lên máy chủ game, máy chủ gọi
GET https://api.meeagent.app/v1/međể biết người chơi thật.