@unif/react-native-umeng
友盟（U-Share + U-App 移动统计）的 React Native 新架构桥:一次 await Share.openSheet(payload) 拉起分享面板,一行 Analytics.onEvent(id) 记录埋点,统计采集遵循 PIPL 两段式合规。
这个库是什么
它在友盟官方 SDK(U-Share 社会化分享 + U-App 移动统计)之上,封装出一套新架构(TurboModule)友好、UI 文案中文的 React Native 接口。对外只有三个命名空间加一个宿主组件:
Common——preInit/init/isInited,PIPL 两段式初始化。Share——openSheet(命令式分享面板)/shareText/shareImage/shareLink/isInstalled/listPlatforms。Analytics——onEvent/signIn/signOut,自定义事件与账号埋点。<ShareSheetHost />—— 命令式分享面板的宿主组件,在 App 根挂一次。
分享面板的 UI 直接复用 @unif/react-native-design 的 BottomSheet + Cell,与 design 的 toast() / confirm() 同一套「单例 + Host」模式。
解决什么问题
直接接友盟原生 SDK,你要分别处理 iOS / Android 的初始化时序、平台注册、分享回调跳回、PIPL 合规启停,还要自己拼一套分享面板 UI。本库把这些收敛成几次声明式调用:
import { Share, UmengError } from '@unif/react-native-umeng';
try {
const r = await Share.openSheet({ type: 'link', title: '问问看', url: 'https://example.com' });
// 只有成功才走到这里:r.code 恒为 'success'
} catch (e) {
if (e instanceof UmengError && e.code === 'E_USER_CANCEL') { /* 用户取消 */ }
}
核心概念
- 首版只支持微信会话 + 钉钉 ——
Platform枚举只有WECHAT_SESSION与DINGTALK两个成员。没有朋友圈、QQ、微博;传未支持的平台会抛E_PLATFORM_NOT_SUPPORTED。 - 分享面板 = 单例 controller + Host 组件 ——
Share.openSheet()是推荐用法,它经一个模块级单例拉起<ShareSheetHost />渲染的BottomSheet。Host 必须在 App 根挂一次,否则openSheet立即 reject;一次只能开一个面板。 - 取消 / 失败走 reject,不走 resolve ——
openSheet与shareText/shareImage/shareLink在用户取消或分享失败时抛UmengError(E_USER_CANCEL/E_SHARE_FAILED)。resolve 到手的结果code恒为'success'—— 永远 try/catch,别去判r.code === 'cancel'(到不了)。 - PIPL 两段式:
preInit(不上报)→ 同意 →init(开始采集) ——Common.preInit(config)在 App 启动后立刻调,只存配置、注册平台,不上报任何数据;用户同意《隐私协议》后再调无参的Common.init()才正式启动采集。 - 统计是同步
void——Analytics.onEvent / signIn / signOut没有 Promise,不要 await。
能力
- 命令式分享面板 ——
Share.openSheet({ type, ... })一行拉起BottomSheet,用户选平台,Promise resolve 成功 / reject 取消失败。 - 三种分享内容 —— 文本(
'text')、图片('image')、链接('link'),面板与直拉变体共用同一套payload。 - 直拉单平台 —— 不需要面板时,
Share.shareText / shareImage / shareLink跳过 UI 直接发到指定平台。 - PIPL 合规初始化 ——
preInit/init两段式,满足「用户同意前不采集」。 - 自定义事件 + 账号埋点 ——
Analytics.onEvent / signIn / signOut,数字参数自动字符串化。 - 官方 Jest mock —— 随包导出
./mock,测试里整包替换,无需手写 stub。
何时使用
| 适用 | 不适用 |
|---|---|
| 分享到微信会话或钉钉(文本 / 图片 / 链接) | 分享到朋友圈 / QQ / 微博 —— 首版不支持 |
| 需要一套现成的中文分享面板 UI | 完全自定义的分享 UI(可直拉 shareXxx 自绘) |
| 友盟自定义事件 / 账号登录登出埋点 | 非友盟的统计后端 |
| PIPL 两段式合规采集启停 | —— |
平台支持
| 平台 | 支持 |
|---|---|
| iOS | ✅ |
| Android | ✅ |
| Web / 模拟器 | ❌(分享需真机) |
仅支持新架构
本库是 TurboModule 桥,仅支持 React Native 0.85+ 新架构、React 19。旧架构(Bridge)不在目标范围。
分享必须真机验证
分享会调起原生微信 / 钉钉,模拟器没有真 App 也无法完成回调跳转(iOS 还有 EXCLUDED_ARCHS=arm64 限制)。分享改动一律真机验证 —— 这是预期行为,不是 bug。
下一步
- 安装 —— 装齐 peerDeps、跑 pod install、原生配置指针
- 快速上手 —— 5 分钟跑通初始化 + 第一次分享
- 指南 → 分享 —— 面板 / 直拉、内容类型、取消失败处理
- 指南 → 隐私合规(PIPL) —— 两段式初始化时序
- API 参考 → Common —— 完整 API 文档