快速上手

5 分钟跑通:根挂 <ShareSheetHost /> → 启动时 preInit → 用户同意后 init → await Share.openSheet() 拉起面板。

当前验证边界

这套流程已在 JS、Android 和 iOS 落地。iOS 已通过 simulator build/XCTest/native contract；Android CI 已通过 native contract、JVM tests、启用 minify 的 release 构建与 merged manifest 核对。真实第三方 App 回跳与 Android 真机 R8 运行仍需真机验证。

分享必须真机运行

分享会调起原生微信 / 钉钉,模拟器没有真 App,无法完成回调跳转(属预期行为)。先完成安装(peerDeps + pod install + 原生回调配置)再运行本例。

---

① 在 App 根挂 <ShareSheetHost />

<ShareSheetHost /> 是命令式分享面板的宿主,必须在 App 根挂一次,且位于 design 的 ThemeProvider 内。示例保留 App 外层 GestureHandlerRootView 供其余 RNGH UI 使用:

App.tsx（或根组件）

import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { ThemeProvider } from '@unif/react-native-design';
import { ShareSheetHost } from '@unif/react-native-umeng';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <ThemeProvider>
        <YourNavigationStack />
        <ShareSheetHost />{/* 根上挂一次,位置不影响显示(打开时全屏覆盖) */}
      </ThemeProvider>
    </GestureHandlerRootView>
  );
}

不挂 Host,Share.openSheet() 会立即 reject(No <ShareSheetHost /> mounted)。Host 自己会在 RN Modal 内容里创建另一层 GestureHandlerRootView;Modal 是独立 native root,App 外层 root 不能替代内部这一层。消费者无需手工再包 Modal 内容。

② App 启动后立刻 preInit(此时不上报)

Common.preInit(config) 只在 JS 侧校验、标准化并保存 config 快照,不调用 native、不注册微信 / 钉钉平台、不上报任何数据,因此可以(也应该)在用户同意《隐私协议》之前调。所有配置都在这里给:

import { Common } from '@unif/react-native-umeng';

await Common.preInit({
  appkey: 'YOUR_UMENG_APPKEY',          // 必填
  channel: 'App Store',                  // 可选,默认 iOS='App Store' / Android='default'
  wechatAppId: 'YOUR_WECHAT_APP_ID',     // 使用平台分配的原值
  wechatAppSecret: 'YOUR_WECHAT_APP_SECRET',
  wechatUniversalLink: 'https://your.host/', // 微信 1.8.6+(iOS)要求
  dingtalkAppId: 'YOUR_DINGTALK_APP_ID', // 使用平台分配的原值
});

iOS 启用微信时 wechatAppId、wechatAppSecret、绝对 HTTPS wechatUniversalLink 三项必须同时提供；Android 启用微信时前两项必须成组，Universal Link 可省略。任一可选字段一旦出现也必须是非空字符串。

③ 用户同意后,init 开始采集(无参)

// 仅在用户点「同意《隐私协议》」之后调用
await Common.init();   // ⚠️ 无参 —— config 已给 preInit

Common.init() 不接收 config(配置已给 preInit)。没先 preInit 直接 init 会 reject E_NOT_INITIALIZED。用户同意后调用时,Android 才依次执行 vendor preInit、平台注册、FileProvider 与正式 init；iOS 才执行 Universal Link 配置、微信 / 钉钉注册与 UMConfigure.initWithAppkey。两段式合规细节见隐私合规(PIPL)。

④ 拉起分享面板

import { Share, UmengError } from '@unif/react-native-umeng';

async function onShareTap() {
  try {
    const r = await Share.openSheet({
      type: 'link',
      title: '问问看',
      url: 'https://example.com',
      description: '一句话描述',
    });
    // 走到这里说明分享成功:r.code 恒为 'success'
    console.log(r.platform); // 'wechat_session' | 'dingtalk'
  } catch (e) {
    if (e instanceof UmengError && e.code === 'E_USER_CANCEL') {
      // 用户取消,通常静默
    }
    // 其它如 E_SHARE_FAILED / E_PLATFORM_NOT_INSTALLED:兜底提示
  }
}

取消 / 失败走 reject,不走 resolve

Share.openSheet() 只有成功才 resolve(r.code 恒为 'success');用户取消、分享失败都会抛 UmengError。务必 try/catch,不要写 if (r.code === 'cancel')(永远到不了)。详见分享指南。

---

统计埋点(可选)

初始化完成后即可埋点。Analytics.* 都是同步 void,不要 await:

import { Analytics } from '@unif/react-native-umeng';

Analytics.onEvent('share_click', { source: 'detail', count: 1 }); // 数字自动转字符串
Analytics.signIn('user-123', 'WX');  // provider 可选
Analytics.signOut();

---

下一步

• 指南 → 分享 —— 面板 vs 直拉、内容类型、取消失败处理
• 指南 → 统计埋点 —— onEvent / signIn / signOut 详解
• 指南 → 隐私合规(PIPL) —— 两段式初始化时序
• API 参考 → Common —— preInit / init / isInited 完整参数