米洛SDK H5 API 标准对接文档

1. 接入前准备

1.1 必须提供的信息

对接前需要向米洛SDK提供以下信息：

• ✅ 商家名称
• ✅ 游戏名称
• ✅ 游戏登录地址
• ✅ 支付异步通知地址（或在后台添加获取相应参数）

1.2 米洛SDK提供的信息

米洛SDK会为您提供：

• ✅ mlsdk_Gameid - 游戏 ID
• ✅ mlsdk_payKey - 支付密钥
• ✅ mlsdk_appKey - 应用加密字段（请妥善保管）
• ✅ 游戏测试地址

2. 引入 SDK

在 HTML 文件中引入必要的 JS 库：

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>游戏名称</title>
    
    <!-- 1. 引入 jQuery 或 Zepto（必须） -->
    <script src="https://cdn.jsdelivr.net/npm/jquery@3.6.0/dist/jquery.min.js"></script>
    
    <!-- 2. 引入 mlSDK -->
    <script src="https://unify.wancms.com/static/channel/libWancmsnewSDK.js"></script>
</head>
<body>
    <!-- 游戏内容 -->
</body>
</html>

3. 初始化 SDK

3.1 接口说明

游戏应调用 mlSDK 的 init 接口，同时传入 mlSDK 后台分配给游戏的参数。

3.2 接口定义

mlSDK.init(mlgameid, isDebug, callback)

3.3 参数说明

3.4 调用示例

// 后台自动分配的 mlgameid
var mlgameid = '1';

mlSDK.init(mlgameid, true, function() {
    console.log("init success");
});

4. 调用 login 方法

4.1 接口说明

用户访问游戏时，米洛SDK会采用 iframe 方式访问游戏登录地址，并带上以下参数：

• username - 用户唯一识别 ID
• token - 用户登录口令（可以用于二次校验）

4.2 接口定义

mlSDK.login(callback)

4.3 参数说明

4.4 回调参数

{
    status: true,           // boolean - 登录状态
    data: {
        uid: '123',         // string - 用户 ID
        username: 'user',   // string - 用户名
        token: 'xxx'        // string - 登录令牌（用于二次校验）
    },
    message: ''             // string - 提示信息
}

4.5 调用示例

var uid;
var username;
var token;

mlSDK.login(function(callbackData) {
    var message;
    
    if (callbackData.status) {
        // 登录成功
        uid = callbackData.data.uid;
        username = callbackData.data.username;
        token = callbackData.data.token;
        
        console.log('GameDemo:username:' + uid);
        console.log('GameDemo:SDK登录成功: uid=>' + callbackData.data.uid);
        console.log('GameDemo:SDK登录成功: token=>' + callbackData.data.token);
        console.log('GameDemo:SDK登录成功: username=>' + callbackData.data.username);
        console.log('GameDemo:SDK登录成功: logintime=>' + callbackData.data.logintime);
    } else {
        // 登录失败
        console.log('GameDemo:SDK登录失败:' + callbackData.message);
    }
});

4.6 Token 使用建议

// 建议将 token 保存在 sessionStorage
sessionStorage.setItem('token', token);

// 请求接口时带上 token 进行二次校验
function makeAPIRequest() {
    var token = sessionStorage.getItem('token');
    // 使用 token 进行请求
}

5. 调用支付接口

5.1 接口说明

当用户点击购买时，游戏可调用 pay 方法传入 orderInfo 对象调起各渠道的支付页面。

5.2 接口定义

mlSDK.pay(orderInfoJson, callback)

5.3 参数说明

orderInfo 对象参数

callback 回调参数

{
    status: true,       // boolean - 支付状态
    message: ''         // string - 提示信息
}

5.4 调用示例

