Web SDK 集成指南
本文是 MA Web SDK 标准的集成指南文档。
产品说明
MA Web SDK 提供数据采集上报功能，用于 EUID 生成、用户属性设置、事件上报等场景
集成选择
MA Web SDK 支持 2 种接入方式，同时使用 WebPush 或者仅单独使用 MA Web SDK
- 同时使用 WebPush：集成 EngageLab WebPush 模块时设置开启 MA 功能，将自动加载 MA SDK
- 仅单独使用 MA Web SDK：单独将 MA SDK 地址集成到网站中使用，无 WebPush 功能
同时使用 WebPush
集成前准备
- 需要同时集成 WebPush 模块
- 准备一个能访问的 https web 服务域名，集成后的页面需在该域名下进行测试与调试。web 离线推送不支持本地调试、不支持 http。
- 访问 Engagelab WebPush，在【集成设定】-【 网站域名】页面，填写 https web 服务域名。
获取应用信息
需要在 WebPush 控制台上创建应用，创建成功后自动生成 AppKey 用以标识该应用，详情参考 应用设置文档。
MA 数据源配置
在 MA 项目-数据来源-添加数据来源-Web，选择「同时使用 WebPush」，下拉选择在 WebPush 创建好的应用，并保存
SDK 接入
进入 控制台，下载 SDK，在每个页面接入 js：
<script type="text/javascript" src="./WebSDK.3.3.4.js"></script>
<script type="text/javascript" src="./WebSDK.3.3.4.js"></script>
此代码块在浮窗中显示
tips
引入该 js 后，传入 maOpen 为 true 属性开启 MA 配置，就可以使用 MA 的相关 API 和功能
SDK 初始化
// 初始化（开启MA）
MTpushInterface.init({
appkey: "", // 必填，详见上文获取应用信息
user_str: "adminDemo", // 必填，用户识别符，用来标识用户
swUrl: "url", //默认 "/sw.min." + sdkEnv.version + ".js"。该配置项为server worker文件地址，域名必须为当前域名，且路径决定server worker作用域。
debugMode: true,// 设置是否开启 debug 模式。true 则会打印更多的日志信息。设置 false 则只会输出 w、e 级别的日志。
channel: "default-channel",// 渠道名称，默认值为:default-channel
appName: "string",// 用于设置网站名称，用于上报
maOpen: true, //打开开关，开启使用 MA 功能
userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123" },//在初始化MA的同时设置用户标识，从 3.3.4 版本开始支持，适用于仅面向登录会员提供MA服务的企业
maCompletion: (code, msg) => {//MA初始化回调
if (code === 0) {
console.log("✅MA SDK 初始化成功！");
} else {
console.error("❌MA SDK 初始化失败：", msg);
}
}
});
// 初始化（开启MA）
MTpushInterface.init({
appkey: "", // 必填，详见上文获取应用信息
user_str: "adminDemo", // 必填，用户识别符，用来标识用户
swUrl: "url", //默认 "/sw.min." + sdkEnv.version + ".js"。该配置项为server worker文件地址，域名必须为当前域名，且路径决定server worker作用域。
debugMode: true,// 设置是否开启 debug 模式。true 则会打印更多的日志信息。设置 false 则只会输出 w、e 级别的日志。
channel: "default-channel",// 渠道名称，默认值为:default-channel
appName: "string",// 用于设置网站名称，用于上报
maOpen: true, //打开开关，开启使用 MA 功能
userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123" },//在初始化MA的同时设置用户标识，从 3.3.4 版本开始支持，适用于仅面向登录会员提供MA服务的企业
maCompletion: (code, msg) => {//MA初始化回调
if (code === 0) {
console.log("✅MA SDK 初始化成功！");
} else {
console.error("❌MA SDK 初始化失败：", msg);
}
}
});
此代码块在浮窗中显示
单独使用 MA Web SDK
MA 数据源配置
在 MA 项目-数据来源-添加数据来源-Web，在「是否同时使用 WebPush」中选择「不使用」，输入数据源的名称和网站域名，保存后即可得到 Web 数据源的 Appkey 信息
- 请准备一个能访问的 https web 服务域名，集成后的页面需在该域名下进行测试与调试。
SDK 接入
每个页面接入下面 js：
<script type="text/javascript" src="https://websdk-res.engagelab.com/lib/ma-web.min.js"></script>
<script type="text/javascript" src="https://websdk-res.engagelab.com/lib/ma-web.min.js"></script>
此代码块在浮窗中显示
引入该 JS 后，就可以使用 Window 上的全局对象 MAInterface。
特别提示：请直接使用此链接，不要将此文件下载到您项目中，否则，在我们更新数据结构或 API 接口后有可能会导致统计失效。
SDK 初始化
window.MAInterface.init({
appKey: "7ccf93e0950b5e22f4ca2124", // 必填，详见上文获取应用信息
debugMode: true,
channel: "default-channel22",// 渠道名称，默认值为:default-channel
appName: "EngageLab-MA test-appName", //网址名称，用于设置设备属性和事件上报中的app_name
userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123", email: "user@example.com", phone: "+8613800000000" }, //在初始化MA的同时设置用户标识，支持 user_id、anonymous_id、email、phone
completion: (code, msg) => {
if (code === 0) {
console.log("✅ SDK 初始化成功！");
} else {
console.error("❌ SDK 初始化失败：", msg);
}
}
})
window.MAInterface.init({
appKey: "7ccf93e0950b5e22f4ca2124", // 必填，详见上文获取应用信息
debugMode: true,
channel: "default-channel22",// 渠道名称，默认值为:default-channel
appName: "EngageLab-MA test-appName", //网址名称，用于设置设备属性和事件上报中的app_name
userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123", email: "user@example.com", phone: "+8613800000000" }, //在初始化MA的同时设置用户标识，支持 user_id、anonymous_id、email、phone
completion: (code, msg) => {
if (code === 0) {
console.log("✅ SDK 初始化成功！");
} else {
console.error("❌ SDK 初始化失败：", msg);
}
}
})
此代码块在浮窗中显示
用户标识说明
- userIdentity 支持 user_id、anonymous_id、email、phone 4 类用户标识（email、phone 从 2.1.0 版本开始支持），至少提供一个，各字段规则详见 设置用户标识。
- 初始化时不符合规则的字段会被忽略并在控制台打印告警，其余合法字段继续生效。
- email、phone 用于用户身份匹配，不是联系方式；触达用的邮箱、手机号请使用「设置用户联系方式」（setUserContact）接口设置。
重复初始化与切换 AppKey
开始支持的版本：2.1.0
SDK 初始化后，可以再次调用 init，无需刷新页面：
- 传入相同的 AppKey：SDK 会重新获取 EUID。同时传入新的 userIdentity 时，SDK 使用新的用户标识重新获取 EUID，适用于同一页面内退出登录后切换账号的场景。
- 传入不同的 AppKey：SDK 切换到新 AppKey 对应的 MA 数据源，之后的数据上报到新数据源；切换前产生的数据仍上报到原数据源。
- 多次调用
init会按调用顺序依次执行，每次调用都会通过 completion 返回结果，请以本次回调结果为准。 - 仅单独使用 MA Web SDK 时支持切换 AppKey，「同时使用 WebPush」的接入方式不支持。
// 切换到另一个 MA 数据源
window.MAInterface.init({
appKey: "另一个数据源的 AppKey",
completion: (code, msg) => {
console.log(code, msg)
}
})
// 切换到另一个 MA 数据源
window.MAInterface.init({
appKey: "另一个数据源的 AppKey",
completion: (code, msg) => {
console.log(code, msg)
}
})
此代码块在浮窗中显示
设置通道联系ID
开始支持的版本：2.1.0
如需为 WebPush 或第三方 Push 通道设置 RID 或 Token，请在 SDK 初始化成功后调用：
window.MAInterface.setChannelValue(136, ["push rid or token"], (code, message) => { })
window.MAInterface.setChannelValue(136, ["push rid or token"], (code, message) => { })
此代码块在浮窗中显示
- channelId：MA 控制台中配置的 Push 通道 ID，必须大于 0。
- values：RID 或 Token 数组，数组及元素均不能为空；RID 或 Token 变化后，需要再次调用接口更新。
详细说明见 设置通道联系ID。
更多 API 接口
其他 API 的使用方法请参考接口文档：Web SDK API。
