@hcaptcha/react-native-hcaptcha

中文文档
4.1.0发布于 2026/07/21MITTypeScriptCommonJS构建来源已验证近 30 天下载 30万

h Captcha 本地反应库(Android和iOS)

中文使用文档
文档目录24 节
  1. 安装
  2. 演示
  3. 使用量
  4. 基本模式使用
  5. 核查有效载荷 verifyParams
  6. 用户行程( 企业)
  7. 内置组件使用
  8. 处理发放后过期寿命周期
  9. 处理错误并重试
  10. 依赖关系
  11. 以iOS为基础
  12. 所需框架/图书馆
  13. 翻转版本
  14. 本地化
  15. 页:1
  16. 捕捉洞
  17. 外交部电话支助
  18. 属性
  19. 旅行API
  20. initJourneyTracking(options?)
  21. registerJourneyNavigationContainer(ref)
  22. ConfirmHcaptcha.stopEvents()
  23. 状态
  24. 许可证

npm ci

反应-内生-头痛

h Captcha 为反应原生(Android和iOS)所包装

安装

  1. 安装软件包 :
  • 利用国家预防机制 npm install @hcaptcha/react-native-hcaptcha
  • 使用 Yarn yarn add @hcaptcha/react-native-hcaptcha
  1. 导入包 : import ConfirmHcaptcha from '@hcaptcha/react-native-hcaptcha';

博览会和反应本地化的完整示例以及调试指南都在其中 保安员,md

演示

见现场演示 点心。 。 。 .

使用量

见 实例。 应用 (c) 以完全行之有效的范例执行的回购为例.

对于熟悉hCaptcha JS API的用户,呼叫 show() 在此包装中触发 hcaptcha.execute() 电话.

这意味着,如果您是企业用户,配置了99.9%的被动或纯被动的站点密钥,则不需要额外工作来获得预期的行为:要么显示视觉挑战,要么立即通过网络返回一个符号 onMessage,按照您的配置.

此外,请注意以下可通过下列方式返回的特别信件串: onMessage 页:1 错误大小写

事件由 onMessage 与 success === true 将是一个密码.

实际上,你应该总是提供 onMessage。没有它,您的应用程序将不会收到符号、错误或取消事件.

基本模式使用

import React, { useRef } from 'react';
import ConfirmHcaptcha from '@hcaptcha/react-native-hcaptcha';

export default function Example() {
  const captchaRef = useRef(null);

  const onMessage = (event) => {
    if (!event?.nativeEvent?.data) {
      return;
    }

    if (event.success) {
      const token = event.nativeEvent.data;
      event.markUsed?.();
      captchaRef.current?.hide();
      return;
    }

    if (event.nativeEvent.data === 'challenge-closed') {
      captchaRef.current?.hide();
    }
  };

  return (
    <ConfirmHcaptcha
      ref={captchaRef}
      siteKey="your-site-key"
      baseUrl="https://hcaptcha.com"
      onMessage={onMessage}
    />
  );
}

核查有效载荷 verifyParams

使用 verifyParams 请求数据 hcaptcha.setData(...) 在每次核查之前.

<ConfirmHcaptcha
  ref={captchaRef}
  siteKey="your-site-key"
  baseUrl="https://hcaptcha.com"
  onMessage={onMessage}
  verifyParams={{
    rqdata: enterpriseRqdata,
    phonePrefix: '44',
    phoneNumber: '+44123456789',
  }}
/>

高级遗产 rqdata, (中文(简体) ), phonePrefix,以及 phoneNumber 道具还能用,不过 verifyParams 优先,对于新的守则应优先.

用户行程( 企业)

旅程捕捉在卡普查水平上进行 userJourney={true}。 。 。 .

默认情况下, Captcha 实例与 userJourney={true} 将:

  • 将当前共享的旅行缓冲器附在其核查有效载荷上,作为 userjourney
  • 启动首次使用的行程运行时间
  • 启用自动全应用的触摸抓取, 至少一个 userJourney captcha 实例已挂载

使用 initJourneyTracking() 当您想要:

  • 在卡布查组件挂起前开始跟踪行程
  • 登记用于自动屏幕跟踪的 React 导航容器
  • 启用运行时间调试/调试钩
  • 禁用自动触摸抓取方式 touchCapture: false ,同时保留用户余行
import ConfirmHcaptcha, {
  initJourneyTracking,
  registerJourneyNavigationContainer,
} from '@hcaptcha/react-native-hcaptcha';

initJourneyTracking({
  touchCapture: true,
});

// If you use React Navigation, register the container once the ref exists.
registerJourneyNavigationContainer(navigationRef);

<ConfirmHcaptcha
  ref={captchaRef}
  siteKey="your-site-key"
  baseUrl="https://hcaptcha.com"
  onMessage={onMessage}
  userJourney={true}
