07/27/2026 21:11:44
MSDK-Web 接入指引
一、能力简介
- 适用于需要在端外实现 MSDK 登录的场景，比如 H5（包括 PC 网页）活动，官网页面；
- 目前支持的登录渠道包括：Facebook，Google，Apple，Twitter，Wechat，邮箱/手机号，更多的渠道正在持续实现；
二、接入准备
业务侧提供 MSDK Game ID 以及需要接入的渠道的 Client ID (有的渠道也叫作 App ID），示例如下：
MSDK Game ID: 11 (一般业务的 game id 都是 5 位整数，比如 12345)
各渠道 Client ID:
wechat: wx49174c26790800f1
facebook: 371085970095922
google: 851769810464-ed9kaaikttfvp7f2kd8qmilogg8us71t.apps.googleusercontent.com
apple: com.itop.sdk.web
邮箱/手机: 0afef39eb02d069107db6e02efd71a2c
twitter: M3ZzRUVncEhKbVJkZ3JjWXg5ZW86MTpjaQ
关于防水墙（邮箱/手机号验证码登录）：接入邮箱/手机号验证码登录时，在"发送验证码"环节可以接入防水墙（人机校验）做风控。防水墙选填，但强烈建议接入，可有效降低验证码被恶意刷取的风险。接入方式：业务方先到腾讯云验证码开通服务并创建一个"验证"，拿到
CaptchaAppId；在页面里额外引入腾讯云验证码脚本https://turing.captcha.qcloud.com/TJCaptcha.js。
三、部署方式
MSDK 会基于上述信息完成配置，并把编译好的 JSSDK 文件交付给业务，由业务自行部署到自己的域名 / 服务器（或 CDN）上。
1. 交付文件清单
MSDK 交付的 SDK 包包含以下文件：
| 文件 | 作用 | 是否必须部署 |
|---|---|---|
index.js |
业务页面用 <script src> 引入的 JSSDK 主文件 |
是 |
index.html |
发起登录/绑定时的中转起始页（业务调用登录后，会先经过它再跳转到对应渠道） | 接入 Google / Apple / Facebook / Twitter 等第三方渠道登录时必须；纯邮箱/手机号验证码登录可不部署 |
login.html |
第三方渠道登录或验证码登录完成后，浏览器跳回的回调中转页 | 是 |
msdk_<hash>.js |
index.html / login.html 两个页面依赖的脚本文件 |
是 |
2. 部署要求
必须使用 HTTPS。
目录约定： 建议把
index.js、index.html、login.html、msdk_<hash>.js放在同一目录下，例如/sdk/。业务自己的接入页可放在任意路径。目录结构示例（假设业务域名为
https://your.domain.com）：https://your.domain.com/ ├── (业务接入页) ← 路径不限 └── sdk/ ← MSDK 交付产物建议统一放这里 ├── index.js ← 业务页面引入的 JSSDK 主文件 ├── index.html ← 发起登录/绑定的中转起始页 ├── login.html ← 登录完成后浏览器跳回的回调中转页 └── msdk_<hash>.js ← 上面两个 html 页面依赖的脚本文件回调白名单登记（必做，否则会报错
redirect_uri_mismatch）： 需把login.html的完整地址精确登记到各渠道后台的redirect_uri白名单，并同步提供给 MSDK 后台登记。示例：| 渠道 | 白名单地址 | 备注 | | --- | --- | --- | | Facebook（4） |
https://your.domain.com/sdk/login.html?channelId=4| - | | Google（6） |https://your.domain.com/sdk/login.html?channelId=6| - | | Apple（15） |https://your.domain.com/sdk/login.html| 不带 query；默认走标准 GET 回调，若需 Apple 返回姓名/邮箱（scopes）则改用 form_post，需 MSDK 后台单独支持 | | Twitter（9） |https://your.domain.com/sdk/login.html?channelId=9| - | | Wechat（1） |your.domain.com| 仅按域名匹配，只能添加一个域名 |SDK 默认会在回调地址后自动附加
?channelId=<渠道id>（Apple 除外）；登记的白名单地址必须与 SDK 实际发起时的redirect_uri完全相同。
四、SDK使用方式
支持传统的 HTML + JS 的方式，也支持通过 npm 包引入，但鉴于目前 H5 活动开发场景都是传统方式，所以这里只提供这种方式的使用样例，如果需要 npm 包，可联系 MSDK助手获取。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>MSDK Web Sample</title>
<!-- 引入部署在业务自有域名下的 JSSDK（见"三、部署方式"目录约定，统一放在 /sdk/ 下） -->
<script src="https://your.domain.com/sdk/index.js"></script>
<!-- 仅当接入邮箱/手机号验证码登录并需要防水墙时才引入（见"接入准备"中的防水墙说明） -->
<script src="https://turing.captcha.qcloud.com/TJCaptcha.js"></script>
</head>
<body>
<h1>MSDK Web Sample</h1>
<div style="display: flex; flex-direction: column;">
<div>渠道登录</div>
<button id="btn-facebook">Facebook</button>
<button id="btn-google">Google</button>
<button id="btn-apple">Apple</button>
</div>
<script>
(() => {
const login = new MSDK.MSDK({
gameId: 12345,
});
function getFieldValue(field) {
/**
* @type {HTMLInputElement}
*/
const ele = document.getElementById(field);
return ele.value;
}
// 这个函数由业务自己实现，比如只是简单的检测cookie，或者更严格的请求后端接口验证
// 这里作为示例简化问题，将登录态存到了localStorage
function setLoginSecret(secret) {
localStorage.setItem('MSDK_SECRET', secret);
}
document.getElementById('btn-facebook').addEventListener('click', () => {
login.auth({
channelId: 4, // 4: FB, 6: Google, 15: Apple
// redirectUri: encodeURIComponent(location.href), // 登录成功之后会跳转回到这个URL，授权码（code）会附加到上面，默认为location.href
state: JSON.stringify({xyz: '12345'}), // 这里可以是任意内容，跳转回来之后还能获取到
});
});
document.getElementById('btn-google').addEventListener('click', () => {
login.auth({
channelId: 6, // 4: FB, 6: Google, 15: Apple
// redirectUri: encodeURIComponent(location.href), // 登录成功之后会跳转回到这个URL，授权码（code）会附加到上面，默认为location.href
});
});
document.getElementById('btn-apple').addEventListener('click', () => {
login.auth({
channelId: 15, // 4: FB, 6: Google, 15: Apple
// redirectUri: encodeURIComponent(location.href), // 登录成功之后会跳转回到这个URL，授权码（code）会附加到上面，默认为location.href
});
});
/**
* @type {{code?: string; state?: string} | undefined}
*/
const authRes = login.getAuthResult();
if (authRes?.code) {
/**===============================================================================================
拿到一次性授权码 code 后，有两种换取用户信息的方式：
+ 第一种（推荐）：把 code 发送到业务后端，由后端调用 MSDK 后台的 token 换取/校验接口，
用 code 换取 openid + token 并校验其有效性。后台接口地址由 MSDK 提供。
+ 第二种：直接在前端调用 login.accessToken({ code, gameId }) 换取 openid + token；
这种情况下因为是前端换取，真正需要校验身份时仍需在业务后台调用 MSDK 的 token 校验接口。
> 注意：code 是一次性的，只有 3 分钟有效期，页面刷新或重复使用都会失效。
这里为了简化，直接把 code 作为 secret，正式使用时请勿如此！！！
================================================================================================**/
setLoginSecret(authRes.code);
location.hash = 'logined';
}
})();
</script>
</body>
</html>
五、常见问题
- 授权页跳回后
code为空？ 检查login.html是否已按"三、部署方式"部署到业务域名的/sdk/login.html。 - 授权页报
redirect_uri_mismatch（如 Google 报错误 400: redirect_uri_mismatch）？ 渠道后台的redirect_uri白名单未登记或不匹配。SDK 发起时的redirect_uri是https://your.domain.com/sdk/login.html?channelId=<渠道id>（第三方渠道登录时含 query），白名单必须登记与之完全相同的完整 URL。 - 控制台报
sdk/msdk_<hash>.js 404？ 建议把msdk_<hash>.js与index.html/login.html放在同一目录（如/sdk/，见"三、部署方式"目录约定）；分开部署可能导致按相对路径找不到该文件而 404。 accessToken报code invalid？code只能使用一次，页面刷新或重复点按钮都不能重用，getAuthResult()拿到后要立即消费。
如有问题请联系 MSDK助手。
All rights reserved.