跳到主要内容

游戏行为上报接入文档

1. 功能说明​

游戏行为上报主要用于渠道导流等场景，可引导新用户更深入地体验游戏内容。

用户在游戏内完成开放平台配置的目标行为后，CP 需要将行为完成结果同步给芒果TV小游戏平台。对于可多次上报的行为任务，游戏中心及悬浮球会同步展示当前进度，例如“3/10”；任务完成后展示“已完成”状态，并触发奖励发放。

开发者仅需配置并上报行为，任务目标、任务奖励等其他参数由芒果TV内部配合设置。

2. 接入前准备​

  1. 注册芒果TV账号，并创建小游戏。
    当前“游戏行为上报”仅支持小游戏，不支持小程序。

  2. 进入芒果TV开放平台，选择对应小游戏，进入“开放能力”页。

  3. 在开放能力页申请开通“游戏行为上报”能力。
    申请时需提供使用场景描述和场景示例截图。运营一般在 1 个工作日内完成审核。

3. 创建行为标识​

开通“游戏行为上报”能力后，即可创建游戏行为。单个游戏最多可创建 20 个游戏行为。

创建时请谨慎填写以下字段：

字段说明
行为名称后台配置、审核专用的标识名称，需规范填写，不可随意命名。示例：关卡通关上报
行为标识行为标识必须唯一，支持英文、数字、下划线。示例：game_addexp_01
上报规则分为两类：
行为结果上报：仅判定行为是否完成，上报一次即代表达成，addValue 填 1，适用于击杀 BOSS 等结果判断场景。
数据增量上报：上报本次新增的正整数值，适用于获取金币、经验、人物等级等数据递增场景。
上报时机描述重要。请明确描述该上报触发的时机，以便后续进行任务配置。时机描述错误会导致任务配置错误。

4. 如何上报​

CP 在小游戏前端调用芒果TV提供的 mgtv.reportBehaviorTask 接口完成上报。平台会自动完成行为数据上报，并实时更新用户可见的任务进度。

调用前准备：获取 uuid 与 ticket​

mgtv.reportBehaviorTask 需要用户 uuid 与 ticket 作为必传参数，用于平台识别上报用户。上报前需先调用 mgtv.getUserProfile 获取。

调用时机​

  • 在用户完成指定目标后立即上报。
  • 数据增量上报需注意应传差值。
    示例：获得金币时，应上报本次获得的金币数额，而不是当前金币总额。

调用示例​

// 1. 先获取用户 uuid 和 ticket
mgtv.getUserProfile({
  success(res) {
    const { uuid, ticket } = res.data
    reportBehavior(uuid, ticket)
  },
  fail(res) {
    console.log('获取用户信息失败', res)
  }
})

function reportBehavior(uuid, ticket) {
  // 行为结果上报：仅上报行为完成，addValue 填 1
  mgtv.reportBehaviorTask({
    behaviorId: 7,
    behaviorKey: 'game_addexp_01',
    addValue: 1,
    uuid,
    ticket,
    success(res) {
      console.log('行为上报成功', res)
    },
    fail(res) {
      console.log('行为上报失败', res)
    }
  })
}

参数说明​

参数名类型必填说明
behaviorIdnumber是行为标识，开放平台配置的行为 id
behaviorKeystring是行为 key，开放平台配置的行为标识，与任务配置完全一致（区分大小写）
addValuenumber是本次行为进度增量，必须为非负整数。行为结果上报填 1；数据增量上报填本次新增的正整数值（差值）
uuidstring是用户 uuid，通过 mgtv.getUserProfile 获取
ticketstring是用户 ticket，通过 mgtv.getUserProfile 获取
successfunction否接口调用成功的回调函数
failfunction否接口调用失败的回调函数
completefunction否接口调用结束的回调函数（调用成功、失败都会执行）

完整的接口说明及返回详情请见：
mgtv.reportBehaviorTask

5. 后续创建任务和相关合作​

如需在芒果TV小游戏中心及游戏悬浮球内展示相关任务，可联系对应运营人员配合上线。

双方协商并整理任务表。目前支持单次任务、日常任务、周常任务，并可灵活设置任务达成时的奖励目标。