美团游戏开放平台

# 添加桌面快捷方式

# 一、基本介绍

为了提升用户的游戏心智和游戏曝光，游戏中增加添加桌面功能。此系统能有效提升活跃用户回流，为游戏玩家提供能方便快捷进入游戏的方式。

您可以通过以下方法，在系统桌面创建及管理一个快捷方式，让用户可以直接通过桌面入口进入到您的小游戏中。游戏在上线前必须接入该功能。

操作说明 示意图 功能要求
入口 img 1、添加桌面功能一般在进入游戏后2-5分钟左右展示，或者在无强制引导后展示；
2、UI需要包含icon和文字，文案为“桌面福利”;
3、UI需要有红点或动效展示，在玩家添加桌面并领取奖励前，特效需要一直展示；
页面展示 img 1、顶部主标题为“桌面收藏”；
2、上部文案为“添加游戏图标到手机桌面可快速进入游戏，同时获得丰厚奖励”；
3、奖励建议以招募券、货币或其他游戏内消耗道具为主，奖励类型建议3种（高品质1个，中品质1个，低品质1个）；
4、下部需要在UI内添加文案：前往系统设置，为美团打开“创建桌面快捷方式”权限；其他文案内容可以参考寻道大千；
5、按钮文案为“添加桌面”，添加完成后文案变为“领取奖励”，每个角色只能领取一次奖励；
6、因无法确认玩家设备中美团APP是否有添加桌面快捷方式的权限，需要此功能一直保留在游戏首页，除领取奖励以外，其他逻辑每日刷新，具体可以参考《向僵尸开炮》

# 二、添加桌面任务

接入要求：

运营侧：

  1. 将游戏添加为桌面快捷方式为一次性任务。
  2. 为了提升用户加桌意愿，需要开发在游戏中增加添加桌面入口，并将入口放在一级界面中，须设置提示，红点、动效等等引导。
  3. 添加桌面功能文案统一为"桌面福利"。
  4. 联系美团运营获取美术素材要求，包含横版和竖版素材规范，开发者只需替换游戏的相关素材即可。
  5. 添加桌面任务发放奖励价值不低于50元，具体奖励和页面效果图在实装到游戏前与美团运营确认。
  1. 通过调用 mt.addShortcut 接口添加桌面快捷方式。
  2. 在 mt.addShortcut 的 success 回调中判断添加成功，即可触发任务奖励下发逻辑。

详情可参考本文档 二、接入接口 中的 mt.addShortcut 部分。

# 三、桌面复访任务

接入要求：

运营侧：

  1. 此任务为多次任务，一般跟随创角设置为7天复访，添加桌面完成后的首日从桌面快捷方式、桌面KK入口、桌面2×2卡片入口复访即可领取任务奖励。
  2. 为了提升用户加桌意愿，需要开发在游戏中增加添加桌面入口，并将入口放在一级界面中，须设置提示，红点、动效等等引导。
  3. 添加桌面功能文案统一为"桌面福利"。
  4. 联系美团运营获取美术素材要求，包含横版和竖版素材规范，开发者只需替换游戏的相关素材即可。
  5. 桌面复访任务发放奖励价值不低于50元，具体奖励和页面效果图在实装到游戏前与美团运营确认。
  6. 当日复访任务完成，按钮显示"明日再来"，全部复访任务完成，此功能不消失。
  1. 通过渠道参数识别用户来源，判断是否从桌面渠道进入游戏。inner_source参数中包含 'deskicon'、'desk22card'、'desk' 等标识可判断用户来自不同的桌面入口（分别对应桌面快捷方式、桌面2×2卡片、其他桌面入口）。
  2. 获取inner_source参数可以通过mt.getLaunchOptionsSync接口或者onshow的回调（接口可以通过开平文档-API汇总查看）。

# 桌面复访判断示例

// 定义桌面来源标识
const deskSources = ['deskicon', 'desk22card', 'desk'];

