1. YMTrack
文档站
  • onemore
    • onemore 鸿蒙对接文档
    • 一盟广告 Android SDK接入文档
    • 一盟广告 iOS SDK接入文档
  • YMTrack
    • Cocos 微信小游戏接入文档
  1. YMTrack

Cocos 微信小游戏接入文档

YMTrack Cocos 微信小游戏接入文档#

概述#

本文档面向 Cocos Creator 微信小游戏接入方。
Cocos 微信小游戏请选择 ymtrack-wx-game。

接入步骤#

1. 获取 SDK#

从 SDK 发布包中获取：
ymtrack-wx-game/index.js
ymtrack-wx-game/index.d.ts
放入 Cocos 项目：
assets/scripts/sdk/ymt/index.js
assets/scripts/sdk/ymt/index.d.ts
Cocos Creator 3.x 不支持目录导入，CommonJS 或 TypeScript 引入时都要写到具体文件，不要写成 require('./sdk/ymt') 或 import ymt from './sdk/ymt'。

2. 初始化#

在首个场景或启动脚本中初始化：
import ymt from './sdk/ymt/index.js'

ymt.init({
  appKey: 'your-app-key',
  debug: true,
})

ymt.setCurrentPage('GameScene')
小游戏场景下，SDK 会在平台支持时自动绑定：
wx.onShow
wx.onHide
wx.onError
没有微信小游戏运行时的环境中，SDK 会自动跳过初始化，不会发起真实上报。小游戏开发者工具或 wx.request 暂不可用时，SDK 可以正常初始化；开启 debug 后会打印 payload，但不会真实发送。
SDK 使用 request 发送上报数据，需要在微信小程序后台把 https://service.zhaomuqingyun.com 添加到 request 合法域名中。

设置 OpenId#

业务拿到 openId 后调用：
ymt.setOpenId('openid_123')

Debug 与模拟器#

ymt.init({
  appKey: 'your-app-key',
  debug: true,
})
开启后：
打印完整上报数据
模拟器/开发者工具中只打印，不真实发送
真机环境中打印并发送

自定义事件#

事件名会统一使用 ymt_ 前缀。业务侧可以直接传业务事件名，SDK 会自动补齐前缀；如果已经传入 ymt_ 开头的事件名，会保持不变。
ymt.track('button_click', {
  buttonName: 'start',
})

注册与角色#

注册#

用户完成注册或首次完成业务账号体系注册时调用。
ymt.register({
  registerType: 'wechat',
})

创建角色#

玩家创建角色成功后调用。
固定参数：
字段含义
roleId角色 ID
roleName角色名称
serverId区服 ID
serverName区服名称
ymt.role.create({
  roleId: 'role_001',
  roleName: '玩家昵称',
  serverId: 's1',
  serverName: '一区',
})

进入游戏#

玩家选择区服并进入游戏时调用。
固定参数：
字段含义
roleId角色 ID
serverId区服 ID
serverName区服名称
ymt.enterGame({
  roleId: 'role_001',
  serverId: 's1',
  serverName: '一区',
})

玩家等级 Level#

level 表示玩家等级或升级，不表示关卡。
固定参数：
字段适用 API含义
levelset当前玩家等级
sourceset等级来源，例如登录同步、存档恢复
fromLevelup升级前等级
toLevelup升级后等级
reasonup升级原因，例如经验足够、任务奖励
expup本次升级相关经验值
ymt.level.set({
  level: 10,
  source: 'login_sync',
})

ymt.level.up({
  fromLevel: 10,
  toLevel: 11,
  reason: 'exp_enough',
  exp: 1200,
})

关卡 Stage#

stage 表示关卡、副本、局内阶段、轮次或检查点。
固定参数：
字段适用 API含义
stageIdstart / running / pause / exit / end关卡、副本或局内阶段 ID
stageNamestart关卡名称
stageTypestart关卡类型，例如主线、活动、副本
difficultystart难度
resultend关卡结果，例如 success、fail
durationSecpause / exit / end当前关卡持续时长，单位秒
scoreend关卡得分
eventrunning关卡进行中的二级行为名称
roundrunning回合、波次或阶段序号
reasonpause / exit暂停或退出原因

开始关卡 / 结束关卡#

开始关卡和结束关卡表示一个关卡的正常生命周期，应该配套使用。通常在关卡资源、配置、棋盘或场景准备完成后调用 start，在胜利、失败、结算完成等明确结果出现后调用 end。
ymt.stage.start({
  stageId: '1-1',
  stageName: '第一关',
  stageType: 'main',
  difficulty: 'normal',
})

