Skip to content

Latest commit

 

History

History
174 lines (119 loc) · 8.29 KB

README.md

File metadata and controls

174 lines (119 loc) · 8.29 KB
Raw

npm ci

react-native-hcaptcha

hCaptcha wrapper for React Native (Android and iOS)

Installation

  1. Install package:
  • Using NPM npm install @hcaptcha/react-native-hcaptcha
  • Using Yarn yarn add @hcaptcha/react-native-hcaptcha
  1. Import package: import ConfirmHcaptcha from '@hcaptcha/react-native-hcaptcha';

Full examples for expo and react-native, as well as debugging guides, are in MAINTAINER.md

Demo

See live demo in Snack.

Usage

See Example.App.js example in repo for a fully worked example implementation.

For users familiar with the hCaptcha JS API, calling show() in this wrapper triggers an hcaptcha.execute() call.

This means that if you are an Enterprise user with a 99.9% passive or purely passive sitekey configured, no additional work is required to get the expected behavior: either a visual challenge will be shown or a token will be returned immediately via onMessage, in accordance with your configuration.

Also, please note the following special message strings that can be returned via onMessage:

name purpose
expired passcode response expired and the user must re-verify, or did not answer before session expired
error there was an error displaying the challenge
cancel the user closed the challenge
open the visual challenge was opened

Any other string returned by onMessage will be a passcode.

Handling the post-issuance expiration lifecycle

This extension is a lightweight wrapper, and does not currently attempt to manage post-verification state in the same way as the web JS API, e.g. with an on-expire callback.

In particular, if you do not plan to immediately consume the passcode returned by submitting it to your backend, you should start a timer to let your application state know that a new passcode is required when it expires.

By default, this value is 120 seconds. So, an expired error will be emitted to onMessage if you haven't called event.markUsed().

Once you've utilized hCaptcha's token, call markUsed on the event object in onMessage:

  onMessage = event => {
    if (event && event.nativeEvent.data) {
      if (['cancel'].includes(event.nativeEvent.data)) {
        this.captchaForm.hide();
      } else if (['error'].includes(event.nativeEvent.data)) {
        this.captchaForm.hide();
        // handle error
      } else {
        this.captchaForm.hide();
        const token = event.nativeEvent.data;
        // utlize token and call markUsed once you done with it
        event.markUsed();
      }
    }
  };
  ...
  <ConfirmHcaptcha
    ref={_ref => (this.captchaForm = _ref)}
    siteKey={siteKey}
    languageCode="en"
    onMessage={this.onMessage}
  />

Handling errors and retry

If your app encounters an error event, you can reset the hCaptcha SDK flow by calling `event.reset()`` to perform another attempt at verification.

Dependencies

  1. react-native-modal

  2. react-native-webview

Building on iOS

Required frameworks/libraries

Your app must have the following frameworks/libraries linked:

  • libswiftWebKit.tbd
  • JavaScriptCore.framework

Flipper version

You must have a recent version of flipper to build this app. If you have upgraded React Native recently, your Flipper version may be out of date. This will cause compilation errors.

Your Podfile should be updated to something like:

  # 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

If you encounter build-time errors related to Flipper.

Localization

Make sure the value you pass to languageCode is the one the user has set in your app if you allow them to override the system defaults.

Otherwise, you should pass in the preferred device locale, e.g. fetched from getLocales() if using react-native-localize.

Notes

  • The UI defaults to the "invisible" mode of the JS SDK, i.e. no checkbox is displayed.
  • You can import Hcaptcha from '@hcaptcha/react-native-hcaptcha/Hcaptcha'; to customize the UI yourself.
  • hCaptcha loading is restricted to a 15-second timeout; an error will be sent via onMessage if it fails to load due to network issues.

Properties

Name Type Description
siteKey (required) string The hCaptcha siteKey
size string The size of the checkbox, can be 'invisible', 'compact' or 'checkbox', Default: 'invisible'
onMessage Function (see here) The callback function that runs after receiving a response, error, or when user cancels.
languageCode string Default language for hCaptcha; overrides phone defaults. A complete list of supported languages and their codes can be found here
showLoading boolean Whether to show a loading indicator while the hCaptcha web content loads
closableLoading boolean Allow user to cancel hcaptcha during loading by touch loader overlay
loadingIndicatorColor string Color of the ActivityIndicator
backgroundColor string The background color code that will be applied to the main HTML element
theme string|object The theme can be 'light', 'dark', 'contrast' or a custom theme object (see Enterprise docs)
rqdata string Hcaptcha execution options (see Enterprise docs)
sentry boolean sentry error reporting (see Enterprise docs)
jsSrc string The url of api.js. Default: https://js.hcaptcha.com/1/api.js (Override only if using first-party hosting feature.)
endpoint string Point hCaptcha JS Ajax Requests to alternative API Endpoint. Default: https://api.hcaptcha.com (Override only if using first-party hosting feature.)
reportapi string Point hCaptcha Bug Reporting Request to alternative API Endpoint. Default: https://accounts.hcaptcha.com (Override only if using first-party hosting feature.)
assethost string Points loaded hCaptcha assets to a user defined asset location, used for proxies. Default: https://newassets.hcaptcha.com (Override only if using first-party hosting feature.)
imghost string Points loaded hCaptcha challenge images to a user defined image location, used for proxies. Default: https://imgs.hcaptcha.com (Override only if using first-party hosting feature.)
host string hCaptcha SDK host identifier. null value means that it will be generated by SDK
url (inline component only) string The url domain defined on your hCaptcha. You generally will not need to change this.
style (inline component only) ViewStyle (see here) The webview style
baseUrl (modal component only) string The url domain defined on your hCaptcha. You generally will not need to change this.
passiveSiteKey (modal component only) boolean Indicates whether the passive mode is enabled; when true, the modal won't be shown at all
hasBackdrop (modal component only) boolean Defines if the modal backdrop is shown (true by default). If hasBackdrop=false, backgroundColor will apply only after the hCaptcha visual challenge is presented.
orientation string This specifies the "orientation" of the challenge. It can be portrait, landscape. Default: portrait

Status

Fully functional, but additional releases will be made in the near term.

Changes within the same major release are expected to be additive, i.e. non-breaking.

License

MIT License. (C) 2021 hCaptcha.

Credits: Originally forked from xuho and filipepiresg's Google reCAPTCHA v2 work. (MIT license)