openapi-chainless

One-tap login plugin for React Native using deep linking between apps.

功能简介

openapi-chainless 是一个基于 App 间 deep link 唤起的 React Native 一键登录插件，适用于需要在多个 App 之间安全快捷传递登录凭证的场景。

• 支持一键唤起第三方授权 App 并回传 Code
• 支持自定义 Modal 提示未安装授权 App 时的用户引导
• 支持监听其他 App 通过 URL Scheme 拉起本 App 并获取参数
• 兼容 React Native 生态，API 简单易用

安装

npm install openapi-chainless
# 或
yarn add openapi-chainless
# 或
pnpm add openapi-chainless

平台配置

Android 配置

1. 配置 URL Scheme

在 android/app/src/main/AndroidManifest.xml 中添加 intent-filter：

<activity
   >
    <!-- 添加以下 intent-filter 用于处理 deep link -->
    <intent-filter android:autoVerify="true">
          <data android:scheme="your-app-scheme" android:host="*" android:pathPattern=".*"/>
    </intent-filter>
</activity>

iOS 配置

1. 配置 URL Scheme

直接在 ios/YourApp/Info.plist 中添加：

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <!-- 配置 -->
        <key>CFBundleURLSchemes</key>
        <array>
            <string>your-app-scheme</string>
        </array>
    </dict>
</array>

在 ios\您的项目\AppDelegate.mm 添加以下配置，确保支持接收回调参数

// URL Scheme
- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
  NSLog(@"[AppDelegate] openURL: %@", url.absoluteString);
  BOOL handledBySuper = [super application:application openURL:url options:options];
  BOOL handledByRN = [RCTLinkingManager application:application openURL:url options:options];
  return handledBySuper || handledByRN;
}

