1.1 Open Interfaces

Unless otherwise noted, the following APIs support Promise-style calls: resolve when result is 'SUCCESS', otherwise reject.

Exceptions: mos.isMosEnv is a synchronous read-only property; mos.registerHandler registers a callback. Neither follows the Promise convention above.

1.1.1 Check MOS Environment

SDK version: 1.1.10

API: mos.isMosEnv

Synchronous read-only property that returns a boolean. No await needed.

Description

Synchronously checks whether the current page is in the MOS bridge environment (App / PC shell), used to decide if native capabilities can be called.

• true: Current page is inside MOS App / PC shell; native APIs are available
• false: Regular browser

if (mos.isMosEnv) {
  // Inside MOS App / PC shell, native APIs are available
  const sign = await mos.getSign()
} else {
  // Regular browser
  console.log('Not in MOS environment')
}

1.1.2 Login

SDK version: 1.1.0

API: mos.login(appKey)

Supports Promise-style invocation.

Parameters

Property	Type	Required	Description
appKey	string	true	Mini-App appKey

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
code	string	login credential

1.1.3 Share Text

SDK version: 1.1.0

API: mos.shareToApp(content)

Supports Promise-style invocation. Share text through mos.

Parameters

Property	Type	Required	Description
content	string	true	Text content to be shared out

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure

1.1.4 Get User Information

SDK version: 1.1.0

API: mos.getUserInfo(Object object)

Supports Promise-style invocation. Silently granting authorization will not cause an authorization window to pop up.

Parameters

[Object object]

Property	Type	Required	Description	Least version
authorizedDesc	string	true	Purpose of Obtaining Authorization Information
closeOnClickOverlay	string	false	Whether to close the pop-up window after clicking the mask layer, 0: do not close, 1: close	1.1.2

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure | CANCEL': user cancel
authorized	number	0: Not Authorized | 1: Authorized | 2: No Corresponding Information
firstName	string	Surname
lastName	string	Given Name
headPortrait	string	Avatar URL
descriptor	string	Profile Bio

1.1.5 Get User Mobile/Email Information

SDK version: 1.1.0