ymt.stage.end({
  stageId: '1-1',
  result: 'success',
  durationSec: 86,
  score: 1200,
})

更新关卡状态#

关卡进行中的二级行为。适合上报关卡过程中的阶段性事件，例如多个回合、出现选择技能、出现活动礼包等。
它和 track 的区别是：running 明确限定在关卡进行中。
ymt.stage.running({
  stageId: '1-1',
  event: 'skill_select_show',
  round: 2,
})

暂停游戏#

玩家手动暂停游戏时调用。
ymt.stage.pause({
  stageId: '1-1',
  reason: 'user_pause',
  durationSec: 30,
})

关闭游戏#

玩家手动关闭或退出游戏时调用，例如返回首页、退出本局或放弃挑战。
ymt.stage.exit({
  stageId: '1-1',
  reason: 'back_home',
  durationSec: 45,
})

分享#

固定参数：
字段含义
shareType分享类型，例如 app_message、timeline
shareFrom分享入口，例如 result_page、home_page
stageId分享发生时关联的关卡 ID
ymt.share({
  shareType: 'app_message',
  shareFrom: 'result_page',
  stageId: '1-1',
})

付费 Revenue#

固定参数：
字段含义
orderId订单 ID
productId商品 ID
productName商品名称
amount支付金额
currency币种，例如 CNY
payChannel支付渠道，例如 wechat
stageId支付发生时关联的关卡 ID
level支付发生时的玩家等级
ymt.revenue({
  orderId: 'order_001',
  productId: 'coin_pack_6',
  productName: '金币礼包',
  amount: 6,
  currency: 'CNY',
  payChannel: 'wechat',
  stageId: '1-3',
  level: 12,
})

领取礼包#

固定参数：
字段含义
giftId礼包 ID
giftName礼包名称
giftType礼包类型，例如新手、活动、登录奖励
amount领取数量
source领取入口或来源
ymt.gift.claim({
  giftId: 'new_user_pack',
  giftName: '新手礼包',
  giftType: 'new_user',
  amount: 1,
  source: 'login',
})

广告#

广告用于上报广告流程中的各个阶段。默认按激励视频理解，也可以通过 adType 传入 banner、native 等其他广告类型。广告位 ID adUnitId 必填。
固定参数：
字段适用 API含义
adUnitIdload / loadFail / show / error / close / reward平台广告位 ID，必填
adTypeload / loadFail / show / error / close / reward广告类型，默认 rewarded_video，可传 banner、native 等
placementshow / error / close / reward广告展示时机或业务场景，例如 task_fail_show、shop_reward_show、double_reward_show
errorCodeloadFail / error广告加载、展示或播放失败时的平台错误码
errorMessageloadFail / error广告加载、展示或播放失败时的错误信息
isEndedclose激励视频关闭时是否完整观看
rewardNamereward激励奖励名称，例如 revive、double_coin
rewardAmountreward激励奖励数量

加载广告上报#

加载广告时调用。
ymt.ad.load({
  adUnitId: 'adunit-xxx',
  adType: 'rewarded_video',
})

广告加载失败上报#

广告加载失败时调用。
ymt.ad.loadFail({
  adUnitId: 'adunit-xxx',
  adType: 'rewarded_video',
  errorCode: 1001,
  errorMessage: 'load failed',
})

展示广告上报#

展示广告成功时调用。placement 用来区分展示时机，例如任务失败展示、商城奖励展示、双倍奖励展示。
ymt.ad.show({
  adUnitId: 'adunit-xxx',
  adType: 'rewarded_video',
  placement: 'task_fail_show',
})

广告异常上报#

广告展示或播放过程中出现异常时调用。
ymt.ad.error({
  adUnitId: 'adunit-xxx',
  adType: 'rewarded_video',
  placement: 'task_fail_show',
  errorCode: 1002,
  errorMessage: 'show failed',
})

关闭广告上报#

广告关闭时调用。激励视频可通过 isEnded 表示是否完整观看。
ymt.ad.close({
  adUnitId: 'adunit-xxx',
  adType: 'rewarded_video',
  placement: 'task_fail_show',
  isEnded: true,
})

广告发奖上报#

激励广告满足发奖条件并完成发奖后调用。banner、native 等非激励广告通常不需要调用。
ymt.ad.reward({
  adUnitId: 'adunit-xxx',
  adType: 'rewarded_video',
  placement: 'task_fail_show',
  rewardName: 'revive',
  rewardAmount: 1,
})
修改于 2026-08-31 06:34:02
上一页
一盟广告 iOS SDK接入文档
Built with