1.1 开放接口

除特别说明外，以下接口支持 Promise 风格调用：当 result 为 'SUCCESS' 时 resolve，否则 reject。

例外：mos.isMosEnv 为同步只读属性；mos.registerHandler 为回调注册，均不适用上述 Promise 约定。

1.1.1 判断 MOS 环境

SDK 版本号: 1.1.10

API： mos.isMosEnv

同步只读属性，返回 boolean，无需 await。

说明

同步判断当前页是否在 MOS 桥接环境（App / PC 壳），用于决定是否可调用原生能力。

• true：当前页在 MOS App / PC 壳内，可调用原生能力
• false：普通浏览器

if (mos.isMosEnv) {
  // MOS App / PC 壳内，可调用原生能力
  const sign = await mos.getSign()
} else {
  // 普通浏览器
  console.log('非 MOS 环境')
}

1.1.2 登录

SDK 版本号: 1.1.0

API： mos.login(appKey)

支持以 Promise 风格调用。

参数

属性	类型	必填	说明
appKey	string	是	微应用 appKey

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
code	string	登录凭证

1.1.3 分享文本

SDK 版本号: 1.1.0

API： mos.shareToApp(content)

支持以 Promise 风格调用。 通过 mos 分享文本。

参数

属性	类型	必填	说明
content	string	是	需要分享出去的文本内容

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败

1.1.4 获取用户信息

SDK 版本号: 1.1.0

API： mos.getUserInfo(Object object)

支持以 Promise 风格调用。 静默允许授权，不会弹出授权窗口。

参数

[Object object]

属性	类型	必填	说明	最低版本
authorizedDesc	string	否	获取授权信息的用处
closeOnClickOverlay	string	否	是否在点击遮罩层后关闭弹窗，0: 不关闭 1: 关闭	1.1.2

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败 | CANCEL: 用户取消
authorized	number	0: 不授权 | 1: 授权 | 2: 没有对应信息
firstName	string	姓
lastName	string	名
headPortrait	string	头像地址
descriptor	string	个人简介

1.1.5 获取用户手机号/邮箱信息

SDK 版本号: 1.1.0

