更新记录

1.0.0（2026-04-03）

v1.0.0 初次上传测试

平台兼容性

uni-app(4.87)

uni-app x(5.06)

etalya-wmpf-runtime

Etalya 封装的 WMPF uni-app UTS 插件，目标是让 uni-app 通过一个 UTS 插件完成 WMPF Android 能力接入。

插件定位

• 作者前缀：etalya
• 功能定位：wmpf runtime
• uni_modules 名称：etalya-wmpf-runtime
• Android 实现方式：UTS + 单 AAR
• 单 AAR 文件：utssdk/app-android/libs/etalya-wmpf-runtime-android.aar

前置条件

• 仅支持 Android
• iOS 当前为占位实现，不可用
• 设备上必须安装并运行 WMPF Service APK
• 使用新增 AAR、Manifest、原生依赖时，建议使用自定义基座或云打包安装包验证
• 激活失效监听等 2.2+ 能力，要求设备端 WMPF 版本不低于 2.2

已封装能力

• 初始化：init
• 快速验证初始化：quickInitByTicket
• 快速验证一键启动：quickLaunchMiniProgram
• 设备能力：activateDevice、isDeviceActivated、getDeviceId
• 小程序能力：preload、warmUpApp、launchMiniProgram、closeMiniProgram
• 账号能力：login、isLogin、logout
• 推送能力：getPushToken、onPushMessage
• 设备认证能力：registerMiniProgramDevice、prefetchDeviceToken、getMiniProgramDeviceInfo
• UI 能力：setZoom
• 事件监听：onActivationOutdated

最实际的调用顺序

快速验证

适合你先把链路跑通。

1. quickInitByTicket
2. quickLaunchMiniProgram 或者 launchMiniProgram
3. 需要推送时调用 onPushMessage
4. 需要验证激活失效监听时调用 onActivationOutdated

正式接入

适合生产环境。

1. 服务端下发 hostAppId/productId/keyVersion/deviceId/signature
2. 客户端调用 init
3. 可选调用 activateDevice
4. 可选调用 preload 或 warmUpApp
5. 调用 launchMiniProgram
6. 需要登录时调用 login
7. 需要推送时调用 getPushToken 和 onPushMessage
8. 需要设备认证时调用 registerMiniProgramDevice 等接口

Quick 示例

import {
  quickInitByTicket,
  quickLaunchMiniProgram,
  onPushMessage,
  onActivationOutdated,
} from '@/uni_modules/etalya-wmpf-runtime'

quickInitByTicket({
  ticket: 'YOUR_TICKET',
  wxaAppId: 'YOUR_WXA_APPID',
  hostAppId: 'YOUR_HOST_APPID',
  activate: true,
  success: (device) => {
    console.log('device', device)
  },
  fail: (e) => {
    console.error('quick init failed', e)
  },
})

quickLaunchMiniProgram({
  ticket: 'YOUR_TICKET',
  wxaAppId: 'YOUR_WXA_APPID',
  hostAppId: 'YOUR_HOST_APPID',
  appId: 'YOUR_WXA_APPID',
  path: '',
  appType: 'RELEASE',
  activate: true,
})

onPushMessage({
  listener: (msg) => {
    console.log('push msg', msg)
  },
})

onActivationOutdated((msg) => {
  console.log('activation outdated', msg)
})

Production 示例

import {
  init,
  activateDevice,
  preload,
  warmUpApp,
  launchMiniProgram,
  setZoom,
  login,
  isLogin,
  logout,
  getPushToken,
} from '@/uni_modules/etalya-wmpf-runtime'

init({
  device: {
    hostAppId: 'YOUR_HOST_APPID',
    productId: 0,
    keyVersion: 0,
    deviceId: 'YOUR_DEVICE_ID',
    signature: 'YOUR_SIGNATURE',
  },
  activate: false,
  success: () => {
    console.log('init ok')
  },
})

activateDevice({})
preload({})

warmUpApp({
  appId: 'YOUR_WXA_APPID',
  path: '',
  appType: 'RELEASE',
})

launchMiniProgram({
  appId: 'YOUR_WXA_APPID',
  path: '',
  appType: 'RELEASE',
  landscapeMode: 'NORMAL',
})

setZoom({
  zoom: 1.25,
})

login({
  style: 'FULLSCREEN',
  success: (res) => console.log('oauthCode', res.oauthCode),
})

isLogin({ success: (res) => console.log('isLogin', res.isLogin) })
logout({})

getPushToken({
  appId: 'YOUR_WXA_APPID',
  success: (res) => console.log('pushToken', res.pushToken),
})

Demo 页面

项目里已经提供一个最直接的联调页面：

• index.vue

它包含：

• Quick 初始化
• Quick 启动
• getDeviceId
• isDeviceActivated
• preload
• warmUpApp
• login / isLogin / logout
• getPushToken
• onPushMessage
• setZoom
• onActivationOutdated

常见问题

1. 为什么运行时报找不到 com.tencent.wmpf...

• 一般是标准基座未合入新的原生 AAR
• 解决方式：使用自定义基座或云打包安装包验证

2. 为什么 quick 模式也要 hostAppId

• quick 模式本质上也是按 WMPF 设备初始化流程在跑
• 只是设备信息由 ticket 接口返回，不是你服务端自己签发

3. 为什么单 AAR 里还有 libs/logger-1.2.jar 和 libs/protobuf.jar

• 这是 WMPF SDK 原始 AAR 自带的本地 jar 依赖
• 当前单 AAR 打包任务会把这些依赖一起保留在最终产物中

4. 激活失效监听为什么不是 options 方式

• 这是为了让持续监听在 uni-app/UTS 场景里更稳定
• 当前接口直接采用 onActivationOutdated((msg)=>{})

构建单 AAR

如果你后续重新生成单 AAR，在 UniPlugin-Hello-AS 目录执行：

./gradlew :etalya_wmpf_runtime_android:bundleReleaseSingleAar

生成路径：

UniPlugin-Hello-AS/etalya_wmpf_runtime_android/build/outputs/aar/etalya-wmpf-runtime-android.aar

错误码

• 9010001 参数错误
• 9010002 未初始化
• 9010003 当前平台或当前版本不支持
• 9010004 网络错误（主要用于 quick 模式 ticket 拉设备信息）
• 9010005 WMPF API 错误
• 9010006 未知错误