Keel — 5 个国内一等原生模块

国内 RN 开发者最常踩的坑：微信 / 支付宝 / 高德 / 极光 / 友盟 在 Expo 上要么没有要么 community 维护质量参差。Keel 把这 5 个当官方维护的一等模块——@keel-ai/<name> 一行 npm 安装即可，标准 autolink，不靠 community 拼凑。

本文档锁定 spec：npm 包名、JS 表面、native 实现策略、依赖、限制。

通用规范

  • 包名：@keel-ai/<module> (官方) 或 keel-module-<name> (社区)，标准 npm + autolink
  • JS 表面：default export + 平铺方法；尽量保持 Promise-based + 跟 native SDK 1:1 映射
  • native 集成：iOS 用 CocoaPods 引入官方 SDK；Android 用 Maven 引入官方 SDK
  • 错误处理：所有 Promise reject 抛 KeelError（含 code: string + message），跟 RN 标准对齐
  • 类型：@keel-ai/<module> 包自带 .d.ts，编辑器有完整自动补全
  • 示例代码：每模块 README 里跑一个最小 demo

1. @keel-ai/wechat —— 微信支付 + 登录 + 分享

能力

功能方法说明
支付pay(orderInfo)拉起微信 app 完成支付，返回 { status, transactionId }
登录signIn()OAuth code → 让你后端换 access_token
分享shareText / shareImage / shareLink / shareMiniProgram分享到聊天 / 朋友圈 / 收藏
跳转小程序launchMiniProgram(appId, path)从 RN app 拉起微信小程序

Native 依赖

  • iOS：pod 'WechatOpenSDK_XCFramework' + URL scheme 配置
  • Android：implementation 'com.tencent.mm.opensdk:wechat-sdk-android'

商户号要求

  • 必须有微信开放平台账号 + 移动应用 appId
  • 支付额外要商户号（微信支付 mch_id）+ API key
  • Keel 不代管商户凭证；用户自己在初始化时传入 appId + universalLink（iOS）

JS API（草稿）

import { wechat } from '@keel-ai/wechat';

await wechat.init({ appId: 'wx...', universalLink: 'https://...' });

// 支付
const result = await wechat.pay({
  partnerId: '商户号',
  prepayId: '后端预下单返回的 prepay_id',
  nonceStr: '...',
  timestamp: ...,
  package: 'Sign=WXPay',
  sign: '...',
});

// 登录
const { code } = await wechat.signIn({ scope: 'snsapi_userinfo' });
// 用 code 调你自己的后端换 token

限制

  • 微信 SDK 必须在 main thread 调用——@keel-ai/wechat 内部已包好，调用者无感
  • 安卓上需要应用签名指纹与开放平台填写一致——Keel CLI keel doctor 会校验

2. @keel-ai/alipay —— 支付宝支付 + 实名认证 + 小程序跳转

能力

功能方法说明
支付pay(orderString)拉起支付宝 app 完成支付
实名认证realName(certifyId)蚂蚁金融云人脸认证
跳转小程序launchMiniProgram(appId)拉起支付宝小程序
授权登录signIn(authInfo)拿 auth_code → 后端换 user_id

Native 依赖

  • iOS：pod 'AlipaySDK-iOS'
  • Android：implementation 'com.alipay.sdk:alipaysdk-android'

商户号要求

  • 支付宝开放平台 + 应用 appId
  • 支付要 RSA2 密钥对（公钥上传支付宝、私钥后端持有）
  • 同微信，Keel 不代管凭证

JS API（草稿）

import { alipay } from '@keel-ai/alipay';

const orderString = '<后端拼好的 orderString>';
const result = await alipay.pay(orderString);
// result: { resultStatus: '9000' | '6001' | ..., result: '...' }

3. @keel-ai/amap —— 高德地图 + 定位 + 路径 + Geo

能力

功能方法 / 组件说明
地图组件<AMapView />RN 组件，渲染原生地图
定位getCurrentLocation() / watchLocation(cb)GPS + 网络混合定位
地理编码geocode(address) / reverseGeocode(lat, lng)地址 ↔ 坐标
路径规划routePlan({ origin, dest, mode })步行 / 骑行 / 驾车 / 公交
POI 搜索searchPOI(keyword, region)搜餐厅 / 加油站等
距离测量distance(p1, p2)直线距离

Native 依赖

  • iOS：pod 'AMap3DMap' + pod 'AMapLocation' + pod 'AMapSearch'
  • Android：implementation 'com.amap.api:3dmap' + 'location' + 'search'

应用 key

  • 高德开放平台申请 web service key + iOS / Android 端 key（每端独立）
  • init({ iosKey, androidKey, webServiceKey })——Keel CLI 在 keel.json 里读

JS API（草稿）

import { amap, AMapView } from '@keel-ai/amap';

await amap.init({ iosKey, androidKey, webServiceKey });

// 组件用法
<AMapView
  style={{ flex: 1 }}
  center={{ lat: 39.91, lng: 116.39 }}
  zoom={14}
  markers={[{ position: ..., title: ... }]}
/>;

// 命令式 API
const loc = await amap.getCurrentLocation({ accuracy: 'high' });
const route = await amap.routePlan({ origin: loc, dest: ..., mode: 'driving' });

替代品

国内还有百度地图 / 腾讯地图，按市场份额（地图类百度 + 高德占 90%）选一家做一等公民够用。需要百度的用户走 community module（不是 Keel 一等）。

4. @keel-ai/push —— 推送（极光 + 个推双 backend）

