{"id":19943487,"url":"https://github.com/iproov/react-native","last_synced_at":"2025-05-03T15:33:05.726Z","repository":{"id":127780828,"uuid":"476348777","full_name":"iProov/react-native","owner":"iProov","description":"iProov Biometrics React Native SDK","archived":false,"fork":false,"pushed_at":"2024-08-02T14:05:08.000Z","size":1332,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-11-07T05:21:33.719Z","etag":null,"topics":["iproov"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iProov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-03-31T14:44:09.000Z","updated_at":"2024-08-02T14:01:33.000Z","dependencies_parsed_at":"2023-11-13T16:51:38.959Z","dependency_job_id":null,"html_url":"https://github.com/iProov/react-native","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iProov%2Freact-native","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iProov%2Freact-native/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iProov%2Freact-native/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iProov%2Freact-native/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iProov","download_url":"https://codeload.github.com/iProov/react-native/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224365264,"owners_count":17299156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["iproov"],"created_at":"2024-11-13T00:16:44.676Z","updated_at":"2025-05-03T15:33:05.708Z","avatar_url":"https://github.com/iProov.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![iProov: Flexible authentication for identity assurance](https://github.com/iProov/react-native/raw/main/images/banner.jpg)\n# iProov Biometrics React Native SDK\n\n## Table of contents\n\n- [Introduction](#introduction)\n- [Repository contents](#repository-contents)\n- [Registration](#registration)\n- [Installation](#installation)\n- [Get started](#get-started)\n- [Options](#options)\n- [Handling errors](#handling-errors)\n- [Localization](#localization)\n- [API Client](#api-client)\n- [Sample code](#sample-code)\n- [Help \u0026 support](#help--support)\n\n## Introduction\nThe iProov Biometrics React Native SDK wraps iProov's native iOS (Swift) and Android (Java) SDKs behind a JavaScript interface for use from within your React Native iOS or Android app.\n\n### Requirements\n\n- React Native 0.73 and above\n- iOS 13.0 and above\n- Android API Level 26 (Android 8 Oreo) and above\n\n## Registration\n\nYou can obtain API credentials by registering on the [iProov Partner Portal](https://portal.iproov.net).\n\n## Installation\n\n1. Add the following to your package.json file:\n\t\n\t```json\n\t\"dependencies\": {\n\t  \"@iproov/react-native\": \"2.0.2\"\n\t}\n\t```\n\n2. From your React Native app directory, run:\n\t\n\t```sh\n\tyarn\n\t```\n\n### iOS installation\n\n1. Add an `NSCameraUsageDescription` entry to your app's Info.plist, with the reason why your app requires camera access (e.g. “To iProov you in order to verify your identity.”)\n\n2. You need to **Enable frameworks** - Cocoapods by default builds static libraries rather than frameworks. You should add the following to your Podfile:\n\t\n\t```ruby\n\tuse_frameworks!\n\t```\n\tPlease note that [Flipper](https://fbflipper.com/docs/getting-started/react-native/) does not work with `use_frameworks`, so you should remove it if you have it enabled.\n\t\n3. In your React Native app `ios` directory, run:\n\n\t```sh\n\tpod install\n\t```\t\n\t\t\n\tThis will install all Pods and apply the above workarounds.\n\t\n### Android installation\n\nYou must add the iProov repository URL to your `repositories` block inside the `allprojects` block in your build.gradle file:\n\n```groovy\nallprojects {\n    repositories {\n        maven { url 'https://raw.githubusercontent.com/iProov/android/master/maven/' } // Add this\n    }\n}\n```\n\n## Get started\n\nOnce you have a valid token (obtained via the React Native API client or your own backend-to-backend call), you can `launch()` an iProov capture and handle the callback events as follows:\n\n```javascript\nimport IProov from '@iproov/react-native'\nimport NativeEventEmitter from 'react-native'\n\nlet options = new IProov.Options()\noptions.filter = {\n\tname: IProov.Options.LINE_DRAWING,\n\tstyle: IProov.Options.CLASSIC,\n\tforegroundColor: '#00000055',\n\tbackgroundColor: '#32a852'\n}\n\nconst eventEmitter = new NativeEventEmitter(IProov.IProovReactNative)\n\nIProov.launch('wss://eu.rp.secure.iproov.me/ws', \"\u003c YOUR TOKEN \u003e\", options, eventEmitter, (event) =\u003e {\n\tswitch(event.name) {\n\t\n\tcase IProov.EVENT_CONNECTING:\n\t  // The SDK is connecting to the server. You should provide an indeterminate progress indicator\n\t  // to let the user know that the connection is taking place.\n\t  break\n\t\n\tcase IProov.EVENT_CONNECTED:\n\t  // The SDK has connected, and the iProov user interface will now be displayed. You should hide\n\t  // any progress indication at this point.\n\t  break\n\t\n\tcase IProov.EVENT_PROCESSING:\n\t  // The SDK will update your app with the progress of streaming to the server and authenticating\n\t  // the user. This will be called multiple times as the progress updates.\n  \n\t  let progress = event.params.progress\n\t  let message = event.params.message\n\t  break\n\t\n\tcase IProov.EVENT_CANCELED:\n\t  // Either the user canceled iProov by pressing the Close button at the top or\n\t  // the Home button (canceler == USER)\n\t  // Or the app canceled using Session.cancel() (canceler = APP).\n\t  // You should use this to determine the next step in your flow.\n\n\t  let canceler = event.params.canceler\n\t  break\n\t\n\tcase IProov.EVENT_FAILURE:\n\t  // The user was not successfully verified/enrolled, as their identity could not be verified,\n\t  // or there was another issue with their verification/enrollment. A reason (as a string)\n\t  // is provided as to why the claim failed, along with a feedback code from the back-end.\n  \n\t  let reason = event.params.reason\n\t  let frame = event.params.frame // Optional property containing a single Base64 encoded frame\n\t  break\n\t\n\tcase IProov.EVENT_SUCCESS:\n\t  // The user was successfully verified/enrolled and the token has been validated.\n   \n\t  let frame = event.params.frame // Optional property containing a single Base64 encoded frame\n\t  break\n\n\tcase IProov.EVENT_ERROR:\n\t  // The user was not successfully verified/enrolled due to an error (e.g. lost internet connection).\n\t  // You will be provided with an Exception (see below).\n\t  // It will be called once, or never.\n\t  let error = event.params.error\n\t  let reason = event.params.reason\n\t  let message = event.params.message\n\t  break\n\t}\n})\n```\n\n👉 You should now familiarize yourself with the following resources:\n\n-  [iProov Biometrics iOS SDK documentation](https://github.com/iProov/ios)\n-  [iProov Biometrics Android SDK documentation](https://github.com/iProov/android)\n\nThese repositories provide comprehensive documentation about the available customization options and other important details regarding the SDK usage.\n\n## Options\n\nThe `Options` class allows iProov to be customized in various ways. These can be specified by passing options in `IProov.launch()`.\n\nMost of these options are common to both Android and iOS, however, some are platform-specific.\n\nFor full documentation, please read the respective [iOS](https://github.com/iProov/ios#options) and [Android](https://github.com/iProov/android#options) native SDK documentation.\n\nA summary of the support for the various SDK options in React Native is provided below. All options can be null and any options not set will default to their platform-specific default value.\n\n| Option                                          | Type                                                                |   iOS   | Android |\n|-------------------------------------------------|---------------------------------------------------------------------|:-------:|:---------:|\n| `filter`                                        | `Options.(LINE_DRAWING\\|NATURAL_DRAWING)` [(See filter options)](#filter-options) | ✅ | ✅ |\n| `promptBackgroundColor`                         | `String` (#rgba)                                                    | ✅     | ✅     |\n| `promptTextColor`                               | `String` (#rgba)                                                    | ✅     | ✅     |\n| `promptRoundedCorners`                          | `Boolean`                                                           | ✅     | ✅     |\n| `title`                                         | `String`                                                            | ✅     | ✅     |\n| `titleTextColor`                                | `String` (#rgba)                                                    | ✅     | ✅     |\n| `surroundColor`                                 | `String` (#rgba)                                                    | ✅     | ✅     |\n| `font`                                          | `String`                                                            | ✅     | ✅     |\n| `fontPath`  (*)                                 | Unsupported                                                         | ❌     | ❌     |\n| `logoImage`                                     | `String` (Base64-encoded image)                                     | ✅     | ✅     |\n| `closeButtonImage`                              | `String` (Base64-encoded image)                                     | ✅     | ✅     |\n| `closeButtonTintColor`                          | `String` (#rgba)                                                    | ✅     | ✅     |\n| `certificates`                                  | `String[]` (base 64 encoded string in DER format)                   | ✅     | ✅     |\n| `timeout`                                       | `Number` (int)                                                      | ✅     | ✅     |\n| `enableScreenshots`                             | `Boolean`                                                           |        | ✅     |\n| `orientation`                                   | `Options.(PORTRAIT\\|LANDSCAPE\\|REVERSE_PORTRAIT\\|REVERSE_LANDSCAPE)`|        | ✅     |\n| `camera`                                        | `Options.(FRONT\\|EXTERNAL)`                                         |        | ✅     |\n| `headerBackgroundColor` | `String` (#rgba)  | ✅ | ✅ |\n| `disableExteriorEffects` | `Boolean` | ✅ | ✅ |\n| **`Options.genuinePresenceAssurance.`**         |                                                                     |        |        |\n| ↳`notReadyOvalStrokeColor `                      | `String` (#rgba)                                                    | ✅     | ✅     |\n| ↳`readyOvalStrokeColor `                         | `String` (#rgba)                                                    | ✅     | ✅     |\n| **`Options.livenessAssurance.`**                |                                                                     |        |         |\n| ↳`ovalStrokeColor`                               | `String` (#rgba)                                                    | ✅     | ✅     |\n| ↳`completedOvalStrokeColor`                      | `String` (#rgba)                                                    | ✅     | ✅     |\n\n(*) Custom fonts are not currently supported and will be added in a future version of the React Native SDK.\n\n### Filter Options\n\nThe SDK supports two different camera filters:\n\n#### `LINE_DRAWING`\n\n`LINE_DRAWING` is iProov's traditional \"canny\" filter, which is available in 3 styles: `IProov.Options.SHADED` (default), `IProov.Options.CLASSIC` and `IProov.Options.VIBRANT`.\n\nThe `foregroundColor` and `backgroundColor` can also be customized.\n\nExample:\n\n```javascript\nvar options = new IProov.Options()\noptions.filter = {\n\tname: IProov.Options.LINE_DRAWING,\n\tstyle: IProov.Options.CLASSIC,\n\tforegroundColor: '#00000055',\n\tbackgroundColor: '#32a852'\n}\n```\n\n\u003e **Note**: `foregroundColor` and `backgroundColor` are only applicable to `LINE_DRAWING` filter.\n\n#### `NATURAL`\n\n`NATURAL` provides a more direct visualization of the user's face and is available in 2 styles: `IProov.Options.CLEAR` (default) and `IProov.Options.BLUR`.\n\nExample:\n\n```javascript\nvar options = new IProov.Options()\noptions.filter = {\n\tname: IProov.Options.NATURAL,\n\tstyle: IProov.Options.CLEAR\n}\n```\n\n\u003e **Note**: `NATURAL` is available for Liveness Assurance claims only. Attempts to use `NATURAL` for Genuine Presence Assurance claims will result in an error.\n\n## Handling errors\n\nIProov listener error events will contain an `error` string within the events `params` property which maps to native exceptions:\n\n| Exception                         | iOS | Android | Description                                                                                                                      |\n| --------------------------------- | :---: | :-------: | -------------------------------------------------------------------------------------------------------------------------------- |\n| `capture_already_active_error`   | ✅   | ✅       | An existing iProov capture is already in progress. Wait until the current capture completes before starting a new one.           |\n| `network_error`                    | ✅   | ✅       | An error occurred with the video streaming process. Consult the `message` value for more information.                            |\n| `camera_permission_error`           | ✅   | ✅       | The user disallowed access to the camera when prompted. You should direct the user to re-enable camera access.                   |\n| `server_error`                 | ✅   | ✅       | A server-side error/token invalidation occurred. The associated `message` will contain further information about the error.      |\n| `unexpected_error`        | ✅   | ✅       | An unexpected and unrecoverable error has occurred. These errors should be reported to iProov for further investigation.         |\n| `unsupported_device_error`         |✅   | ✅         | Device is not supported.|\n| `multi_window_unsupported_error` |     | ✅       | The user attempted to iProov in split-screen/multi-screen mode, which is not supported.                                          |\n| `camera_error`                 |     | ✅       | An error occurred acquiring or using the camera. This could happen when a non-phone is used with/without an external/USB camera. |\n| `face_detector_error`           |     | ✅       | An error occurred with the face detector.                                                                                        |\n| `invalid_options_error`         |     | ✅       | An error occurred when trying to apply your options.                                                                             |\n| `user_timeout_error`         |✅   |          | The user has taken too long to complete the claim.|\n\n\n\n\n## Localization\n\nString localization is handled by adding translations to both native components, you can do this by following the instructions of the respective platform of the native iProov SDK.\u003cbr/\u003e\n* [iProov Biometrics iOS SDK localization documentation](https://github.com/iProov/ios#localization)\u003cbr/\u003e\n* [iProov Biometrics Android SDK localization documentation](https://github.com/iProov/android#localization)\n\n## API Client\n\nThe React Native API Client provides a convenient wrapper to call iProov's REST API v2 from a React Native app. It is a useful tool to assist with testing, debugging and demos, but should not be used in production mobile apps.\n\nThe React Native API client can be found in `ApiClient.js`.\n\nTo setup your credentials, copy `credentials.example.js` to `credentials.js` and add them to the example project.\n\n\u003e ⚠️ **SECURITY NOTICE:** Use of the React Native API Client requires providing it with your API secret. **You should never embed your API secret within a production app.**\n\n### Functionality\n\nThe React Native API Client supports the following functionality:\n\n- `getToken()` - Get an enrol/verify token\n- `enrolPhoto()` - Perform a photo enrolment (either from an electronic or optical image). The image must be provided as a base64 encoded jpeg represented as a string.\n- `enrolPhotoAndGetVerifyToken()` - A convenience method which first gets an enrolment token, then enrols the photo against that token, and then gets a verify token for the user to iProov against.\n- `validate()` - Validates a token, this is typically called via a backend-to-backend call to ensure that the claim was successful.\n- `invalidate()` - Used to cancel (invalidate) a token. Once a token has been invalidated, it can no longer be used.\n\n### Getting a token\n\nThe most useful thing you can do with the API Client is get a token to either enrol or verify a user, using either iProov's Genuine Presence Assurance or Liveness Assurance.\n\nThis is achieved as follows:\n\n```javascript\nimport ApiClient, { CLAIM_TYPE_ENROL, ASSURANCE_TYPE_LIVENESS } from './ApiClient.js'\n\nlet apiClient = ApiClient({\n  baseUrl: \"https://eu.rp.secure.iproov.me/api/v2/\", // Substitute URL as appropriate\n  apiKey: \"\u003c YOUR API KEY \u003e\",\n  secret: \"\u003c YOUR SECRET \u003e\"\n});\n\nlet token = await apiClient.getToken(ASSURANCE_TYPE_LIVENESS, CLAIM_TYPE_ENROL, \"name@example.com\");\n```\n\nYou can then launch the iProov SDK with this token.\n\n## Sample code\n\nFor a simple iProov experience that is ready to run out-of-the-box, check out the React Native example project which also makes use of the React Native API Client.\n\nCopy the `credentials.example.js` file to `credentials.js` and add your credentials obtained from the [iProov portal](https://portal.iproov.com/).\n\nOnce you have completed the [installation](#installation) instructions, to run the example app, you should run the following commands:\n\n```sh\nnpx react-native run-android\t\t# Run on Android\nnpx react-native run-ios --device\t# Run on iOS\n```\n\n\u003e NOTE: iProov is not supported on the iOS or Android simulator, you must use a physical device in order to iProov.\n\n## Help \u0026 support\n\nYou may find your question is answered in the documentation of our native SDKs:\n\n- iOS - [Documentation](https://github.com/iProov/ios), [FAQs](https://github.com/iProov/ios/wiki/Frequently-Asked-Questions)\n- Android - [Documentation](https://github.com/iProov/android), [FAQs](https://github.com/iProov/android/wiki/Frequently-Asked-Questions)\n\nFor further help with integrating the SDK, please contact [support@iproov.com](mailto:support@iproov.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiproov%2Freact-native","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiproov%2Freact-native","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiproov%2Freact-native/lists"}