Đưa game HTML5 của bạn lên WebSuperGames

WebSuperGames là cổng game HTML5 chơi ngay trên trình duyệt, ưu tiên điện thoại. Người chơi bấm là chơi bằng tài khoản khách, có bảng xếp hạng theo ngày, tuần và mọi lúc, xem quảng cáo giữa các lượt hoặc để nhận thưởng trong game. Tài liệu này dành cho studio và lập trình viên muốn đưa game của mình lên portal: cách dùng SDK, game cần đáp ứng gì, kiểm thử ra sao và nộp, phát hành thế nào.

Bạn không cần biết portal được làm bằng gì. Game chỉ cần là một bundle tĩnh (HTML, JS, asset), nhúng một file SDK và gọi vài hàm ở đúng thời điểm.

Game chạy thế nào trên portal

• Origin riêng cho game. Bundle của bạn được phục vụ từ origin game https://games.leonogames.com, tách khỏi origin của trang portal https://leonogames.com. Mỗi phiên bản nằm ở một đường dẫn cố định /<slug>/<version>/.
• Iframe chỉ được tạo khi bấm Chơi. Portal tạo một phiên chơi (session) cho người chơi trước, rồi mới dựng <iframe> trỏ tới index.html của game kèm query ?wsg=1&host=<origin portal>&lang=<vi|en>&v=<version>.
• SDK là cầu nối. Game nhúng file /sdk/v1/wsg-sdk.js, cũng nằm trên origin game. Khi bạn gọi WSG.init(), SDK đọc query ở trên, bắt tay với trang portal qua postMessage, và từ đó mọi tính năng (người chơi, điểm, bảng xếp hạng, quảng cáo, lưu dữ liệu, chia sẻ) đi qua kênh này.
• Game không gọi API của portal. Trang portal nhận yêu cầu từ game, gọi API thay cho game rồi trả kết quả về. Cookie người chơi, phiên chơi và luật chống gian lận đều nằm phía portal, game không thấy và không cần quản lý.
• Chạy được ở mọi nơi. Mở game trực tiếp, không qua iframe của portal, SDK tự chuyển sang chế độ standalone: mọi API vẫn trả kết quả hợp lệ với dữ liệu lưu trong localStorage. Bạn phát triển và kiểm thử game mà không cần portal.

Trình duyệt người chơi
│
├─ Trang portal (https://leonogames.com)
│    ├─ gọi API của portal: phiên chơi, điểm, bảng xếp hạng, dữ liệu lưu
│    ├─ hiện overlay tải game, tạm dừng, quảng cáo
│    └─ <iframe sandbox> → https://games.leonogames.com/<slug>/<version>/index.html?wsg=1&host=…
│              │
│              │  postMessage hai chiều, mỗi bên kiểm tra origin của bên kia
│              ▼
└─ Game của bạn (origin game)
     ├─ index.html, JS, asset — tải bằng đường dẫn tương đối
     └─ <script src="/sdk/v1/wsg-sdk.js"> → window.WSG

Bạn cần làm gì

1. Nhúng SDK và khởi tạo. Thêm thẻ script, gọi await WSG.init({ gameId }). Xem Bắt đầu nhanh.
2. Báo vòng đời. Gọi WSG.loadingFinished() khi game sẵn sàng (portal mới gỡ overlay tải), WSG.gameplayStart() khi người chơi bắt đầu điều khiển và WSG.gameplayStop() khi hết lượt.
3. Nộp điểm. Gọi WSG.leaderboard.submit(score) khi hết lượt và khai báo limits hợp lý trong game.json, vì server dùng chúng để từ chối điểm gian lận. Xem Điểm và bảng xếp hạng.
4. Nghe lời portal. Dừng vòng lặp và tắt tiếng khi nhận sự kiện pause hoặc audio(false), chạy lại khi resume. Gọi quảng cáo ở chỗ hợp lý. Xem Quảng cáo.
5. Đóng gói và nộp. Bundle có index.html ở gốc, đường dẫn tương đối, không gọi origin ngoài. Kiểm thử ở chế độ standalone rồi gửi gói nộp gồm game.json, thumbnail.png và thư mục build. Xem Yêu cầu với game và Nộp và phát hành.

Những điều nên biết sớm

• Điểm chỉ được nhận trong khung gameplay. Server chấp nhận điểm khi gameplay đang chạy hoặc trong vòng 10 giây sau gameplayStop(), và kiểm tra theo limits của game: điểm tối đa, thời gian chơi tối thiểu, tốc độ ghi điểm tối đa.
• Điểm là số nguyên không âm. Số lẻ thập phân hay số âm bị từ chối với lý do invalid_score.
• Origin game dùng chung cho mọi game. localStorage, IndexedDB và cookie trên origin này chia sẻ với game khác, nên đừng dùng chúng cho dữ liệu cần giữ. Dùng WSG.storage, được lưu theo người chơi và theo game.
• Iframe bị giới hạn quyền. Không mở được popup, không điều hướng được trang cha, không hiện được alert() hay confirm().
• SDK cập nhật không cần build lại. File SDK nằm ở đường dẫn có major version (/sdk/v1/). Trong cùng major, SDK tương thích ngược và portal tự cập nhật bản vá.

Các trang tài liệu

• Bắt đầu nhanhHai cách bắt đầu — thêm SDK vào game HTML5 có sẵn với bất kỳ engine nào, hoặc tạo game mới từ template Phaser của đội nội bộ.
• Tham chiếu SDKMọi API của SDK v1 — chữ ký TypeScript, hành vi trong portal và khi chạy standalone, giới hạn, sự kiện và mã lỗi.
• game.jsonTham chiếu manifest của game — từng trường, kiểu, giá trị mặc định, ràng buộc, category và tag hợp lệ, cách chọn limits.
• Yêu cầu với gameRàng buộc về bundle, mạng, dữ liệu, iframe, màn hình, tải, âm thanh và tạm dừng, kèm checklist trước khi nộp.
• Điểm và bảng xếp hạngLuồng nộp điểm, các kỳ bảng xếp hạng, XP của người chơi, luật chống gian lận theo thứ tự, mẹo chọn limits và xác thực người chơi bằng JWT.
• Quảng cáoInterstitial và rewarded — khi nào nên gọi, cooldown, xử lý reason, tạm dừng và tắt tiếng, chỉ cấp thưởng khi người chơi xem hết.
• Engine và frameworkTích hợp SDK từ Phaser, canvas hay JavaScript thuần, và cách gọi SDK từ Unity WebGL, Construct, Godot qua cầu nối JavaScript.
• Kiểm thửChạy game ở chế độ standalone, dựng thư mục giống production trên máy, chạy trong portal, test hooks, game conformance và smoke test Playwright.
• Nộp và phát hànhGói nộp gồm những gì, game được lưu trên R2 và phục vụ thế nào, cache, phiên bản, quy trình duyệt và các lệnh wsg cho đội nội bộ.
• Giao thức bridgeGiao thức postMessage cấp thấp giữa game và portal, cho trường hợp không dùng được file SDK — envelope, các yêu cầu, sự kiện, kiểm tra origin, timeout và mã lỗi.
• Câu hỏi thường gặpNhững lỗi hay gặp khi tích hợp và cách xử lý — rơi về standalone, chưa init, CSP chặn nhúng, mixed content, âm thanh, điểm bị từ chối.

Địa chỉ của môi trường này

Các địa chỉ trong tài liệu được điền theo môi trường bạn đang xem: