@soyio/soyio-rn-sdk 2.3.1 → 3.1.0

package/README.md

@@ -14,7 +14,7 @@
 
 ## Installation
 
-- Install using npm! (or your favorite package manager)
+- Install using npm (or your favorite package manager)
 
 ```sh
 # Using npm
@@ -24,22 +24,147 @@ npm install @soyio/soyio-rn-sdk
 yarn add @soyio/soyio-rn-sdk
 ```
 
-- Add custom uri scheme to your project:
+- You'll also need to install the required peer dependencies:
 
-```bash
-npx uri-scheme add custom-uri-scheme
+```sh
+# Using npm
+npm install react-native-webview react-native-inappbrowser-reborn
+
+# Using yarn
+yarn add react-native-webview react-native-inappbrowser-reborn
+```
+
+**iOS Setup:** Run `cd ios && pod install` to install native dependencies.
+
+**Android Setup:** For React Native 0.60+, auto-linking should handle Android setup automatically. For older versions, follow the [manual linking guide](https://github.com/react-native-webview/react-native-webview/blob/master/docs/Getting-Started.md).
+
+## Android setup (repositories, permissions, deep links)
+
+Add these to your app so bundled native dependencies and deep linking work when consuming the SDK from npm.
+
+1) Repositories (`android/settings.gradle`) - **Only required if you want to use NFC validation**
+
+```gradle
+dependencyResolutionManagement {
+  repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
+  repositories {
+    // Keep your normal repositories here (e.g., google(), mavenCentral()) as appropriate for your project/architecture.
+    // Add this flatDir so bundled native dependencies are resolvable:
+    flatDir {
+      dirs(
+        "$rootDir/../node_modules/@soyio/soyio-rn-sdk/android/libs",
+      )
+    }
+  }
+}
+```
+
+2) Manifest entries (`android/app/src/main/AndroidManifest.xml` inside `<manifest>`)
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-feature android:name="android.hardware.camera" android:required="true" />
+```
+
+If you want to enable NFC validation with the `SoyioWidget`, also add:
+
+```xml
+<uses-permission android:name="android.permission.NFC" />
+<uses-feature android:name="android.hardware.nfc" android:required="false" />
+```
+
+3) Deep link for returning from the in-app browser: add an intent filter in your main `<activity>` with your chosen scheme (must match `uriScheme` passed to the SDK)
+
+```xml
+<intent-filter>
+  <action android:name="android.intent.action.VIEW" />
+  <category android:name="android.intent.category.DEFAULT" />
+  <category android:name="android.intent.category.BROWSABLE" />
+  <data android:scheme="your-app-scheme" />
+</intent-filter>
+```
+
+After changes, rebuild the Android app (`cd android && ./gradlew :app:assembleDebug` or `yarn android`).
+
+## iOS Setup (permissions, NFC, deep links)
+
+Add these to your app so native dependencies, NFC scanning, and deep linking work when consuming the SDK from npm.
+
+### 1. Native Dependencies
+
+After installing the package and peer dependencies, run:
+
+```sh
+cd ios && pod install
+```
+
+### 2. Permissions
+
+Add the following permissions to your `ios/YourApp/Info.plist` file:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>This app needs access to camera for document verification</string>
 ```
 
-Here, `custom-uri-scheme` is a unique scheme used for redirecting within Android applications, ensuring links open in the correct app without prompting the user to choose. It should be structured uniquely for your application. For example, for a company with name `Test`, a custom uri scheme could be `soyio-test` or simply `test`.
+If you want to enable NFC validation with the `SoyioWidget`, also add:
 
-**IMPORTANT:**
-For developers integrating with a **bare React Native** application, it's crucial to prepare your project for Expo modules:
+```xml
+<key>NFCReaderUsageDescription</key>
+<string>This app needs access to NFC for identity document verification</string>
 