/>

如果您已经持有一个导航容器 查看器的时间, 您可以直接通过 :

initJourneyTracking({
  navigationContainerRef: navigationRef,
});

如果您想要使用包含行程的内置组件 :

import { Hcaptcha, initJourneyTracking } from '@hcaptcha/react-native-hcaptcha';

initJourneyTracking();

<Hcaptcha
  siteKey="your-site-key"
  url="https://hcaptcha.com"
  onMessage={onMessage}
  userJourney={true}
/>

如果你想的话 userJourney 验证有效载荷和导航跟踪,但不希望自动的全应用触控捕获:

initJourneyTracking({
  navigationContainerRef: navigationRef,
  touchCapture: false,
});

自动抓取当前记录 :

  • 反应导航屏幕转换
  • 基本水龙头
  • 基本拖动手势
  • 从轴向主触控运动推断出类似滚动的手势

自动旅行故意抓取 没有 记录 :

  • 文本输入内容
  • 搜索查询
  • 文本长度或输入字符
  • 作为控制标识符的可见按钮文本

内置组件使用

如果您想要自己管理周围的用户界面, 请使用内置组件 :

import { Hcaptcha } from '@hcaptcha/react-native-hcaptcha';

<Hcaptcha
  siteKey="your-site-key"
  url="https://hcaptcha.com"
  onMessage={onMessage}
/>

处理发放后过期寿命周期

这个扩展是一个轻量级的包装器,目前并不试图以与网络JS API相同的方式管理验证后状态,例如使用到期回调.

特别是,如果你这样做 没有 计划通过提交后端立即消耗返回的密码,您应该启动一个定时器,让您的应用程序状态知道,当新的密码到期时需要它.

默认情况下,该值为120秒. 所以,一个 expired 错误将被释放到 onMessage 如果你没有打电话 event.markUsed()。 。 。 .

一旦你用过卡普查的纪念品,就打电话 markUsed 对象在 onMessage数字 :

  const onMessage = event => {
    if (event && event.nativeEvent.data) {
      if (event.nativeEvent.data === 'open') {
        // hCaptcha shown
      } else if (event.success) {
        captchaForm.current.hide();
        const token = event.nativeEvent.data;
        // utilize token and call markUsed once you are done with it
        event.markUsed();
      } else if (event.nativeEvent.data === 'challenge-closed') {
        captchaForm.current.hide();
      } else {
        // handle rest errors
      }
    }
  };

  const captchaForm = useRef(null);

  return (
    <ConfirmHcaptcha
      ref={captchaForm}
      siteKey={siteKey}
      languageCode="en"
      onMessage={onMessage}
    />
  );

处理错误并重试

如果你的应用遇到一个 error 事件,您可以通过调用重设 hCaptcha SDK 流量 event.reset() 进行另一次核查.

event.reset() 重建当前道具上的验证有效载荷,以及当前在重试前的缓冲行程.

SDK 自动重试加载 api.js 在短暂的失败之后。 如果一切尝试都失败了, script-error 发送通过 onMessage。 。 。 .

15秒钟 loading timeout 电文不停止初始化,不应作为终端装载故障处理.

依赖关系

  1. 反应-本地-网络视图

以iOS为基础

所需框架/图书馆

您的应用程序必须链接以下框架/ 库 :

  • libswift 微博Kit.tbd
  • JavaScript Core. 框架

翻转版本

您必须拥有最新版本的 Flapper 来构建此应用程序 。 如果您最近升级了 React Natural , 您的 Flipper 版本可能已经过时 。 这将引起编译错误 .

您的 Podfile 应该更新到类似的东西:

  # Enables Flipper.
  #
  # Note that if you have use_frameworks! enabled, Flipper will not work and
  # you should disable these next few lines.
  use_flipper!({ 'Flipper-Folly' => '2.5.3', 'Flipper' => '0.87.0', 'Flipper-RSocket' => '1.3.1' })
  post_install do |installer|
    flipper_post_install(installer)
  end

如果您遇到与 Flipper 相关的构建时错误 .

本地化

确定您传递的值 languageCode 是用户在您的应用程序中设置的, 如果您允许他们覆盖系统默认值 .

否则,您应该通过首选设备 locale,例如从 getLocales() 如果使用的话 反应-本地化-本地化。 。 。 .

页:1

  • UI默认为JS SDK的"隐形"模式,即不显示复选框.
  • 如果您需要测试显示挑战模式, 请在 hCaptcha 仪表板中将您的站点键设置为“ 永远挑战” 模式 .
  • 你们可以 import { Hcaptcha } from '@hcaptcha/react-native-hcaptcha'; 自己定制UI.