// 检查用户是否从桌面入口进入游戏
function isFromDeskEntry(innerSource) {
  return deskSources.includes(innerSource) || deskSources.some((source) => innerSource?.endsWith(`_${source}`));
}

# 实现参考

详见美团线上游戏《西游除妖》中"添加桌面"实现方式：

imgimg

# 四、接入接口

# mt.supportShortcut

  • 说明：查询设备对桌面快捷方式相关能力的支持

  • 支持版本： android: 11.11.400 ios: 不支持、 直接调用 addShortcut 即可

  • 入参

    参数名 类型 默认值 是否必填 说明
    operation int 是 快捷方式能力
    1: 添加 256: 删除
    17: 更新 16: 查询
    type int 2 否 快捷方式类型
    1: 动态快捷方式,Android版本大于24才支持,对应iOS的3D touch
    2: 常规桌面快捷方式，会新增一个图标
    3: 桌面小插件,常见墨迹天气的桌面插件
    success function 否 接口调用成功的回调
    fail function 否 接口调用失败的回调
    complete function 否 接口调用结束的回调（成功/失败都会执行）

  • 出参 Fail

    Error Code 说明
    521 必要参数缺失或无效
    7 功能不支持
    8 系统接口调用失败
    10002 快捷方式已存在
    10003 快捷方式不存在

# mt.addShortcut

  • 说明：添加快捷方式，不支持重复添加··

  • 支持版本： android: 11.11.400 ios: 11.13.400

  • 入参

    参数名 类型 默认值 是否必填 说明
    shortcutType int 2 否 快捷方式类型
    1: 动态快捷方式,Android版本大于24才支持,对应iOS的3D touch
    2: 常规桌面快捷方式，会新增一个图标
    3: 桌面小插件,常见墨迹天气的桌面插件
    id string 是 快捷方式唯一标识
    label string 是（shortcutType = 1 或 2） 快捷方式显示的名称（shortcutType=1 或 2时必填）
    icon string app图标 否 快捷方式图片网络路径
    target string 是（shortcutType = 1 或 2） 快捷方式跳转目标页面（shortcutType=1 或 2时必填）
    widgetProviderId string 是（shortcutType = 3） 桌面小插件唯一标识
    interceptSuccess bool false 否 拦截添加快捷方式成功提示（目前只有addShortcut生效）
    success function 否 接口调用成功的回调。（iOS 中无法保证安装成功，可以默认 API 调用即安装成功）
    fail function 否 接口调用失败的回调
    complete function 否 接口调用结束的回调（成功/失败都会执行）

备注：

  • 参数id制定规则：gameid_appid，appid通过美团开平-开发管理-开发设置查找，例：gameid_mgcxxxxxxxx

  • 参数widgetProviderId制定规则：gameid_widget_appid，appid通过美团开平-开发管理-开发设置查找，例：gameid_widget_mgcxxxxxxxx

  • 参数 target 为快捷方式目标游戏链接，需要在首次提测前向美团运营索取。如果游戏未发布上线，使用该链接跳转可能会失败，游戏发布线上版本即可跳转

  • 出参 Fail

    Error Code 说明
    521 必要参数缺失或无效
    7 功能不支持
    8 系统接口调用失败
    204 快捷方式没有授权
    10002 快捷方式已存在
    10003 快捷方式不存在

# mt.deleteShortcut

  • 说明：删除快捷方式

  • 支持版本： android: 11.11.400 ios: 不支持

  • 入参

    参数名 类型 默认值 是否必填 说明
    shortcutType int 2 否 快捷方式类型
    1: 动态快捷方式,Android版本大于24才支持,对应iOS的3D touch
    2: 常规桌面快捷方式，会新增一个图标
    3: 桌面小插件,常见墨迹天气的桌面插件
    id string 是 快捷方式唯一标识
    label string 是（shortcutType = 1 或 2） 快捷方式显示的名称（shortcutType=1 或 2时必填）
    icon string app图标 否 快捷方式图片网络路径
    target string 是（shortcutType = 1 或 2） 快捷方式跳转目标页面（shortcutType=1 或 2时必填）
    widgetProviderId string 是（shortcutType = 3） 桌面小插件唯一标识
    interceptSuccess bool false 否 拦截添加快捷方式成功提示（目前只有addShortcut生效）
    success function 否 接口调用成功的回调
    fail function 否 接口调用失败的回调
    complete function 否 接口调用结束的回调（成功/失败都会执行）

  • 出参 Fail

    Error Code 说明
    521 必要参数缺失或无效
    7 功能不支持
    8 系统接口调用失败
    204 快捷方式没有授权
    10002 快捷方式已存在
    10003 快捷方式不存在