-`npx install-expo-modules`: This command installs Expo modules in your React Native project, allowing you to use Expo's powerful library of APIs and components without needing to eject from the Expo managed workflow.
+<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
+<array>
+    <string>A0000002471001</string>
+    <string>A0000002472001</string>
+</array>
+```
+
+### 3. NFC Entitlements
+
+For NFC to work, you also need to create (or update) your entitlements file at `ios/YourApp/YourApp.entitlements`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.developer.nfc.readersession.formats</key>
+    <array>
+        <string>TAG</string>
+    </array>
+</dict>
+</plist>
+```
+
+Then, in Xcode, ensure the entitlements file is linked to your target:
+1. Select your project in Xcode
+2. Go to your app target's **Signing & Capabilities** tab
+3. Add **Near Field Communication Tag Reading** capability (if not already added)
+4. Verify the entitlements file path is set in **Build Settings → Code Signing Entitlements**
+
+
+## URI Scheme Setup
+
+You need to configure a custom URI scheme for your application to handle deep linking properly:
+
+```sh
+npx uri-scheme add custom-uri-scheme
+```
+
+Replace `custom-uri-scheme` with your desired scheme name. This scheme should match the `uriScheme` parameter you use in the `SoyioWidget` options.
 
 ## Usage
 
-`Soyio React Native` exports a single hook called `useSoyioAuth`. This is a hook that opens a `WebBrowser` using the `openAuthSessionAsync` method by [expo](https://docs.expo.dev/versions/latest/sdk/webbrowser/#webbrowseropenauthsessionasyncurl-redirecturl-options).
+`Soyio React Native` provides two ways to integrate the Soyio verification flow:
+
+1. **Component**: A `SoyioWidget` component that renders a WebView within your app.
+2. **InAppBrowser Functions**: Direct functions that open the verification flow in an in-app browser.
+
+> ℹ️ **NFC validation** is only available when you integrate with the `SoyioWidget` component (WebView). The InAppBrowser mode does not support NFC.
+
+## Component Integration
 
 ### 1. Disclosure Request
 
@@ -57,40 +182,44 @@ To instantiate this process in the code, you have two options:
 This doesn't require any previous setup. Given your company and disclosure template IDs, you can create disclosure requests freely when the user starts the widget:
 
 ```jsx
-import { useSoyioAuth } from "@soyio/soyio-rn-sdk";
+import { View, StyleSheet } from "react-native";
+import { SoyioWidget } from "@soyio/soyio-rn-sdk";
 
 export default function App() {
   const options = {
-    companyId: "<company id>",                     // Starts with 'com_'
-    uriScheme: "<company custom uri scheme>"
+    uriScheme: "<your-app-scheme>", // Required: Your app's URI scheme
+    companyId: "<company id>", // Optional: Starts with 'com_'
     userReference: "<company identifier of user>", // Optional
-    customColor: "<custom color>",                 // Optional
-    isSandbox: true,                               // Optional
+    isSandbox: true, // Optional
   };
 
   // For initialize a disclosure request
   const disclosureParams = {
-    templateId: "<template id>",          // Starts with 'dtpl_'
-    userEmail: "<user email>",            // Optional
-    forceError: '<error type>',           // Optional
-  };
-
-  const onEventChange = (event) => {
-    console.log("Event:", event);
+    templateId: "<template id>", // Starts with 'dtpl_'
+    userEmail: "<user email>", // Optional
   };
 
-  const { disclosure } = useSoyioAuth({ options, onEventChange });
-
-  const initDisclosureRequest = () => {
-    disclosure(disclosureParams);
+  const handleSuccess = () => {
+    console.log("Verification successful!");
   };
 
   return (
-    <View>
-      <Button title="Disclosure request" onPress={initDisclosureRequest} />
+    <View style={styles.container}>
+      <SoyioWidget
+        options={options}
+        requestType="disclosure"
+        requestParams={disclosureParams}
+        onSuccess={handleSuccess}
+      />
     </View>
   );
 }
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});
 ```
 
 #### 1.b Created disclosure request:
@@ -102,38 +231,41 @@ For more details about the use case, please refer to [the documentation](https:/
 To use this option, simply specify the disclosure request ID along with any optional parameters:
 
 ```jsx
-import { useSoyioAuth } from "@soyio/soyio-rn-sdk";
+import { View, StyleSheet } from "react-native";
+import { SoyioWidget } from "@soyio/soyio-rn-sdk";
 
 export default function App() {
   const options = {
-    uriScheme: "<company custom uri scheme>"
-    customColor: "<custom color>",                 // Optional
-    isSandbox: false,                              // Optional
+    uriScheme: "<your-app-scheme>", // Required: Your app's URI scheme
+    isSandbox: false, // Optional
   };
 
   // For initialize a disclosure request
   const disclosureParams = {
-    disclosureRequestId: "<disclosure request id>",  // Starts with 'dreq_'
-    userEmail: "<user email>",                       // Optional
-    forceError: '<error type>',                      // Optional
+    disclosureRequestId: "<disclosure request id>", // Starts with 'dreq_'
   };
 
-  const onEventChange = (event) => {
-    console.log("Event:", event);
-  };
-
-  const { disclosure } = useSoyioAuth({ options, onEventChange });
-
-  const initDisclosureRequest = () => {
-    disclosure(disclosureParams);
+  const handleSuccess = () => {
+    console.log("Verification successful!");
   };
 
   return (
-    <View>
-      <Button title="Disclosure request" onPress={initDisclosureRequest} />
+    <View style={styles.container}>
+      <SoyioWidget
+        options={options}
+        requestType="disclosure"
+        requestParams={disclosureParams}
+        onSuccess={handleSuccess}
+      />
     </View>
   );
 }
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});
 ```
 
 Note that user and template properties are not specified here because they must be specified when creating the disclosure request beforehand.
@@ -143,97 +275,147 @@ Note that user and template properties are not specified here because they must
 The **`auth_request`** is a process where, using a previously created `auth_request_id`, a request is initiated in which a user can authenticate with Soyio. This authentication can occur either through an access key or facial video.
 
 ```jsx
-import { useSoyioAuth } from "@soyio/soyio-rn-sdk";
+import { View, StyleSheet } from "react-native";
+import { SoyioWidget } from "@soyio/soyio-rn-sdk";
 
 export default function App() {
   const options = {
-    uriScheme: "<company custom uri scheme>"
-    customColor: "<custom color>",                 // Optional
-    isSandbox: false,                              // Optional
+    uriScheme: "<your-app-scheme>", // Required: Your app's URI scheme
+    isSandbox: false, // Optional
   };
 
   const authRequestParams = {
-    authRequestId: "<auth request id>" // Starts with 'authreq_'
-  }
-
-  const onEventChange = (event) => {
-    console.log("Event:", event);
+    authRequestId: "<auth request id>", // Starts with 'authreq_'
   };
 
-  const { authentication } = useSoyioAuth({ options, onEventChange });
-
-  const initAuthRequest = () => {
-    authentication(authRequestParams);
+  const handleSuccess = () => {
+    console.log("Authentication successful!");
   };
 
   return (
-    <View>
-      <Button title="Auth Request" onPress={initAuthRequest} />
+    <View style={styles.container}>
+      <SoyioWidget
+        options={options}
+        requestType="authentication_request"
+        requestParams={authRequestParams}
+        onSuccess={handleSuccess}
+      />
     </View>
   );
 }
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});
 ```
 
-The `onEventChange` function can return the following objects:
+### Event Handling
 
-1. When a request is successful:
+The `SoyioWidget` component supports the following event handlers:
 
-```js
-{
-  type: "success",
-  request: "disclosure" | "authRequest",
-  verificationKind: "validation" | "authentication",
-  userReference: "<company-user-reference>",
-  identityId: "<soyio-identity-id-of-user>",
-}
-```
+- **`onSuccess`**: Called when the verification/authentication process completes successfully
 
-2. When webview is opened:
+## InAppBrowser Integration
 
-```js
-{
-  type: "open";
-}
+For cases where you prefer to open the verification flow in an in-app browser instead of a WebView, you can use the direct function approach.
+
+### 1. Disclosure Request (InAppBrowser)
+
+#### 1.a Disclosure request on-the-fly:
+
+```jsx
+import { openDisclosure } from "@soyio/soyio-rn-sdk";
+
+const handleDisclosure = async () => {
+  const options = {
+    uriScheme: "<your-app-scheme>", // Required: Your app's URI scheme
+    companyId: "<company id>", // Optional: Starts with 'com_'
+    userReference: "<company identifier of user>", // Optional
+    isSandbox: true, // Optional
+  };
+
+  const disclosureParams = {
+    templateId: "<template id>", // Starts with 'dtpl_'
+    userEmail: "<user email>", // Optional
+  };
+
+  await openDisclosure({
+    options,
+    requestParams: disclosureParams,
+    onComplete: () => console.log("Disclosure completed successfully!"),
+    onCancel: () => console.log("Disclosure was cancelled by user"),
+  });
+};
 ```
 
-3. When webview is closed:
+#### 1.b Created disclosure request:
 
-```js
-{
-  type: "cancel";
-}
+```jsx
+import { openDisclosure } from "@soyio/soyio-rn-sdk";
+
+const handleDisclosure = async () => {
+  const options = {
+    uriScheme: "<your-app-scheme>", // Required: Your app's URI scheme
+    isSandbox: false, // Optional
+  };
+
+  const disclosureParams = {
+    disclosureRequestId: "<disclosure request id>", // Starts with 'dreq_'
+  };
+
+  await openDisclosure({
+    options,
+    requestParams: disclosureParams,
+    onComplete: () => console.log("Disclosure completed successfully!"),
+    onCancel: () => console.log("Disclosure was cancelled by user"),
+  });
+};
 ```
 
-4. When user exits because of error:
+### 2. Auth Request (InAppBrowser)
 
-```js
-{
-  type: "error",
-  request: "disclosure" | "authRequest",
-  error: "UNEXPECTED_ERROR"
-}
+```jsx
+import { openAuthenticationRequest } from "@soyio/soyio-rn-sdk";
+
+const handleAuthRequest = async () => {
+  const options = {
+    uriScheme: "<your-app-scheme>", // Required: Your app's URI scheme
+    isSandbox: false, // Optional
+  };
+
+  const authRequestParams = {
+    authRequestId: "<auth request id>", // Starts with 'authreq_'
+  };
+
+  await openAuthenticationRequest({
+    options,
+    requestParams: authRequestParams,
+    onComplete: () => console.log("Authentication completed successfully!"),
+    onCancel: () => console.log("Authentication was cancelled by user"),
+  });
+};
 ```
 
-#### Attribute Descriptions
+### Event Handling (InAppBrowser)
 
-- **`companyId`**: The unique identifier for the company, must start with `'com_'`.
-- **`userReference`**: (Optional) A reference identifier provided by the company for the user engaging with the widget. This identifier is used in events (`onEvent` and `webhooks`) to inform the company which user the events are associated with.
-- **`userEmail`**: The user's email address.
-- **`forceError`**: (Optional) Triggers specific errors for testing or debugging. Used to simulate failure scenarios.
-- **`templateId`**: Identifier of template. Specifies the order and quantity of documents requested from the user, as well as the mandatory data that the user is asked to share with the company. It must start with `'datmp_'`.
-- **`customColor`**: (Optional) A hex code string that specifies the base color of the interface
-- **`isSandbox`**: (Optional) Indicates if the widget should operate in sandbox mode, defaulting to `false`.
-- **`uriScheme`**: The unique redirect scheme you've set with `npx uri-scheme add ...`, critical for redirect handling in your app.
-- **`authRequestId`**: Identifier of auth request obtained when creating the `AuthRequest`. It must start with `'authreq_'`.
+The InAppBrowser functions support the following callback handlers:
 
-#### Error types
+- **`onComplete`**: Called when the verification/authentication process completes successfully
+- **`onCancel`**: Called when the user cancels the process or navigates away
 
-The `forceError` parameter can simulate the following error conditions:
+#### Attribute Descriptions
 
-- `'user_exists'`: Triggers an error indicating that a user with the given credentials already exists in the system.
-- `'facial_validation_error'`: Simulates a failure in the facial video liveness test, indicating the system could not verify the user's live presence.
-- `'document_validation_error'`: Indicates an issue with validating the photos of the documents provided by the user.
-- `'unknown_error'`: Generates a generic error, representing an unspecified problem.
+- **`uriScheme`**: (Required) The URI scheme for your application, used for deep linking and navigation.
+- **`companyId`**: (Optional) The unique identifier for the company, must start with `'com_'`.
+- **`userReference`**: (Optional) A reference identifier provided by the company for the user engaging with the widget. This identifier is used in events (`onEvent` and `webhooks`) to inform the company which user the events are associated with.
+- **`userEmail`**: (Optional) The user's email address.
+- **`templateId`**: (Required for new disclosure requests) Identifier of template. Specifies the order and quantity of documents requested from the user, as well as the mandatory data that the user is asked to share with the company. It must start with `'dtpl_'`.
+- **`isSandbox`**: (Optional) Indicates if the widget should operate in sandbox mode, defaulting to `false`.
+- **`developmentUrl`**: (Optional) Custom development URL for testing purposes.
+- **`authRequestId`**: (Required for authentication requests) Identifier of auth request obtained when creating the `AuthRequest`. It must start with `'authreq_'`.
+- **`disclosureRequestId`**: (Required for existing disclosure requests) Identifier of an existing disclosure request. It must start with `'dreq_'`.
 
 #### TypeScript support
 
@@ -241,10 +423,10 @@ This package includes TypeScript declarations.
 
 #### Developing
 
-To develop the package, you need to use `npm`. Install the dependencies:
+To develop the package, you need to use `yarn`. Install the dependencies:
 
 ```sh
-npm install
+yarn install
 ```
 
 To test locally, I recommend packaging the app. Remember to build the library first:
@@ -253,30 +435,3 @@ To test locally, I recommend packaging the app. Remember to build the library fi
 npm run build
 npm pack
 ```
-
-This will create a `soyio-soyio-rn-sdk-x.x.x.tgz` file (with the corresponding package version). Now, go to another directory and create a React Native app (using Expo, perhaps). After creating the new application, add the following dependency to its `package.json` file:
-
-```json
-{
-  "dependencies": {
-    ...,
-    "@soyio/soyio-rn-sdk": "file:./path/to/soyio-soyio-rn-sdk-x.x.x.tgz",
-    ...
-  }
-}
-```
-
-Where `./path/to/soyio-soyio-rn-sdk-x.x.x.tgz` corresponds to the path to the `.tgz` file created on the `npm pack` step. After running `npm install` on the new React Native app, you should be able to use Soyio React Native to import the Soyio View.
-
-If you want to create a new _release_, you can run:
-
-```sh
-git switch main
-npm run bump! <major|minor|patch>
-```
-
-This will create a new branch with the updated version from `main`.
-
-## Acknowledgements
-
-This implementation was written based on the input and experience of [**fintoc**](https://github.com/fintoc-com/fintoc-react-native) integrating the WebView using React Native, which served as a good starting point for the general idea of this library.

package/android/build.gradle

@@ -0,0 +1,56 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+    compileSdkVersion safeExtGet('compileSdkVersion', 34)
+    def javaVersion = safeExtGet('javaVersion', JavaVersion.VERSION_17)
+
+    defaultConfig {
+        minSdkVersion safeExtGet('minSdkVersion', 21)
+        targetSdkVersion safeExtGet('targetSdkVersion', 34)
+        versionCode 1
+        versionName "1.0"
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility javaVersion
+        targetCompatibility javaVersion
+    }
+
+    kotlinOptions {
+        jvmTarget = javaVersion.toString()
+    }
+
+    sourceSets {
+        main {
+            assets.srcDirs += ['../assets']
+        }
+    }
+}
+
+repositories {
+    flatDir {
+        dirs 'libs'
+    }
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    def kotlinVersion = safeExtGet('kotlinVersion', '1.8.0')
+    implementation "com.facebook.react:react-native:+"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlinVersion"
+    implementation(name: "facetec-sdk-9.7.96", ext: "aar")
+    implementation "com.squareup.okhttp3:okhttp:3.12.13"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.soyio.soyiorndk">
+
+    <!-- Add any permissions your module needs here -->
+    <!-- Example: <uses-permission android:name="android.permission.INTERNET" /> -->
+
+</manifest>