抽象层 + 两个 backend

@keel-ai/push 是一个抽象接口，下挂两个 native backend：

@keel-ai/push                       ← 抽象接口（小，~300 LoC）
   │
   ├─→ @keel-ai/push-jpush          ← 极光 backend（规划中）
   └─→ @keel-ai/push-getui          ← 个推 backend（规划中）

用户在 init 时选一个，不同时启动两家——避免厂商通道重复弹通知。

import { push } from '@keel-ai/push';

await push.init({ provider: 'jpush', appKey: '...' });   // or 'getui'
const id = await push.register();
await push.setAlias('user_123');

为什么不只接极光

  • 极光：开箱即用，免费版够中小开发者；自动适配华为 / 小米 / OPPO / vivo / FCM 厂商通道；默认 backend
  • 个推：性能更稳、企业版 SLA 更靠谱、长链路心跳更省电；给企业用户选择
  • 厂商直连（华为 / 小米 / OPPO / vivo 各自）：工作量 5×，只有头部 app 愿意做；不在当前范围

能力

功能方法说明
注册register()拿 registrationId（推送目标）
设置 alias / tagsetAlias(alias) / addTags([...])服务端按 alias / tag 推
监听通知onNotificationOpened(cb) / onMessageReceived(cb)App 内 / App 关闭场景的不同回调
角标setBadge(num)iOS 角标
清空通知clearAllNotifications()清通知中心

Native 依赖

  • iOS：pod 'JPush'
  • Android：implementation 'cn.jiguang.sdk:jpush'
  • 厂商通道（极光自动管理）：华为 / 小米 / OPPO / vivo / FCM 各家 SDK

应用 key

极光 Portal 申请 AppKey + Master Secret（后端用）。Keel CLI 在 keel.json 配 appKey。

JS API（草稿）

import { jpush } from '@keel-ai/jpush';

await jpush.init({ appKey: '...', isProduction: true });
const id = await jpush.register();          // 后端记下 registrationId
await jpush.setAlias('user_123');

jpush.onNotificationOpened((noti) => {
  // 用户点了通知，处理跳转
});

限制

  • iOS APNs 证书 / p8 key 要上传到极光 Portal（一次性，Keel 提供 doctor 校验）
  • Android 推送权限需 OS 13+ 显式申请；Keel SDK 会自动提示

5. @keel-ai/umeng —— 友盟统计 + 备份推送

能力

功能方法说明
统计事件track(event, props)自定义事件 + 维度
页面统计pageEnter(name) / pageLeave(name)RN screen 切换
用户标识signIn(userId) / signOut()关联用户
CrashreportCrash(error)JS Error → 友盟 crash 报告
备份推送pushReceiver(handler)用户没装极光 / 个推时备份通道

Native 依赖

  • iOS：pod 'UMCommon' + 'UMAnalytics' + 'UMCrash'（推送 'UMPush'）
  • Android：implementation 'com.umeng.umsdk:common' + 各模块

应用 key

友盟 console 申请 AppKey + Channel ID（区分应用市场来源）。Keel CLI 配置。

JS API（草稿）

import { umeng } from '@keel-ai/umeng';

await umeng.init({ appKey: '...', channel: 'Huawei' });
umeng.track('button_clicked', { button_id: 'pay' });

为什么不用 Sentry / Firebase Analytics

  • Sentry 在国内访问不稳；自建上报到 Mortar 也行，但设备粒度统计要自己写
  • Firebase Analytics 在国内 Google Play 不分发，国产 Android 设备触达率极低
  • 友盟 CN 自带，且大多数国内运营 / 投放平台原生支持友盟数据回传

不在一等模块里的国内常见库

库状态推荐替代
腾讯地图社区用 @keel-ai/amap（高德）
百度地图社区同上
个推社区用 @keel-ai/push（极光 backend）
Bugly Crash社区用 @keel-ai/umeng
阿里 Sophix 热修复项目自集用 KAS Update
美团 ACE 容器Forbidden跟 Keel 范畴重叠，不推荐

需要这些社区模块的用户走 npm 自由引入；Keel 不挡，但也不官方支持。

规划中的实装顺序（按市场需求 + 技术依赖）

  1. @keel-ai/push 抽象层 + jpush backend —— 最常用 + 最容易（极光 SDK 成熟）；抽象接口设计要预留好（不锁死单 backend）
  2. 微信支付 —— 商业模型必备
  3. 支付宝 —— 同上
  4. 高德地图 —— LBS 类应用刚需
  5. 友盟 —— 数据回传必需
  6. @keel-ai/push-getui 第二 backend —— 给企业用户多一选择；推迟到 jpush 上线后看真实反馈再决定

抽象层 + 单 backend ~3 周；加第二 backend ~3 周（含 native 集成 + 服务端 dispatcher）。每个其他模块预计 2-3 周开发 + 1 周内测；总计 ~3-4 个月覆盖。

跟 Mortar 的协同

Keel 的 5 个模块只管端侧 native 集成。服务端验签 / 回调处理 / 数据落库由 Mortar 负责：

  • @keel-ai/wechat 的支付返回 prepayId，Mortar feature/payment 处理签名 + 状态机（规划中待加）
  • @keel-ai/jpush 的 push 触发，由 Mortar 后端调极光 server API（用户后端代码不用自己写）
  • @keel-ai/umeng 的 crash 报告可选转发到 Mortar feature/usage 留备份

这条协同会让 Keel 用户也变成 Mortar 用户——bundled 价值。

在 GitHub 上编辑 →