捕捉洞

  • 打电话 initJourneyTracking() 早点做一次 初始化前发生的事件没有被捕获.
  • 默认启用自动全应用程序触摸抓取, 而至少有一个 captcha 实例带有 userJourney={true} 已挂载.
  • 自动触摸抓取使用 React Industrial 的公开 AppRegistry.setWrapperComponentProvider(...) API (英语).
  • 这个SDK在初始化后通过截取未来呼叫而由已注册的包装提供者组成 setWrapperComponentProvider(...)。 。 。 .
  • React Introduct不会暴露在SDK初始化之前已经注册的包装提供者的获取器. 如果另一个库先安装了包装提供者, 请打电话 initJourneyTracking() 更早或使用时间 touchCapture: false 避免冲突.
  • 如果你开始 touchCapture: false,此 SDK 故意不补丁 AppRegistry。如果另一个库在禁用窗口中注册了包装提供者,而您随后可以重新启用触摸抓取,则hCaptcha无法自动恢复先前的提供者。 如果您可以稍后切换到抓取, 请先初始化 h Captcha 或者保留 touchCapture 开始启用.
  • 导航抓取仅在您注册反应导航容器时自动进行 initJourneyTracking({ navigationContainerRef }) 或者说 registerJourneyNavigationContainer(ref)。 。 。 .
  • userJourney={true} 控制当前缓冲行程是否附在卡普查的核查请求上。 也可以默认自动触摸抓取,除非您使用 initJourneyTracking({ touchCapture: false })。 。 。 .
  • 旅行缓冲器是应用全球的,并在同一过程中通过Captcha实例共享。 这是针对单一应用程序、单一用户的故意行为.
  • ConfirmHcaptcha.stopEvents() 清除共享缓冲出行并解开 ConfirmHcaptcha 实例,从旅行附件到明确重新配置为止,例如: userJourney 关了 继续.
  • 全球旅行捕捉可以在 stopEvents() 如果行程跟踪被初始化,所以后期的应用事件可能仍然会为其他消费者在共享缓冲中积累.
  • 成功的核查清除了缓冲之行. 错误和取消流量没有 .
  • 自动控制标识符是最佳的,更喜欢非内容元数据,如 nativeID, (中文(简体) ), testID,以及 accessibilityLabel如果不存在,事件可能会回到本地视图标记或 "unknown"。 。 。 .

外交部电话支助

SDK支持MFA(多功能认证)流的手机前缀和电话号码参数. 您可以通过这些参数作为道具:

// Using phone prefix (country code without '+')
<ConfirmHcaptcha
  siteKey="your-site-key"
  phonePrefix="44"
  onMessage={onMessage}
/>

// Using phone number (full E.164 format)
<ConfirmHcaptcha
  siteKey="your-site-key"
  phoneNumber="+44123456789"
  onMessage={onMessage}
/>

对于新代码,倾向于:

<ConfirmHcaptcha
  siteKey="your-site-key"
  baseUrl="https://hcaptcha.com"
  verifyParams={{
    phonePrefix: '44',
    phoneNumber: '+44123456789',
  }}
  onMessage={onMessage}
/>

属性