// Universal Links
- (BOOL)application:(UIApplication *)application
 continueUserActivity:(nonnull NSUserActivity *)userActivity
 restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
  NSLog(@"[AppDelegate] continueUserActivity: %@", userActivity.webpageURL.absoluteString);
  BOOL handledByRN = [RCTLinkingManager application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
  BOOL handledBySuper = [super application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
  return handledBySuper || handledByRN;
}

配置说明

• your-app-scheme: 替换为你的应用自定义 scheme，例如 myapp、com.yourcompany.yourapp
• yourdomain.com: 替换为你的域名（如果使用 Universal Links）

测试配置

配置完成后，可以通过以下方式测试：

1. Android: 在浏览器或命令行中输入 your-app-scheme://test
2. iOS: 在 Safari 中输入 your-app-scheme://test

如果配置正确，应该能够唤起你的应用。

使用方法

1. 主动唤起授权 App 并处理未安装弹窗

import React from 'react';
import { Button, View } from 'react-native';
import { useLaunchAuthApp } from 'openapi-chainless';

export default function Demo() {
  const { launch, modal } = useLaunchAuthApp({
    clientId: 'your-client-id',
    environment: 'testnet', // 显式指定测试环境 (可不传)默认为 'mainnet' 
    onDeepLink: (url, params) => {
      // 监听到被其他App拉起时的链接和参数
      console.log('被拉起的链接:', url);
      console.log('参数:', params);
    }
  });

  return (
    <View style={{ flex: 1 }}>
      <Button title="一键登录" onPress={launch} />
      {modal}
    </View>
  );
}

2. 监听被其他 App 拉起时的链接

只需在 useLaunchAuthApp 传入 onDeepLink 回调即可自动监听，无需额外配置。

自定义弹窗

你可以通过 CustomModal 参数自定义未安装授权 App 时的弹窗内容和样式。

1. 实现自定义弹窗组件

import React from 'react';
import { Modal, View, Text, TouchableOpacity, StyleSheet } from 'react-native';

const MyCustomModal = ({ visible, onCancel, onConfirm }) => (
  <Modal visible={visible} transparent animationType="fade" onRequestClose={onCancel}>
    <View style={styles.overlay}>
      <View style={styles.container}>
        <Text style={styles.title}>自定义弹窗标题</Text>
        <Text style={styles.desc}>这里是自定义的弹窗内容，你可以放任何提示、图片或说明。</Text>
        <View style={styles.buttonRow}>
          <TouchableOpacity onPress={onCancel} style={styles.cancelBtn}>
            <Text style={styles.cancelText}>取消</Text>
          </TouchableOpacity>
          <TouchableOpacity onPress={onConfirm} style={styles.confirmBtn}>
            <Text style={styles.confirmText}>去安装/跳转</Text>
          </TouchableOpacity>
        </View>
      </View>
    </View>
  </Modal>
);

const styles = StyleSheet.create({
  overlay: { flex: 1, backgroundColor: 'rgba(0,0,0,0.2)', justifyContent: 'center', alignItems: 'center' },
  container: { width: 320, backgroundColor: '#fff', borderRadius: 16, padding: 24, alignItems: 'center' },
  title: { fontSize: 18, fontWeight: 'bold', marginBottom: 8, color: '#222' },
  desc: { fontSize: 15, color: '#222', marginBottom: 16, textAlign: 'center' },
  buttonRow: { flexDirection: 'row', width: '100%', justifyContent: 'space-between', marginTop: 8 },
  cancelBtn: { flex: 1, backgroundColor: '#f2f3f5', borderRadius: 8, marginRight: 8, paddingVertical: 12, alignItems: 'center' },
  confirmBtn: { flex: 1, backgroundColor: '#1890ff', borderRadius: 8, marginLeft: 8, paddingVertical: 12, alignItems: 'center' },
  cancelText: { color: '#666', fontSize: 16 },
  confirmText: { color: '#fff', fontSize: 16, fontWeight: 'bold' },
});

2. 传递自定义弹窗给 useLaunchAuthApp

import { useLaunchAuthApp } from 'openapi-chainless';
import MyCustomModal from './MyCustomModal';

const { launch, modal } = useLaunchAuthApp({
  clientId: 'your-client-id',
  CustomModal: MyCustomModal,
  onDeepLink: (url, params) => { /* ... */ }
});

API 说明

useLaunchAuthApp(options)

| 参数 | 类型 | 说明 | | ------------ | -------------------------------------------------- | ---------------------------- | | clientId | string | 唤起授权 App 时传递的 clientId| | onDeepLink | (url: string, params: Record<string, any>) => void | 监听被其他 App 拉起时的回调 |

返回值：

• launch: () => { success: boolean; message: string } 主动唤起授权 App
• modal: ReactNode 未安装授权 App 时的弹窗组件

onDeepLink 回调参数说明

• url: 被拉起时的完整链接。
• params: 解析后的参数对象，主要字段如下：
  • code: 授权结果码。同意授权时为非空字符串，拒绝时为空字符串。
  • phone: boolean，为 true 表示授权账号有手机号。
  • email: boolean，为 true 表示授权账号有邮箱。

示例：

• 用户同意授权且账号有手机号和邮箱：

  { code: 'xxxx', phone: true, email: true }

• 用户同意授权但账号无邮箱：

  { code: 'xxxx', phone: true, email: false }

• 用户拒绝授权：

  { code: '', phone: false, email: false }

常见问题

Q: 配置完成后无法唤起应用怎么办？

A: 请检查以下几点：

1. 确认 URL Scheme 配置正确，没有拼写错误
2. Android 中确认 android:autoVerify="true" 已添加
3. iOS 中确认 URL Types 配置正确
4. 重新编译并安装应用
5. 清除应用数据后重试

Q: 应用能唤起但收不到回调参数？

A: 请检查以下几点：

1. 确认 onDeepLink 回调已正确配置
2. 确认 useEffect 中的监听代码已添加
3. 检查授权 App 返回的 URL 格式是否正确
4. 在控制台查看是否有错误日志

Q: iOS 上 Universal Links 不工作？

A: 请检查以下几点：

1. 确认 apple-app-site-association 文件可正常访问
2. 确认文件格式为 JSON，Content-Type 为 application/json
3. 确认 Team ID 和 Bundle ID 配置正确
4. 在真机上测试（模拟器可能有限制）

注意事项

• 请确保你的 App 已正确配置 URL Scheme（deep link）能力。
• clientId 需与授权 App 约定一致。
• 若需自定义弹窗样式，可修改 AuthAppModal.tsx。
• 兼容 React Native 0.60+，如遇类型或编译问题请检查 tsconfig 配置。
• 重要: 在发布到应用商店前，请确保在真机上充分测试 deep link 功能。
• 安全提示: 建议在生产环境中验证 clientId 和授权来源的合法性。

License

MIT