function pay() {
    // 构建 orderInfo 对象
    var orderInfo = new Object();
    orderInfo.mlgameid = '1';              // 必传
    orderInfo.uid = uid;                      // 必传
    orderInfo.username = username;            // 必传
    orderInfo.roleid = 'role_001';            // 必传
    orderInfo.rolename = '角色名';            // 必传
    orderInfo.serverid = 1;                   // 区服id 必传
    orderInfo.servername = '内测1区';         // 区服名 必传
    orderInfo.rolelevel = 1;                  // 角色等级 必传 类型需为int
    orderInfo.cpOrderNo = 'w123456789ss';     // cp订单号 必传
    orderInfo.amount = '1';                   // 总金额 必传
    orderInfo.viplevel = '111';               // vip等级 没有则填空
    orderInfo.rolebalance = '111';            // 角色余额 没有则填空
    orderInfo.partyname = '公会社团';         // 公会社团 没有则填空
    orderInfo.goodsname = '商品名';           // 商品名 必传
    orderInfo.extrasparams = '';              // 透传参数 没有则填空
    orderInfo.goodsid = '222';                // 产品ID 没有则填空
    orderInfo.count = '';                     // 数量 没有则填空
    orderInfo.callbackUrl = '';               // 回调地址 没有则填空
    
    // 转换为 JSON 字符串
    var orderInfoJson = JSON.stringify(orderInfo);
    
    // 调用支付
    mlSDK.pay(orderInfoJson, function(payStatusObject) {
        console.log('GameDemo:下单通知 ' + payStatusObject.message);
        
        if (payStatusObject.status) {
            console.log('✅ 支付成功');
            // 发放商品
        } else {
            console.log('❌ 支付失败: ' + payStatusObject.message);
        }
    });
}

5.1 充值异步回调通知

说明

1. 请求地址：由游戏方提供通知地址
2. 请求方：充值成功后由米洛SDK服务端请求至游戏方服务器
3. 请求方式：异步 GET/POST 请求
4. 请求参数以及加密形式：详见服务端对接文档

6. 上传角色信息接口

6.1 接口说明

游戏需要在玩家登录或角色发生变化时调用此接口。

6.2 接口定义

mlSDK.uploadGameRoleInfo(roleInfoJson, callback)

6.3 参数说明

roleInfo 对象参数

6.4 调用示例

function uploadGameRoleInfo() {
    // 构建 roleInfo 对象
    var roleInfo = new Object();
    roleInfo.isCreateRole = false;            // 创建角色时true其他传false
    roleInfo.uid = uid;                       // 必传
    roleInfo.username = username;             // 必传
    roleInfo.serverid = 1;                    // 区服id 必传
    roleInfo.servername = '区服';             // 必传
    roleInfo.rolename = '角色名';             // 必传
    roleInfo.roleid = '角色id';               // 必传
    roleInfo.rolelevel = 1000;                // 角色等级 必传 类型需为int
    roleInfo.rolebalance = 100;               // 角色用户余额 必传 类型需为int
    roleInfo.viplevel = 1;                    // vip等级必传 类型需为int
    roleInfo.partyname = '行会名称';          // 公会社团 必传
    roleInfo.partyid = 1;                     // 帮派Id
    roleInfo.rolegender = '男';               // 性别
    roleInfo.rolepower = 100;                 // 战力
    roleInfo.partyroleid = 100;               // 角色在帮派中的id
    roleInfo.partyrolename = 100;             // 角色在帮派中的名称
    roleInfo.profession = '武士';             // 职业名
    roleInfo.professionid = '32';             // 职业Id
    roleInfo.friendlist = '';                 // 好友关系列表
    
    // 转换为 JSON 字符串
    var roleInfoJson = JSON.stringify(roleInfo);
    
    // 上传角色信息
    mlSDK.uploadGameRoleInfo(roleInfoJson, function(response) {
        if (response.status) {
            console.log('uploadMessage:' + response.message);
        } else {
            console.log('uploadMessage:' + response.message);
        }
    });
}

7. 调用注销接口

7.1 退出游戏

mlSDK.logout(function(logoutObject) {
    console.log('Game:成功退出游戏');
});

7.2 注册退出通知

mlSDK.setLogoutNotification(function(logoutObject) {
    console.log('Game:玩家点击注销帐号');
});

8. 完整示例代码

8.1 完整流程

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <script src="https://cdn.jsdelivr.net/npm/jquery@3.6.0/dist/jquery.min.js"></script>
    <script src="https://unify.wancms.com/static/channel/libWancmsnewSDK.js"></script>
