MeeAgent

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ản1.0.0
Scripthttps://meeagent.app/sdk/v1.js (khoảng 5 KB, không phụ thuộc thư viện nào)
APIhttps://api.meeagent.app
Trình duyệtChrome, 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ểuMô tả
gamestring, bắt buộcSlug 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>.

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ệnDữ liệuKhi nào
ready{ user, game }Sau khi init() xong.
authuser 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):

EndpointMô tả
GET /v1/healthKiểm máy chủ
GET /v1/homeGame nổi bật, danh sách game, tin mới
GET /v1/games · /v1/games/:slugKho game
GET /v1/news?game=&limit= · /v1/news/:idTin tức
POST /v1/auth/register{ login, password, name } → { token, user }
POST /v1/auth/login{ login, password } → { token, user }
GET /v1/meNgười chơi của mã phiên (Authorization: Bearer <token>)
POST /v1/auth/logoutHuỷ 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