API: mos.getUserContactInfo(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Required	Description	Least version
authorizedDesc	string	true	Purpose of Obtaining Authorization Information
closeOnClickOverlay	string	false	Whether to close the pop-up window after clicking the mask layer, 0: do not close, 1: close	1.1.2

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure | CANCEL': user cancel
authorized	number	0: Not Authorized | 1: Authorized | 2: No Corresponding Information
dialCode	string	Area code
phone	string	Mobile Number
email	string	Email address

1.1.6 Get User Unique Signature

SDK version: 1.1.0

API: mos.getSign()

Supports Promise-style invocation. urpose of Obtaining User Signature to verify whether MOS has switched user accounts.

Parameters

None

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
sign	string	Signature

1.1.7 Get Current Language

SDK version: 1.1.0

API: mos.getLanguage()

Supports Promise-style invocation.

Parameters

None

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
lang	string	Language, e.g. en-US

TIP

lang Field Description:

• MosApp supports the following language types:
  • 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 Invoke Payment

SDK version: 1.1.0

API: mos.pay(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Required	Description
amount	string	true	Amount
currency	string	true	Currency USD: US Dollar
appKey	string	true	Mini-App appKey
prepayId	string	true	Order Prepayment ID

Response

Property	Type	Description
result	string	SUCCESS: Payment succeeded | PAYING: Payment in progress | CANCEL: User canceled
data	string	The data field (containing server response) is only provided when payment result is SUCCESS.

Note

SUCCESS (succeeded) and PAYING (in progress) are not final payment results. Actively query the order status via the backend open API /open-apis/mp/v1/pay/orderQuery to confirm the final result.

1.1.9 Get Window Information

SDK version: 1.1.0

API: mos.getWindowInfo()

Supports Promise-style invocation.

Parameters

None

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
statusBarHeight	number	Status Bar Height

1.1.10 Get Device Information

SDK version: 1.1.0

API： mos.getAppBaseInfo()

Supports Promise-style invocation.

Parameters

None

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
platform	string	APP Platform, 'IOS' | 'ANDROID' | 'WINDOWS' | 'MAC' | 'LINUX'
SDKVersion	string	supported mos-js version, e.g: 1.1.0
language	string	APP language, e.g: 'en-US'
version	string	APP version, e.g: '1.1.0'
deviceId	string	device id
brand	string	device brand
system	string	system version

1.1.11 Share Mini-App Page

SDK version: 1.1.0

API: mos.shareMiniApp(Object object)

Supports Promise-style invocation.

Compatibility only

This API is kept for backward compatibility only. Migrate to mos.registerHandler (action: 'moreButton') as soon as possible so share parameters are set when the user taps More, with optional success / fail / complete callbacks.

Sets share parameters for the top-right More button. The call also syncs into the current page's moreButton registration: even without a separate registerHandler call, the App can pull the same parameters when the user taps More (equivalent to registering data only, with no result callbacks). Existing pages that only call this API can keep working temporarily, but new pages should use registerHandler directly.

If used together with registerHandler, the data from the later call wins. See 1.1.12.

Parameters

[Object object]

See Appendix: Share Parameters.

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
shareLink	string	current page link, e.g. https://mp.mos.me/mp/<miniapp_id>?query=xxxxx

1.1.12 Register More Button Callback

SDK version: 1.1.10

API: mos.registerHandler(Object object)

Registers More-button share config for the App to pull (recommended — prefer this API): when the user taps More, the App reads the current page's data as share parameters; after handling, it may invoke success / fail / complete.

Registration is scoped per page; page switches are managed by the SDK. If custom share content is not needed, you do not have to register — the App falls back to default sharing. mos.shareMiniApp is compatibility-only: calling it alone also registers this page's moreButton (same as providing data only, with no result callbacks). Migrate to this API as soon as possible.

When used together with shareMiniApp:

Order	Behavior
registerHandler first, then shareMiniApp	Updates share data only; keeps existing success / fail / complete, etc.
shareMiniApp first, then registerHandler	Fully replaces this page's moreButton (this API wins)
Conflicting data	The later write wins

Parameters

[Object object]

Property	Type	Required	Description
action	string	true	Fixed value: moreButton
data	object	false	Share content for this tap; see Appendix: Share Parameters
success	function	false	Success callback; res.data is the share link for this tap
fail	function	false	Failure callback
complete	function	false	Complete callback (called on both success and failure)
callbackId	string | null	false	Pass null explicitly when success / fail / complete are not needed

mos.registerHandler({
  action: 'moreButton',
  data: {
    query: { path: '/profile' },
    shareDisabled: '0',
    desc: 'Page description',
    imageUrl: '',
    screenShotDisabled: '0',
  },
  success(res) {
    // res.data is the share link for this tap
    console.log('success', res.data)
  },
  fail(error) {
    console.log('fail', error)
  },
  complete(res) {
    console.log('complete', res)
  },
})

1.1.13 Share Mini-App Page Data, Notify Mobile to Open Forwarding Page

SDK version: 1.1.0

API: mos.shareMiniAppData(Object object)

Supports Promise-style invocation.

Opens the forward-to-chat UI. Affects only this proactive share, and does not change the share content of the top-right More button.

Parameters

[Object object]

See Appendix: Share Parameters.

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
shareLink	string	current page link, e.g. https://mp.mos.me/mp/<miniapp_id>?query=xxxxx

Appendix: Share Parameters

Shared object (not an API)

This section is not a standalone API. It defines the share parameter object reused by the share-related APIs above. When an API says “see Share Parameters”, it links here.

This object is used by:

• mos.registerHandler data (action: 'moreButton')
• mos.shareMiniApp request parameters
• mos.shareMiniAppData request parameters

Fields

Property	Type	Required	Description
query	string | object	No	Launch parameters. See query field description below
shareDisabled	string	No	Disable sharing: 1 disabled | 0 enabled
desc	string	No	Page description, usually the current page title
imageUrl	string	No	Image URL shown on the Mini-App message card; HTTPS recommended
screenShotDisabled	string	No	Disable screenshot for the Mini-App message card image: 1 disable | 0 auto screenshot

query Field Description

TIP

Query Field Description:

• If query is an object type and has an ogLang property, the page will prioritize using this property value as the language when parsing og tags. The values for ogLang are:
  • 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 - हिन्दी
• If you want to make your sharing link more attractive, you can tell applications that support OG tags (such as Telegram, Facebook, Twitter, etc.) to customize OG tags to determine the title, description, image, and redirect address of the link, so that users can more easily understand the content of the micro application when sharing.
  Query supports setting four main attributes to customize shared content:
• ogTitle : Custom title displayed at the top of the sharing card, corresponding to the og: title tag
• ogDesc : Share description, displayed in the middle of the share card, corresponding to the og: description tag
• ogImg : Share images, preview images displayed on the card, corresponding to the og: image tag
• ogURL : Share the redirect address, the link that the user clicks on after sharing the card, corresponding to the og: URL tag

Image display rules:

• If imageUrl is provided, it takes precedence.
• If imageUrl is empty:
  • screenShotDisabled=1 Show default image (no screenshot)
  • screenShotDisabled=0 Use system auto-screenshot

1.1.14 Get Launch Parameters

SDK version: 1.1.0

API: mos.getLaunchOptions()

Supports Promise-style invocation. Retrieve the Mini-App's launch query parameters, e.g., https://mp.mos.me/mp/<miniapp_id>?query=<query>.

Parameters

None

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
query	string | object	Launch parameters

1.1.15 Add Tracking Event

SDK version: 1.1.1

API： mos.addTrackingEvent(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Required	Description
name	string	true	Event name
data	string	false	JSON string data

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure

1.1.16 Open Native Customer Service Chat Interface

SDK version: 1.1.3

API: mos.folderLinkClick(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Required	Description
link	string	true	Customer service link, e.g.: https://mos.me/xxxxyyyyzzz
query	object	false	Supports parameters like customer source, context function, etc.

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure

1.1.17 Get Short Link

SDK version: 1.1.4

API： mos.getShortLink(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Required	Description
link	string	true	Long link
showLoading	string	1	Whether to show loading, 1: show | 0: hide

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
message	string	Error message
data	string	Short link

1.1.18 Open MiniApp

SDK version: 1.1.6

API： mos.openMiniApp(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Required	Default Value	Description
miniAppId	String	true		MiniApp ID
name	string	false		MiniApp Name
headPortrait	string	false		MiniApp HeadPortrait
query	string | object	false		Launch Parameters

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure

1.1.19 Open Internal Link

SDK version: 1.1.7

API： mos.openInternalLink(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Required	Description
link	string	true	Internal link, e.g.: https://mos.me/xxxxyyyyzzz

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure

1.2 Device

1.2.1 scanCode

SDK version: 1.1.0

API： mos.scanCode()

Supports Promise-style invocation.

Parameters

None

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure | CANCEL': user cancel
code	string	qrCode value

1.2.2 Make Phone Call

SDK version: 1.1.0

API: mos.makePhoneCall(phoneNumber)

Supports Promise-style invocation.

Parameters

Property	Type	Required	Description
phoneNumber	string	true	Phone number

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure

1.2.3 Set Status bar

SDK version: 1.1.0

API： mos.setStatusbar(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Required	Description
show	string	1	1: show | 0: hide
style	string	dark	Status bar font style dark: dark | light: light

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure

1.3 Location

1.3.1 Get Location

SDK version: 1.1.3

API: mos.getLocation(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Default	Required	Description
isHighAccuracy	string	0	false	Enable high-accuracy positioning, 1: enable | 0: disable
highAccuracyExpireTime	string	30000	false	High-accuracy positioning timeout (ms). Returns highest accuracy within specified time. Values above 3000ms are required for high-accuracy positioning to take effect

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
latitude	string	Latitude, range -90~90, negative for south
longitude	string	Longitude, range -180~180, negative for west
address	string	Address information
speed	string	Speed in m/s
accuracy	string	Position accuracy indicating proximity to real location (e.g., 10 means 10m difference from real location, smaller is more accurate)
altitude	string	Altitude in meters
verticalAccuracy	string	Vertical accuracy in meters
horizontalAccuracy	string	Horizontal accuracy in meters (Android cannot get this, returns 0)

TIP

When high-accuracy positioning is enabled, setting highAccuracyExpireTime too low may cause location acquisition to fail.

1.4 Files

1.4.1 Download Network File

SDK version: 1.1.3

API: mos.downNetFile(Object object)

Supports Promise-style invocation. If the file is an image or video, it will be saved to the photo album.

Parameters

[Object object]

Property	Type	Default	Required	Description
fileUrl	string		true	File online URL, starting with https or http
fileName	string		false	File name without extension. If empty, automatically gets the name from the file URL
fileExt	string		false	File type (e.g., txt, png). If empty, automatically determines from file URL
showLoading	string	1	false	Whether to show loading, 1: show | 0: hide
showMsg	string	1	false	Whether to show success/failure message, 1: show | 0: hide

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
message	string	Error message
data	string	Saved file path

1.4.2 Download Local File

SDK version: 1.1.3

API: mos.downLocalFile(Object object)

Supports Promise-style invocation. If the file is an image or video, it will be saved to the photo album.

Parameters

[Object object]

Property	Type	Default	Required	Description
file	file		true	File object
fileName	string		false	File name without extension. If empty, automatically gets the name from the file object
fileExt	string		false	File type (e.g., txt, png). If empty, automatically determines from file object
showLoading	string	1	false	Whether to show loading, 1: show | 0: hide
showMsg	string	1	false	Whether to show success/failure message, 1: show | 0: hide

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
message	string	Error message
data	string	Saved file path

1.5 Data Cache

1.5.1 Set Local Cache

SDK version: 1.1.8

API: mos.setStorage(Object object)

Supports Promise-style invocation. Stores data in local cache specified by key. Overwrites the original content of the key. Unless the user manually deletes the data, the data will remain available. The maximum data size per key is 100KB, and the total data size limit is 1MB.

Parameters

[Object object]

Property	Type	Default	Required	Description
appDataKey	string		true	Storage key, 1-500 characters
appDataValue	any		false	Storage data, maximum size is 100KB, data is encrypted and stored, encrypted data is 1.4 times larger than the original data, and the original data should not exceed 70KB, supports string, number, boolean, object, array

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
message	string	Error message

1.5.2 Get Local Cache

SDK version: 1.1.8

API： mos.getStorage(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Default	Required	Description
appDataKey	string		true	Storage key, 1-500 characters

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
message	string	Error message
data	string	Stored data

1.5.3 Remove Local Cache

SDK version: 1.1.8

API： mos.removeStorage(Object object)

Supports Promise-style invocation.

Parameters

[Object object]

Property	Type	Default	Required	Description
appDataKey	string		true	Storage key, 1-500 characters

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
message	string	Error message

1.5.4 Clear Local Cache

SDK version: 1.1.8

API： mos.clearStorage()

Supports Promise-style invocation.

Parameters

None

Response

Property	Type	Description
result	string	'SUCCESS': Success | 'FAILURE': Failure
message	string	Error message