</head>
<body>
    <script>
    // 全局变量
    var uid;
    var username;
    var token;
    
    // 1. 初始化 SDK
    var mlgameid = '1';  // 后台自动分配
    mlSDK.init(mlgameid, true, function() {
        console.log("init success");
        
        // 2. 调用 login 方法
        mlSDK.login(function(callbackData) {
            if (callbackData.status) {
                uid = callbackData.data.uid;
                username = callbackData.data.username;
                token = callbackData.data.token;
                
                console.log('SDK登录成功: uid=>' + uid);
                console.log('SDK登录成功: token=>' + token);
                console.log('SDK登录成功: username=>' + username);
                
                // 3. 上传角色信息（登录成功后）
                uploadGameRoleInfo();
            } else {
                console.log('SDK登录失败:' + callbackData.message);
            }
        });
    });
    
    // 上传角色信息
    function uploadGameRoleInfo() {
        var roleInfo = new Object();
        roleInfo.isCreateRole = true;         // 创建角色
        roleInfo.uid = uid;
        roleInfo.username = username;
        roleInfo.serverid = 1;
        roleInfo.servername = '内测1区';
        roleInfo.rolename = '测试角色';
        roleInfo.roleid = 'role_001';
        roleInfo.rolelevel = 1;
        roleInfo.rolebalance = 0;
        roleInfo.viplevel = 0;
        roleInfo.partyname = '';
        
        var roleInfoJson = JSON.stringify(roleInfo);
        mlSDK.uploadGameRoleInfo(roleInfoJson, function(response) {
            console.log('uploadMessage:' + response.message);
        });
    }
    
    // 支付
    function pay() {
        var orderInfo = new Object();
        orderInfo.mlgameid = '1';
        orderInfo.uid = uid;
        orderInfo.username = username;
        orderInfo.roleid = 'role_001';
        orderInfo.rolename = '测试角色';
        orderInfo.serverid = 1;
        orderInfo.servername = '内测1区';
        orderInfo.rolelevel = 1;
        orderInfo.cpOrderNo = 'w' + Date.now();
        orderInfo.amount = '1';
        orderInfo.goodsname = '钻石礼包';
        orderInfo.viplevel = '';
        orderInfo.rolebalance = '';
        orderInfo.partyname = '';
        orderInfo.extrasparams = '';
        orderInfo.goodsid = '';
        orderInfo.count = '';
        orderInfo.callbackUrl = '';
        
        var orderInfoJson = JSON.stringify(orderInfo);
        mlSDK.pay(orderInfoJson, function(payStatusObject) {
            console.log('GameDemo:下单通知 ' + payStatusObject.message);
        });
    }
    
    // 退出
    function logout() {
        mlSDK.logout(function(logoutObject) {
            console.log('Game:成功退出游戏');
        });
    }
    </script>
</body>
</html>

9. 参数速查表

9.1 支付参数速查

9.2 角色参数速查

10. 常见问题

// 开启调试模式查看详细日志
mlSDK.init('1', true, function() {
    console.log("init success");
});

// 正确的调用顺序
mlSDK.init('1', true, function() {
    // ✅ 初始化成功后才能登录
    mlSDK.login(function(data) {
        if (data.status) {
            console.log('登录成功');
        }
    });
});

// 登录成功后保存
mlSDK.login(function(data) {
    if (data.status) {
        sessionStorage.setItem('token', data.data.token);
    }
});

// 请求接口时使用
var token = sessionStorage.getItem('token');
// 在请求头或参数中带上 token

// ✅ 正确流程
mlSDK.login(function(data) {
    if (data.status) {
        // 登录成功后才能支付
        pay();
    }
});

function generateCPOrderNo() {
    var timestamp = Date.now().toString(36);
    var random = Math.random().toString(36).substr(2, 9);
    return 'w' + timestamp + random;
}

// 使用
orderInfo.cpOrderNo = generateCPOrderNo();

orderInfo.amount = '1';      // ✅ 整数
orderInfo.amount = '1.5';    // ✅ 浮点数
orderInfo.amount = 1;        // ✅ 数字类型
orderInfo.amount = 1.5;      // ✅ 数字类型

// ✅ 正确流程
mlSDK.login(function(data) {
    if (data.status) {
        // 登录成功后上传角色
        uploadRoleInfo();
    }
});

// 创建角色
roleInfo.isCreateRole = true;

// 更新角色信息（升级、充值等）
roleInfo.isCreateRole = false;

// ✅ 正确 - 使用 parseInt()
roleInfo.serverid = parseInt('1');
roleInfo.rolelevel = parseInt('1000');
roleInfo.rolebalance = parseInt('100');
roleInfo.viplevel = parseInt('1');