API： mos.getUserContactInfo(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	必填	说明	最低版本
authorizedDesc	string	否	获取授权信息的用处
closeOnClickOverlay	string	否	是否在点击遮罩层后关闭弹窗，0: 不关闭 1: 关闭	1.1.2

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败 | CANCEL: 用户取消
authorized	number	0: 不授权 | 1: 授权 | 2: 没有对应信息
dialCode	string	区号
phone	string	手机号码
email	string	邮箱地址

1.1.6 获取用户唯一签名

SDK 版本号: 1.1.0

API： mos.getSign()

支持以 Promise 风格调用。 获取用户签名用来校验 mos 是否切换了用户。

参数

无

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
sign	string	签名

1.1.7 获取当前语言

SDK 版本号: 1.1.0

API： mos.getLanguage()

支持以 Promise 风格调用。

参数

无

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
lang	string	语言，如 en-US

TIP

lang 字段说明：

• MosApp支持以下语言类型：
  • zh-CN - 简体中文
  • en-US - English
  • km-KH - ភាសាខ្មែរ
  • ja-JP - 日本語
  • vi-VN - Tiếng Việt
  • zh-HK - 繁體中文(香港)
  • zh-TW - 繁體中文(臺灣)
  • th-TH - ภาษาไทย
  • ms-MY - Bahasa Melayu
  • ko-KR - 한국어
  • id-ID - Bahasa Indonesia
  • lo-LA - ລາວ
  • hi-IN - हिन्दी

1.1.8 调起支付

SDK 版本号: 1.1.0

API： mos.pay(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	必填	说明
amount	string	是	支付金额
currency	string	是	币种，USD: 美元
appKey	string	是	微应用 appKey
prepayId	string	是	订单预支付 ID

响应

属性	类型	说明
result	string	SUCCESS: 成功 | PAYING: 支付中 | CANCEL: 用户取消
data	string	支付结果为 SUCCESS 时才有，值为服务端返回的信息

注意

SUCCESS（成功）与 PAYING（支付中）均不是最终支付结果，需通过后端开放接口 /open-apis/mp/v1/pay/orderQuery 主动查询订单状态以确认最终结果。

1.1.9 获取窗口信息

SDK 版本号: 1.1.0

API： mos.getWindowInfo()

支持以 Promise 风格调用。

参数

无

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
statusBarHeight	number	状态栏高度

1.1.10 获取设备信息

SDK 版本号: 1.1.0

API： mos.getAppBaseInfo()

支持以 Promise 风格调用。

参数

无

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
platform	string	客户端平台，'IOS' | 'ANDROID' | 'WINDOWS' | 'MAC' | 'LINUX'
SDKVersion	string	支持的 mos-js 库版本, 如: 1.1.0
language	string	客户端语言, 如: 'en-US'
version	string	客户端版本号, 如: '1.1.0'
deviceId	string	设备唯一识别码
brand	string	设备品牌
system	string	操作系统及版本

1.1.11 分享微应用页面

SDK 版本号: 1.1.0

API： mos.shareMiniApp(Object object)

支持以 Promise 风格调用。

兼容接口

本接口仅作兼容保留。请尽快迁移到 mos.registerHandler（action: 'moreButton'），以便在点击「更多」时定参，并支持 success / fail / complete。

进入页面后设置右上角「更多」的分享参数。调用时会同步写入当前页的 moreButton 注册：即使未再调 registerHandler，App 点击「更多」拉取配置时也能拿到同一套参数（等价于只传 data、且不需要结果回调）。存量仅调本接口的页面可暂时不改，但新页面请直接使用 registerHandler。

与 registerHandler 同时使用时，以后执行的那次写入的 data 为准；详见 1.1.12。

参数

[Object object]

字段见 附录：分享参数说明。

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
shareLink	string	当前页面的链接地址，如：https://mp.mos.me/mp/微应用id?query=xxxxx

1.1.12 注册「更多」按钮回调

SDK 版本号: 1.1.10

API： mos.registerHandler(Object object)

注册供 App 拉取的「更多」分享配置（推荐方式，请优先使用本接口）：用户点击右上角「更多」时，App 取当前页 data 作为本次分享参数；处理完成后可触发 success / fail / complete。

按页面注册，页面切换由 SDK 管理。无需自定义分享时可不注册（App 走默认分享）。mos.shareMiniApp 仅作兼容：仅调它时也会自动挂上本页 moreButton，效果等价于只传 data、且不需要结果回调——请尽快改为本接口。

与 shareMiniApp 同时使用：

顺序	行为
先 registerHandler，再 shareMiniApp	只更新分享 data，保留已注册的 success / fail / complete 等
先 shareMiniApp，再 registerHandler	整份覆盖该页 moreButton（以本接口为准）
两边 data 不一致	以后执行的那次写入为准

参数

[Object object]

属性	类型	必填	说明
action	string	是	固定为 moreButton
data	object	否	本次分享内容，字段见 附录：分享参数说明
success	function	否	成功回调，res.data 为本次分享链接
fail	function	否	失败回调
complete	function	否	完成回调（成功或失败都会执行）
callbackId	string | null	否	不需要 success / fail / complete 时可显式传入 null

mos.registerHandler({
  action: 'moreButton',
  data: {
    query: { path: '/profile' },
    shareDisabled: '0',
    desc: '页面描述',
    imageUrl: '',
    screenShotDisabled: '0',
  },
  success(res) {
    // res.data 为本次分享链接
    console.log('success', res.data)
  },
  fail(error) {
    console.log('fail', error)
  },
  complete(res) {
    console.log('complete', res)
  },
})

1.1.13 单次分享微应用数据，通知移动端打开转发到会话的页面

SDK 版本号: 1.1.0

API： mos.shareMiniAppData(Object object)

支持以 Promise 风格调用。

调用后打开转发到会话界面，仅影响本次主动分享的微应用消息，不影响右上角「更多」的分享内容。

参数

[Object object]

字段见 附录：分享参数说明。

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
shareLink	string	当前页面的链接地址，如：https://mp.mos.me/mp/微应用id?query=xxxxx

附录：分享参数说明

公共对象（非 API）

本节不是独立接口，而是上方分享相关 API 共用的参数对象定义。registerHandler / shareMiniApp / shareMiniAppData 中写「见分享参数说明」时，均指向此处。

以下对象用于：

• mos.registerHandler 的 data（action: 'moreButton'）
• mos.shareMiniApp 的入参
• mos.shareMiniAppData 的入参

字段

属性	类型	必填	说明
query	string | object	否	启动参数，详见下方 query 字段说明
shareDisabled	string	否	是否禁用分享 1: 禁用 | 0: 启用
desc	string	否	页面描述，通常为当前页面标题
imageUrl	string	否	微应用消息上展示的图片地址，网络图片路径，建议 https 地址
screenShotDisabled	string	否	是否禁止屏幕截图用于微应用消息的页面图片展示 1: 禁止截图 | 0: 自动截图

query 字段说明

TIP

query 字段说明：

• 若 query 为对象类型，且有 ogLang 属性，则页面解析og标签时优先使用该属性值作为语言，ogLang取值为：
  • zh-CN - 简体中文
  • en-US - English
  • km-KH - ភាសាខ្មែរ
  • ja-JP - 日本語
  • vi-VN - Tiếng Việt
  • zh-HK - 繁體中文(香港)
  • zh-TW - 繁體中文(臺灣)
  • th-TH - ภาษาไทย
  • ms-MY - Bahasa Melayu
  • ko-KR - 한국어
  • id-ID - Bahasa Indonesia
  • lo-LA - ລາວ
  • hi-IN - हिन्दी
• 若为了让你的分享链接更吸引人,可以告诉支持OG标签的应用(如Telegram、Facebook、Twitter等),通过自定义OG标签来决定链接的标题、描述和图片以及跳转地址,让用户在分享时能够更方便地了解到微应用的内容。
  query同时支持设定四个主要属性来定制分享内容：
  • ogTitle - 自定义标题显示在分享卡片顶部,对应‌og:title标签
  • ogDesc - 分享描述,显示在分享卡片中间,对应‌og:description标签
  • ogImg - 分享图片,卡片上展示的预览图片,对应‌og:image标签
  • ogUrl - 分享跳转地址,用户点击分享卡片后跳转的链接,对应‌og:url标签

图片展示规则：

• imageUrl 有值时优先使用 imageUrl 的值
• imageUrl 为空时：
  • screenShotDisabled=1 不截图，页面图片展示默认图
  • screenShotDisabled=0 系统自动截图

1.1.14 获取启动参数

SDK 版本号: 1.1.0

API： mos.getLaunchOptions()

支持以 Promise 风格调用。 获取微应用启动时的 query 参数，例如 https://mp.mos.me/mp/<miniapp_id>?query=<query>。

参数

无

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
query	string | object	启动参数

1.1.15 添加事件埋点统计

SDK 版本号: 1.1.1

API： mos.addTrackingEvent(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	必填	说明
name	string	是	事件名称
data	string	否	JSON 字符串

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败

1.1.16 打开原生客服号聊天界面

SDK 版本号: 1.1.3

API： mos.folderLinkClick(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	必填	说明
link	string	是	客服号链接，如：https://mos.me/xxxxyyyyzzz
query	object	否	支持客户来源、上下文功能等参数

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败

1.1.17 获取短链接

SDK 版本号: 1.1.4

API： mos.getShortLink(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	必填	说明
link	string	是	长链接
showLoading	string	1	否

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
message	string	错误信息
data	string	短链接

1.1.18 打开微应用

SDK 版本号: 1.1.6

API： mos.openMiniApp(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	必填	默认值	说明
miniAppId	String	是		微应用ID
name	string	否		微应用名称
headPortrait	string	否		微应用头像
query	string | object	否		启动参数

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败

1.1.19 打开内部链接

SDK 版本号: 1.1.7

API： mos.openInternalLink(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	必填	说明
link	string	是	内部链接，如：https://mos.me/xxxxyyyyzzz

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败

1.2 设备

1.2.1 扫码

SDK 版本号: 1.1.0

API： mos.scanCode()

支持以 Promise 风格调用。

参数

无

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败(当获取不到摄像头或没有摄像头权限时)' | CANCEL': 用户取消
code	string	二维码值

1.2.2 打电话

SDK 版本号: 1.1.0

API： mos.makePhoneCall(phoneNumber)

支持以 Promise 风格调用。

参数

属性	类型	必填	说明
phoneNumber	string	是	手机号码

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败

1.2.3 设置状态栏样式

SDK 版本号: 1.1.0

API： mos.setStatusbar(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	默认值	必填	说明
show	string	1	否	1: 显示 | 0: 不显示
style	string	dark	否	状态栏字体样式，dark: 黑色 | light: 白色

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败

1.3 位置

1.3.1 获取定位

SDK 版本号: 1.1.3

API： mos.getLocation(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	默认值	必填	说明
isHighAccuracy	string	0	否	开启高精度定位，1: 开启 | 0: 不开启
highAccuracyExpireTime	string	30000	否	高精度定位超时时间(ms)，指定时间内返回最高精度，该值3000ms以上高精度定位才有效果

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
latitude	string	纬度，范围为 -90~90，负数表示南纬
longitude	string	经度，范围为 -180~180，负数表示西经
address	string	地址信息
speed	string	速度，单位 m/s
accuracy	string	位置的精确度，反应与真实位置之间的接近程度，可以理解成10即与真实位置相差10m，越小越精确
altitude	string	高度，单位 m
verticalAccuracy	string	垂直精度，单位 m
horizontalAccuracy	string	水平精度，单位 m（Android 无法获取，返回 0）

TIP

当开启高精度定位时，若 highAccuracyExpireTime 设置过低可能导致获取定位失败。

1.4 文件

1.4.1 下载网络文件

SDK 版本号: 1.1.3

API： mos.downNetFile(Object object)

支持以 Promise 风格调用。 如果为图片或视频类型则保存到相册。

参数

[Object object]

属性	类型	默认值	必填	说明
fileUrl	string		是	文件在线地址，https或http开头
fileName	string		否	文件名称，不带后缀名，为空时自动获取文件在线地址的名称
fileExt	string		否	文件类型，如txt、png等，为空时根据文件在线地址自动判断文件类型
showLoading	string	1	否	是否显示loading，1: 显示 0: 隐藏
showMsg	string	1	否	是否显示保存成功或失败的提示，1: 显示 0: 隐藏

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
message	string	错误信息
data	string	保存的文件路径

1.4.2 下载本地文件

SDK 版本号: 1.1.3

API： mos.downLocalFile(Object object)

支持以 Promise 风格调用。 如果为图片或视频类型则保存到相册。

参数

[Object object]

属性	类型	默认值	必填	说明
file	file		是	文件对象
fileName	string		否	文件名称，不带后缀名，为空时自动获取文件对象中的名称
fileExt	string		否	文件类型，如txt、png等，为空时根据文件对象自动判断文件类型
showLoading	string	1	否	是否显示loading，1: 显示 0: 隐藏
showMsg	string	1	否	是否显示保存成功或失败的提示，1: 显示 0: 隐藏

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
message	string	错误信息
data	string	保存的文件路径

1.5 数据缓存

1.5.1 设置本地缓存

SDK 版本号: 1.1.8

API： mos.setStorage(Object object)

支持以 Promise 风格调用。 将数据存储在本地缓存中指定的 key 中。会覆盖掉原来该 key 对应的内容。除非用户主动删除，否则数据都一直可用。单个 key 允许存储的最大数据长度为 100KB，所有数据存储上限为 1MB。

参数

[Object object]

属性	类型	默认值	必填	说明
appDataKey	string		是	存储的键名，1-500个字符
appDataValue	any		否	存储的数据，最大为100KB，数据为加密存储，加密后数据会变大1.4倍，因此原始数据应控制在70KB以下，支持字符串、数字、布尔、对象、数组

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
message	string	错误信息

1.5.2 获取本地缓存

SDK 版本号: 1.1.8

API： mos.getStorage(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	默认值	必填	说明
appDataKey	string		是	存储的键名，1-500个字符

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
message	string	错误信息
data	string	存储的数据

1.5.3 删除本地缓存

SDK 版本号: 1.1.8

API： mos.removeStorage(Object object)

支持以 Promise 风格调用。

参数

[Object object]

属性	类型	默认值	必填	说明
appDataKey	string		是	存储的键名，1-500个字符

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
message	string	错误信息

1.5.4 清空本地缓存

SDK 版本号: 1.1.8

API： mos.clearStorage()

支持以 Promise 风格调用。

参数

无

响应

属性	类型	说明
result	string	'SUCCESS': 成功 | 'FAILURE': 失败
message	string	错误信息