01 Nhúng SDK vào Game HTML Embed SDK into Game HTML 在游戏网页中引入 SDK 🎮 CLIENT GAME🎮 GAME CLIENT🎮 游戏前端

Chèn 1 thẻ <script> vào file index.html của game H5. Thay {productCode} bằng mã game do JoyGames cấp (ví dụ: b18tiennghich):

Add a single <script> tag to your game's index.html. Replace {productCode} with your game code (e.g., b18tiennghich):

在游戏网页 index.html 中引入一行 SDK 脚本。将 {productCode} 替换为您在 JoyGames 后台配置的游戏标识（例如：b18tiennghich）：

<!-- Staging / Dev Test -->
<script src="https://devsdkapi.joyplay.vn/sdk/joygames-h5-wigame.js?product=b18tiennghich"></script>

<!-- Production / Live -->
<script src="https://sdkapi.joygames.vn/sdk/joygames-h5-wigame.js?product=b18tiennghich"></script>

Khởi tạo đối tượng SDK trong game JavaScript:

Initialize the SDK object in your game JavaScript:

在游戏 JS 中初始化 SDK 实例：

const joyH5 = new JoyGameH5WiGame({
  productCode: 'b18tiennghich', // Mã game trên Portal
  env: 'live'                  // 'live' hoặc 'sandbox' (khi test nội bộ)
});

02 Đăng Nhập & Lấy Thông Tin Người Chơi (joyH5.login) Login & Get Player Profile (joyH5.login) 用户登录与角色鉴权 (joyH5.login) 🎮 CLIENT GAME🎮 GAME CLIENT🎮 游戏前端

Khi game bắt đầu nạp, gọi hàm joyH5.login(). SDK sẽ tự động lấy token từ URL, kết nối với Portal để xác thực và trả về thông tin tài khoản người chơi:

When the game starts loading, call joyH5.login(). The SDK automatically extracts session tokens, verifies with the portal, and returns player credentials:

游戏加载就绪时调用 joyH5.login()。SDK 会全自动提取会话参数并与 Portal 验证，随后返回用户信息：

try {
  const user = await joyH5.login();
  
  console.log('Đăng nhập thành công!');
  console.log('User ID Portal:', user.id);
  console.log('Tên hiển thị:', user.name);
  console.log('WiGame OpenID:', user.wigameUserId);

  // Tiến hành cho người chơi vào màn hình game
  enterGame(user);
} catch (err) {
  console.error('Lỗi đăng nhập:', err.message);
}

Thông tin đối tượng user trả về:

Returned user object fields:

返回的 user 用户对象字段：

Field	Type	Ý nghĩa / Mô tảDescription说明
id	number	ID duy nhất của người chơi trên hệ thống JoyGames Portal Unique user ID on JoyGames Portal JoyGames 平台唯一用户 ID
wigameUserId	string	OpenID của người chơi từ Cổng WiGame / Tammi (ví dụ: wg_11bb71...) Player OpenID from WiGame / Tammi Portal WiGame / Tammi 开放平台的用户唯一标识 OpenID
name	string	Tên hiển thị của người chơi trên WiGame Display name of player 玩家在 WiGame 中的昵称
username	string	Username định danh tài khoản Account username 系统分配的账号名

03 Mua Vật Phẩm / Nạp Game (joyH5.pay) In-Game Purchase (joyH5.pay) 商城充值与道具购买 (joyH5.pay) 🎮 CLIENT GAME🎮 GAME CLIENT🎮 游戏前端

Khi người chơi nhấn vào gói nạp trong Shop Game, gọi joyH5.pay(...). SDK sẽ tự động mở Popup Bottom Sheet thanh toán của Super App WiGame / Tammi (người chơi xác nhận thanh toán qua ví Tammi hoặc trừ Gold WiGame):

When player clicks purchase in your shop, call joyH5.pay(...). The SDK automatically triggers the WiGame / Tammi Checkout Bottom Sheet:

当玩家在商城中点击购买道具时，调用 joyH5.pay(...)。SDK 会全自动弹出 WiGame / Tammi 收银台确认弹窗（扣除 WiGame Gold 或 Tammi 钱包余额）：

Bảng tham số truyền vào hàm joyH5.pay():

Parameters for joyH5.pay():

joyH5.pay() 参数说明表：

Param	Type	Bắt buộcRequired必填	Mô tảDescription说明
price	number	Có	Số tiền cần thanh toán theo đơn vị VND (tối thiểu 1000) Payment amount in VND (minimum 1000) 支付金额（单位：VND，最低 1000）
packageName	string	Có	Tên gói vật phẩm (ví dụ: "Rương 25 Kim Cương") hiển thị trên hoá đơn Item/package title displayed on invoice 道具套餐名称（如“25钻石宝箱”），显示于支付界面
googleProductId	string	Có	Mã SKU gói nạp (ví dụ: pack_20k, pack_50k) Package SKU identifier (e.g. pack_20k) 道具计费点标识 SKU（如 pack_20k）
serverId	string	Có	Mã server / máy chủ nhân vật đang chơi (ví dụ: s1) Game server ID (e.g. s1) 角色所在的游戏区服 ID（如 s1）
charId	string	Có	ID nhân vật của người chơi trong game (dùng để nạp kim cương vào đúng nhân vật) Character ID in game 角色 ID，发货时根据此 ID 准确充值到对应角色
charName	string	Không	Tên nhân vật (hiển thị trên log đối soát) Character name 角色昵称
ext	string	Không	Chuỗi dữ liệu riêng của game (ví dụ mã đơn client, thông tin custom lưu kèm hóa đơn) Custom game passthrough string attached to transaction records 游戏自定义透传字段，附带于订单对账记录中

04 Checklist Bàn Giao & Cấu Hình Integration Checklist 联调与配置清单

Khi tích hợp game, hai bên kỹ thuật cần trao đổi các thông tin sau:

Information exchanged during integration:

联调上线需互相对接的配置项：