// ❌ 错误 - 字符串类型
roleInfo.serverid = '1';
roleInfo.rolelevel = '1000';

orderInfo.serverid = parseInt('1');      // int
orderInfo.rolelevel = parseInt('10');    // int

// ✅ 正确 - 传空字符串
orderInfo.viplevel = '';
orderInfo.rolebalance = '';
orderInfo.partyname = '';

// ❌ 错误 - 省略参数
delete orderInfo.viplevel;  // 不要这样做

// ✅ 推荐 - JSON 字符串
var orderInfoJson = JSON.stringify(orderInfo);
mlSDK.pay(orderInfoJson, callback);

// ✅ 也支持 - 对象直接传
mlSDK.pay(orderInfo, callback);

// 日志输出
[mlSDK 警告] 基础渠道脚本加载失败，继续初始化
[mlSDK 运行日志] SDK 初始化完成

// 渠道脚本中
function mlcallChannelPay(order) {
    // 调起渠道支付
    MyChannelSDK.pay(order, function(result) {
        // 支付完成后必须回调
        if (mlSDK._payCallback) {
            mlSDK._payCallback({
                status: result.success,
                message: result.message
            });
        }
    });
}

mlSDK.init('1', true, function() {
    // true = 开启调试模式
    // 会在控制台输出详细日志
});

[mlSDK 运行日志] SDK 初始化开始, gameId: 1
[mlSDK 运行日志] 已调用渠道初始化 mlcallChannelInit
[mlSDK 运行日志] SDK 初始化完成
[mlSDK 运行日志] 开始登录流程
[mlSDK 运行日志] 登录成功, uid: 123456

<!-- ✅ 正确顺序 -->
<script src="jquery.min.js"></script>
<script src="./WancmsSDK.v2.js"></script>

<!-- ❌ 错误 - 顺序反了 -->
<script src="./WancmsSDK.v2.js"></script>
<script src="jquery.min.js"></script>

// ✅ 正确
var orderInfo = {
    mlgameid: '1',
    uid: uid,
    // ... 其他参数
};
var orderInfoJson = JSON.stringify(orderInfo);
mlSDK.pay(orderInfoJson, callback);

// ❌ 错误 - 忘记 stringify
mlSDK.pay(orderInfo, callback);  // 虽然支持，但推荐用字符串

mlSDK.pay({
    amount: 100,
    goodsname: '钻石礼包',
    goodsid: 'goods_001',
    count: '1',
    rolepower: '10000'
}, callback);

// 1. 页面加载后初始化
window.onload = function() {
    mlSDK.init('1', true, function() {
        console.log('SDK 初始化成功');
        
        // 2. 自动调用登录
        mlSDK.login(function(data) {
            if (data.status) {
                console.log('登录成功');
                
                // 3. 上传角色信息（创角）
                uploadRoleInfo(true);  // true = 创建角色
            }
        });
    });
};

// 4. 玩家购买时调用支付
function onPlayerBuy() {
    pay();
}

// 5. 角色升级时上传角色
function onRoleLevelUp() {
    uploadRoleInfo(false);  // false = 更新角色
}

// 6. 玩家退出时
function onPlayerLogout() {
    mlSDK.logout(function() {
        console.log('退出成功');
    });
}

// 添加超时处理
mlSDK.init('1', true, function() {
    console.log('初始化成功');
});

// 30秒后检查是否初始化成功
setTimeout(function() {
    if (!mlSDK._initialized) {
        console.error('初始化超时，请检查网络');
        // 可以提示用户刷新页面
    }
}, 30000);

📞 技术支持

• 官方文档： https://unify.wancms.com/h5api.html
• 🌐 测试地址: 请联系运营获取
• 技术支持：QQ 767146962
• 🐛 Bug 反馈: 请提供浏览器控制台日志

📝 更新日志

v2.1.1 (2026-02-19)

Bug 修复：

• ✅ 修复未登录时调用支付方法导致崩溃的问题
• ✅ 修复未登录时调用角色上传方法导致崩溃的问题
• ✅ 修复渠道脚本加载失败导致 SDK 初始化卡住的问题

优化：

• ✅ 支付方法增加登录状态检查
• ✅ 角色上传方法增加登录状态检查
• ✅ 渠道脚本加载失败改为警告并继续初始化