名称类型说明
站点键 (必须)字符串H Captcha 网站键
大小字符串部件的大小, 可以是“ 隐形” 、 “ 约束” 或“ 正常” . checkbox 并被接受为用于 normal。默认:“隐形”
新闻函数(见 这里(中文(简体) )要求。 在收到回复、错误或用户取消时运行.
语言代码字符串HCaptcha 的默认语言; 覆盖电话默认 。 可以找到一个完整的支持语言及其代码列表 这里
显示记录布尔在 hCaptcha 网络内容加载时是否显示加载指标
可分块连接布尔允许用户在使用触摸加载器上载时取消 hcaptcha
装入指标颜色字符串活动指示器的颜色
背景颜色字符串将应用于主要 HTML 元素的背景颜色代码
主题字符串\\\ 对象主题可以是"光","暗","相接"或自定义主题对象(参见 Entertainment Docs)
rqdata 数据字符串折旧: 使用 rqdata 内 HCaptchaVerifyParams 换句话说 将在以后的释放中移除。 见企业文件.
校验对象验证有效载荷覆盖 hcaptcha.setData(...) 就在核查前 支助 rqdata, (中文(简体) ), phonePrefix,以及 phoneNumber。 。 。 .
用户行程布尔何时 true,将当前共享行程缓冲器作为核查有效载荷 userjourney。它也可以在默认情况下自动抓取 userJourney 已安装 Captcha 实例 。 使用 initJourneyTracking({ touchCapture: false }) 以保持用户的行走功能,而无需自动触摸捕获.
哨兵布尔启用 hCaptcha 错误报告, 包括 API 装载失败 。 设定为 false 以禁用(见企业编号).
jsSrc 函数字符串Api.js的url (英语). 默认 : https://js.hcaptcha.com/1/api.js (中文(简体) ) (只有在使用第一当事方托管功能的情况下才进行管理。 )
结束点字符串JS Ajax要求替代API终点。 默认 : https://api.hcaptcha.com (中文(简体) ) (只有在使用第一当事方托管功能的情况下才进行管理。 )
报告api字符串点 hCaptcha Bug 报告请求到替代 API 端点. 默认 : https://accounts.hcaptcha.com 互联网档案馆的存檔,存档日期2013-12-02 (只有在使用第一当事方托管功能的情况下才进行管理。 )
资产主机字符串点装入 hCaptcha 资产到用户定义的资产位置, 用于代理 。 默认 : https://newassets.hcaptcha.com (中文(简体) ) (只有在使用第一当事方托管功能的情况下才进行管理。 )
幽灵字符串点装入 hCaptcha 挑战图像到用户定义的图像位置, 用于代理 。 默认 : https://imgs.hcaptcha.com (中文(简体) ) (只有在使用第一当事方托管功能的情况下才进行管理。 )
东道主字符串h Captcha SDK 主机标识符. 无效值表示由 SDK 生成
url 密码 (仅内含组件)字符串在您的 hCaptcha 上定义的 url 域 。 你一般不需要改变这一点.
样式 (仅内含组件)视图样式( 见 这里(中文(简体) )网页视图样式
基数Url (仅包括模式部分)字符串在您的 hCaptcha 上定义的 url 域 。 你一般不需要改变这一点.
被动键 (仅包括模式部分)布尔指示被动模式是否启用; 当为真时, 模式将完全不显示
有背弃 (仅包括模式部分)布尔定义模式背景是否显示(默认正确)。 若为 hasBackdrop=false, (中文(简体) ), backgroundColor 将仅在 hCaptcha 视觉挑战出现后适用.
方向字符串这明确了挑战的"取向". 可能是这样 portrait, (中文(简体) ), landscape默认 : portrait
电话前缀字符串可选电话国家呼叫代码(不含"+"),如"44". 用于外交部流动.
电话号码字符串E.164格式的可选完整电话号码("+44123"),用于外交部.

旅行API

initJourneyTracking(options?)

为应用进程安装自动行程收藏一次 .

选项 :

  • navigationContainerRef: 可选反应导航容器 拒绝立即注册
  • touchCapture: 可选布尔, 默认为 true时 false,保持用户行程启用但禁用自动全应用程序触控抓取
  • debug: 可选布尔来记录已发射的行程事件到 console.debug
  • onStats: 测试或应用仪器中运行时诊断的可选回调

registerJourneyNavigationContainer(ref)

注册或替换用于自动屏幕跟踪的React Navigation容器.

ConfirmHcaptcha.stopEvents()

清除当前共享的行程缓冲并解析 ConfirmHcaptcha 从旅行附件到明确重新配置。 一个简单的重新启用的方法就是切换 userJourney 关了 继续.

状态

功能齐全,但近期内将进行额外的释放.

同一主要释放物内的变化预计将会是添加剂,即不破裂.

许可证

MIT许可证. (C) 2021 h Captcha.

校对:Soup (麻省理工学院许可证)

版本与发布记录

@hcaptcha/react-native-hcaptcha 共发布 24 个版本,首次发布于 2021/01/29;过去 12 个月发布了 5 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
4.1.0latest2026/07/213 个月前
4.0.02026/04/077 个月前
3.0.22026/03/277 个月前
3.0.12026/03/277 个月前
3.0.02026/03/267 个月前
2.1.02025/10/171.1 年前

关于 @hcaptcha/react-native-hcaptcha 的常见问题

@hcaptcha/react-native-hcaptcha 是什么?

h Captcha 本地反应库(Android和iOS)

如何安装 @hcaptcha/react-native-hcaptcha?

在项目目录运行 npm install @hcaptcha/react-native-hcaptcha,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(*)、react-native(*)、react-native-webview(>=9.0.1)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hcaptcha/react-native-hcaptcha 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hcaptcha/react-native-hcaptcha 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@hcaptcha/react-native-hcaptcha 可以商用吗?

@hcaptcha/react-native-hcaptcha 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hcaptcha/react-native-hcaptcha 的下载量有多少?

根据 npm 官方下载统计,@hcaptcha/react-native-hcaptcha 在 2026/10/18 – 2026/11/16 这 30 天内被下载 299,913 次,日均约 9,997 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hcaptcha/react-native-hcaptcha 还在维护吗?

最新版本 4.1.0 发布于 2026/07/21(3 个月前);至今共发布 24 个版本,其中过去 12 个月发布了 5 个;首次发布于 2021/01/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。