跳到主要内容

mgtv 加桌（桌面图标）

信息

框架版本 1.4.5 开始支持，其中框架版本通过 mgtv.getDeviceInfo()（同步接口）返回对象的 frameworkVersion 字段获取。

小游戏加桌（桌面图标）能力：在用户主动授权后，把当前小游戏以图标形式添加到手机桌面，用户可像原生 App 一样从桌面直接启动游戏。该能力对提升小游戏次日留存与复访率有直接作用。

三个接口均需在真机上调试验证。开发者工具不支持，请在业务侧做好降级处理，避免阻断游戏主流程。

本组接口包含：

接口作用
mgtv.installShortcut创建桌面图标（加桌），每次创建都需要用户授权
mgtv.hasShortcutInstalled查询是否已创建桌面图标，success 直接回调 true / false
mgtv.isStartupByShortcut查询本次是否由桌面图标启动，success 直接回调 true / false

mgtv.installShortcut(Object object)​

创建桌面图标。请在用户通关、结算等正向节点触发，避免用户一进入游戏就弹加桌（影响体验）。

object 参数为可选参数，调用时可不传，也可仅传入回调。

Object object​

属性类型默认值必填说明
successfunction否接口调用成功的回调函数
failfunction否接口调用失败的回调函数
completefunction否接口调用结束的回调函数（调用成功、失败都会执行）

成功时走 success；失败时走 fail 回调。

mgtv.installShortcut({
  success: () => {
    // 加桌成功：发放奖励等
  },
  fail: (err) => {
    console.log('加桌失败', err)
  }
})

mgtv.hasShortcutInstalled(Object object)​

查询是否已经创建桌面图标。

success 回调参数直接为布尔值（true 已创建 / false 未创建），而非 { data } 对象。

Object object​

属性类型默认值必填说明
successfunction否接口调用成功的回调函数。参数：true 已创建，false 未创建
failfunction否接口调用失败的回调函数
completefunction否接口调用结束的回调函数（调用成功、失败都会执行）
mgtv.hasShortcutInstalled({
  success: (installed) => {
    if (installed) return
    // 未加桌：引导加桌
  },
  fail: (err) => {
    console.warn('hasShortcutInstalled fail', err)
  }
})

mgtv.isStartupByShortcut(Object object)​

查询本次是否由桌面图标启动，用于启动场景的差异化承接。建议在游戏启动早期调用一次。

success 回调参数直接为布尔值（true 桌面启动 / false 其他方式启动）。

Object object​

属性类型默认值必填说明
successfunction否接口调用成功的回调函数。参数：true 桌面启动，false 其他方式启动
failfunction否接口调用失败的回调函数
mgtv.isStartupByShortcut({
  success: (fromDesktop) => {
    if (fromDesktop) {
      // 桌面启动：直接进入核心玩法等差异化承接
    }
  },
  fail: (err) => {
    console.warn('isStartupByShortcut fail', err)
  }
})

示例代码​

// 版本比较：a > b 返回 1，a === b 返回 0，a < b 返回 -1
function compareVersion(a, b) {
  const arrA = String(a).split('.').map(Number)
  const arrB = String(b).split('.').map(Number)
  const len = Math.max(arrA.length, arrB.length)
  for (let i = 0; i < len; i++) {
    const x = arrA[i] || 0
    const y = arrB[i] || 0
    if (x > y) return 1
    if (x < y) return -1
  }
  return 0
}

// 1) 游戏启动早期：判断是否从桌面图标启动（差异化承接）
function checkStartupByShortcut() {
  if (!mgtv.isStartupByShortcut) return
  mgtv.isStartupByShortcut({
    success: (fromDesktop) => {
      if (fromDesktop) {
        // 桌面启动：直接进入核心玩法等差异化承接
      }
    },
    fail: (err) => { console.warn('isStartupByShortcut fail', err) }
  })
}

// 2) 通关/结算等正向节点：未加桌才引导加桌，加桌成功发奖励
function tryAddToDesktop() {
  if (!mgtv.hasShortcutInstalled || !mgtv.installShortcut) return
  mgtv.hasShortcutInstalled({
    success: (installed) => {
      if (installed) return
      mgtv.installShortcut({
        success: () => {
          // 加桌成功：发放奖励
        },
        fail: (err) => {
          console.log('加桌失败', err)
        }
      })
    },
    fail: (err) => { console.warn('hasShortcutInstalled fail', err) }
  })
}

// 入口：仅当框架版本 >= 1.4.5 才调用（避免在不支持环境下报错）
const deviceInfo = mgtv.getDeviceInfo()
if (compareVersion(deviceInfo.frameworkVersion, '1.4.5') >= 0) {
  checkStartupByShortcut()
  //在合适的正向节点调用 tryAddToDesktop()
}