youverify-liveness-web 0.1.31 → 1.0.1

package/README.md

@@ -64,7 +64,7 @@ try {
 | Option | Type | Required | Description | Default Value | Possible Values |
 | --- | --- | --- | --- | --- | --- |
 | `presentation` | String | No | Controls how UI is displayed | `modal` | `modal`, `page` |
-| `publicKey` | String | Yes | Your Youverify Public Merchant Key | undefined | Valid Youverify Public Key |
+| `publicKey` | String | No | Your Youverify Public Merchant Key | undefined | Valid Youverify Public Key |
 | `sandboxEnvironment` | Boolean | No | Sets whether session should run in sandbox or live mode | `true` | `true`, `false` |
 | `tasks` | Array | No | Sets tasks that need to be performed for liveness to be confirmed | undefined | See [tasks](#tasks) |
 | `user` | Object | No | Sets details of user for which liveness check is being performed | undefined | See nested options below |
@@ -72,12 +72,218 @@ try {
 | `user.lastName` | String | No | Last name of user | undefined | Any string
 | `user.email` | String | No | Email of user | undefined | Any string |
 | `branding` | Object | No | Customizes UI to fit your brand | undefined | See nested options below
+| `branding.name` | String | No | The name of the brand | undefined | Any string |
 | `branding.color` | String | No | Sets your branding color | undefined | Valid hex or RGB string |
 | `branding.logo` | String | No | Sets your logo | undefined | Valid image link |
+| `branding.logoAlt` | String | No | Alternative text for the brand logo | "Youverify" | Any string |
+| `branding.hideLogoOnMobile` | Boolean | No | Hides logo in mobile webview | `false` | `true`, `false` |
+| `branding.showPoweredBy` | Boolean | No | Displays "Powered by" footer text | `false` | `true`, `false` |
+| `branding.poweredByText` | String | No | Customizes the "Powered by" text | "Powered by" | Any string |
+| `branding.poweredByLogo` | String | No | Customizes the "Powered by" logo | undefined | Valid image link |
 | `allowAudio` | Boolean | No | Sets whether to narrate information to user during tasks | false | `true`, `false` |
 | `onClose` | Function | No | Callback function that gets triggered when modal is closed | undefined | Any valid function |
 | `onSuccess` | Function | No | Callback function that gets triggered when all tasks have been completed and passed. Called with completion [data](#callback-data) | undefined | Any valid function |
 | `onFailure` | Function | No | Callback function that gets triggered when at least one task fails. Called with completion [data](#callback-data) | undefined | Any valid function |
+| `sessionId` | String | Yes (required) | ID generated by your backend using your API key. Validated before SDK init and attached to submissions | - | Any valid session ID |
+| `sessionToken` | String | Yes (required) | Token generated by your backend for liveness verification | - | Any valid session token |
+
+### Breaking change: session token generation now external
+
+- The SDK no longer generates session tokens internally.
+- Partners must call their backend to generate both `sessionId` and `sessionToken` and pass them to the SDK via the respective options.
+
+### Base URL Configuration
+
+All API endpoints use the following base URL:
+
+Sandbox base URL:
+```
+https://api.sandbox.youverify.co
+```
+
+Live base URL:
+```
+https://api.youverify.co
+```
+
+### Session ID Generation
+
+Before initializing the SDK, you must generate a `sessionId` by calling your backend API. Your backend should make the following request:
+
+**Endpoint:** `POST /v2/api/identity/sdk/session/generate`
+
+**Headers:**
+```json
+{
+  "Content-Type": "application/json",
+  "Token": "YOUR_API_KEY"
+}
+```
+
+**Request Body:**
+```json
+{
+  "publicMerchantID": "your_public_merchant_id",
+  "metadata": {}
+}
+```
+
+**Response:**
+```json
+{
+  "sessionId": "generated_session_id_here"
+}
+```
+
+**Error Handling:**
+- The `sessionId` should be passed to the SDK constructor
+
+### Session Token Generation
+
+Additionally, you need to generate a `sessionToken` for liveness verification:
+
+**Endpoint:** `POST /v2/api/identity/sdk/liveness/token`
+
+**Headers:**
+```json
+{
+  "Content-Type": "application/json",
+  "Token": "YOUR_API_KEY"
+}
+```
+
+**Request Body:**
+```json
+{
+  "publicMerchantID": "your_public_merchant_id",
+  "deviceCorrelationId": "unique_device_identifier"
+}
+```
+
+**Response:**
+```json
+{
+  "authToken": "generated_auth_token_here"
+}
+```
+
+**Error Handling:**
+- The `authToken` from the response should be passed as `sessionToken` to the SDK constructor
+
+### Complete Integration Flow
+
+1. **Generate Session ID:** Call your backend to generate `sessionId` using the session generation endpoint
+2. **Generate Session Token:** Call your backend to generate `sessionToken` using the liveness token endpoint
+3. **Initialize SDK:** Pass both `sessionId` and `sessionToken` to the SDK constructor
+4. **SDK Validation:** The SDK validates the `sessionId` before initialization
+5. **Error Handling:** If validation fails, `onFailure` is called with key `invalid_or_expired_session` and `session_token_error` for both
+6. **Success:** Upon successful initialization, the SDK uses the `sessionToken` for liveness verification
+
+### Error Keys
+
+- `invalid_or_expired_session`: Returned when the `sessionId` is invalid or expired
+- `session_token_error`: Returned when there's an issue with the `sessionToken` during liveness verification
+
+### Retry Logic
+
+- If session validation fails, generate a new `sessionId` and retry
+- If liveness fails, users may retry while the current `sessionId` remains valid
+- If the `sessionId` expires, create a new session and restart the entire process
+
+### Complete Example Implementation
+
+Here's a complete example showing how to implement the session generation and SDK initialization:
+
+```javascript
+// Backend API calls (these should be made from your backend)
+const generateSessionId = async (publicMerchantID, apiToken) => {
+  const response = await fetch('https://api.sandbox.youverify.co/v2/api/identity/sdk/session/generate', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Token': `${apiToken}`
+    },
+    body: JSON.stringify({
+      publicMerchantID: publicMerchantID,
+      metadata: {}
+    })
+  });
+  
+  const data = await response.json();
+  return data.sessionId;
+};
+
+const generateSessionToken = async (publicMerchantID, deviceCorrelationId, apiToken) => {
+  const response = await fetch('https://api.sandbox.youverify.co/v2/api/identity/sdk/liveness/token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Token': `${apiToken}`
+    },
+    body: JSON.stringify({
+      publicMerchantID: publicMerchantID,
+      deviceCorrelationId: deviceCorrelationId
+    })
+  });
+  
+  const data = await response.json();
+  return data.authToken;
+};
+
+// Frontend SDK initialization
+const initializeLivenessSDK = async () => {
+  try {
+    // Generate session ID and token (these calls should be made from your backend)
+    const sessionId = await generateSessionId('your_public_merchant_id', 'your_api_key');
+    const sessionToken = await generateSessionToken('your_public_merchant_id', 'unique_device_id', 'your_api_key');
+    
+    // Initialize the SDK with generated credentials
+    const yvLiveness = new YouverifyLiveness({
+      sessionId: sessionId,
+      sessionToken: sessionToken,
+      sandboxEnvironment: true,
+      onSuccess: (data) => {
+        console.log('Liveness check passed:', data);
+        // Handle successful liveness check
+      },
+      onFailure: (data) => {
+        console.log('Liveness check failed:', data);
+        
+        // Handle specific error cases
+        if (data.error && data.error.key === 'invalid_or_expired_session') {
+          // Session expired, generate new session and retry
+          console.log('Session expired, retrying...');
+          initializeLivenessSDK();
+        } else if (data.error && data.error.key === 'session_token_error') {
+          // Session token error, generate new token and retry
+          console.log('Session token error, retrying...');
+          initializeLivenessSDK();
+        }
+      }
+    });
+    
+    // Start the liveness check
+    yvLiveness.start();
+    
+  } catch (error) {
+    console.error('Failed to initialize liveness SDK:', error);
+    // Handle initialization errors
+  }
+};
+
+// Call the initialization function
+initializeLivenessSDK();
+```
+
+### Important Notes
+
+1. **API Token Security:** Never expose your API token in frontend code. All API calls to generate `sessionId` and `sessionToken` should be made from your secure backend.
+
+2. **Device Correlation ID:** The `deviceCorrelationId` should be a unique identifier for the user's device/session. This helps track and prevent abuse.
+
+3. **Error Handling:** Always implement proper error handling for both API calls and SDK initialization to provide a smooth user experience.
+
+4. **Environment:** Use `sandboxEnvironment: true` for testing and `sandboxEnvironment: false` for production.
 
 ## Tasks
 

package/dist/index.d.ts

@@ -5,6 +5,12 @@ declare interface BlinkTask extends TaskBase<"blink"> {
 declare interface Branding {
     logo?: string;
     color?: string;
+    name?: string;
+    logoAlt?: string;
+    hideLogoOnMobile?: boolean;
+    showPoweredBy?: boolean;
+    poweredByText?: string;
+    poweredByLogo?: string;
 }
 
 declare type CompleteTheCircleTask = TaskBase<"complete-the-circle">;
@@ -25,12 +31,15 @@ declare interface LivenessWebSdkProps {
     tasks?: Array<Task>;
     user?: User;
     branding?: Branding;
+    isMobileAppWebView?: boolean;
     allowAudio?: boolean;
     onClose?: () => void;
     onSuccess?: (data: LivenessData) => void;
     onFailure?: (data: LivenessData) => void;
     metadata?: Metadata;
     sandboxEnvironment?: boolean;
+    sessionId: string;
+    sessionToken: string;
 }
 
 declare type Metadata = Record<string, any>;