# mt.updateShortcut

  • 说明：更新快捷方式

  • 支持版本： android: 11.11.400 ios: 不支持

  • 入参

    参数名 类型 默认值 是否必填 说明
    shortcutType int 2 否 快捷方式类型
    1: 动态快捷方式,Android版本大于24才支持,对应iOS的3D touch
    2: 常规桌面快捷方式，会新增一个图标
    3: 桌面小插件,常见墨迹天气的桌面插件
    id string 是 快捷方式唯一标识
    label string 是（shortcutType = 1 或 2） 快捷方式显示的名称（shortcutType=1 或 2时必填）
    icon string app图标 否 快捷方式图片网络路径
    target string 是（shortcutType = 1 或 2） 快捷方式跳转目标页面（shortcutType=1 或 2时必填）
    widgetProviderId string 是（shortcutType = 3） 桌面小插件唯一标识
    interceptSuccess bool false 否 拦截添加快捷方式成功提示（目前只有addShortcut生效）
    success function 否 接口调用成功的回调
    fail function 否 接口调用失败的回调
    complete function 否 接口调用结束的回调（成功/失败都会执行）

  • 出参 Fail

    Error Code 说明
    521 必要参数缺失或无效
    7 功能不支持
    8 系统接口调用失败
    204 快捷方式没有授权
    10002 快捷方式已存在
    10003 快捷方式不存在

# mt.queryShortcut

  • 说明：查询快捷方式

  • 支持版本： android: 11.11.400 ios: 不支持

  • 入参

    参数名 类型 默认值 是否必填 说明
    shortcutType int 2 否 快捷方式类型
    1: 动态快捷方式,Android版本大于24才支持,对应iOS的3D touch
    2: 常规桌面快捷方式，会新增一个图标
    3: 桌面小插件,常见墨迹天气的桌面插件
    id string 是 快捷方式唯一标识
    label string 是（shortcutType = 1 或 2） 快捷方式显示的名称（shortcutType=1 或 2时必填）
    icon string app图标 否 快捷方式图片网络路径
    target string 是（shortcutType = 1 或 2） 快捷方式跳转目标页面（shortcutType=1 或 2时必填）
    widgetProviderId string 是（shortcutType = 3） 桌面小插件唯一标识
    interceptSuccess bool false 否 拦截添加快捷方式成功提示（目前只有addShortcut生效）
    success function 否 接口调用成功的回调
    fail function 否 接口调用失败的回调
    complete function 否 接口调用结束的回调（成功/失败都会执行）

  • 出参

    参数名 类型 值-说明
    exist bool 快捷方式是否存在

    Fail

    Error Code 说明
    521 必要参数缺失或无效
    7 功能不支持
    8 系统接口调用失败
    204 快捷方式没有授权
    10002 快捷方式已存在
    10003 快捷方式不存在

# 五、常见问题FAQ

  • Q：接入中mt.addShortcut成功回调但没有加桌成功，如何处理？
  • A：success代表接口调用成功，不代表加桌成功。对于android设备需要通过mt.queryShortcut查询加桌状态,注意不要在 mt.addShortcut 回调 success 之后立即调用 mt.queryShortcut，因为用户交互确认安装是异步流程。可以在用户与游戏重新交互时（说明此时系统交互已结束）查询安装结果。
上次更新: 8/10/2026, 5:36:37 PM