@cookiejar-technologies/finvu-auth-sdk-rn

React Native SDK for Finvu Authentication, supporting both native and WebView integration flows.

Installation

Works in both bare React Native and Expo apps (development build, not Expo Go — custom native modules are not supported in Expo Go).

1. Install the package and its peer dependency

npm install @cookiejar-technologies/finvu-auth-sdk-rn react-native-webview

2. iOS

cd ios && pod install

The iOS xcframework is fetched automatically by the package's podspec — no manual pod 'FinvuAuthenticationSDK', ... line in your Podfile.

Requirement: iOS deployment target ≥ 16.0. Bump it in ios/Podfile and your Xcode project's "Minimum Deployments" setting.

3. Android

Autolinking handles the registration — no MainApplication.java edits required.

Requirements:

• android/build.gradle minSdkVersion ≥ 25.
• Add these permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />

The Android SDK is pulled from Maven Central — no GitHub Packages credentials needed.

Usage

Option 1: Native Integration

Use this approach when you want to build your own UI and call SDK methods directly.

import { 
  FinvuAuthSdkInstance, 
  FinvuAuthEnvironment 
} from '@cookiejar-technologies/finvu-auth-sdk-rn';

// 1. Setup (call once when app starts)
FinvuAuthSdkInstance.setup(FinvuAuthEnvironment.DEVELOPMENT);

// 2. Initialize authentication
const initResponse = await FinvuAuthSdkInstance.initAuth({
  requestId: "your-request-id"
});

if (initResponse.status === 'SUCCESS') {
  console.log('Init successful:', initResponse);
  
  // 3. Start authentication with SNA link
  const startResponse = await FinvuAuthSdkInstance.startAuth(
    "https://snaUrl?requestId=909033243.com/..."
  );
  
  if (startResponse.status === 'SUCCESS') {
    console.log('Auth token:', startResponse.token);
  }
}

// 4. Cleanup when done
FinvuAuthSdkInstance.cleanupAll();

Option 2: WebView Integration

Use this approach to load a web app that handles the UI, with the SDK bridging messages to native code.

import React, { useRef, useEffect } from 'react';
import { View } from 'react-native';
import WebView from 'react-native-webview';
import { 
  FinvuAuthenticationWebviewWrapper, 
  FinvuAuthEnvironment 
} from '@cookiejar-technologies/finvu-auth-sdk-rn';

export default function AuthScreen() {
  const webViewRef = useRef<WebView>(null);
  let finvuWrapper: FinvuAuthenticationWebviewWrapper;

  useEffect(() => {
    finvuWrapper = new FinvuAuthenticationWebviewWrapper(
      FinvuAuthEnvironment.DEVELOPMENT
    );
    
    return () => {
      finvuWrapper.cleanupAll();
    };
  }, []);

  const handleMessage = (event) => {
    finvuWrapper.handleMessage(event, webViewRef);
  };

  return (
    <View style={{ flex: 1 }}>
      <WebView
        ref={webViewRef}
        source={{ uri: 'https://your-web-app.com' }}
        onMessage={handleMessage}
        javaScriptEnabled
      />
    </View>
  );
}

Web App Integration

Your web app should send messages like this:

// In your web app
window.ReactNativeWebView.postMessage(JSON.stringify({
  method: 'initAuth',
  initConfig: JSON.stringify({
    requestId: 'your-request-id'
  }),
  callback: 'handleInitAuthResponse'
}));

// Define callback
window.handleInitAuthResponse = function(response) {
  const result = JSON.parse(response);
  console.log('Init result:', result);
  
  if (result.status === 'SUCCESS') {
    // Now call startAuth
    window.ReactNativeWebView.postMessage(JSON.stringify({
      method: 'startAuth',
      snaLink: 'https://80.in.safr.sekuramobile.com/...',
      callback: 'handleStartAuthResponse'
    }));
  }
};

window.handleStartAuthResponse = function(response) {
  const result = JSON.parse(response);
  console.log('Start auth result:', result);
};

API Reference

setup(environment: FinvuAuthEnvironment)

Initialize the SDK with environment configuration.

Parameters:

• environment: FinvuAuthEnvironment.DEVELOPMENT or FinvuAuthEnvironment.PRODUCTION

Returns: void

initAuth(config: Object)

Initialize authentication session.

Parameters:

• config.requestId (string): Request identifier

Returns: Promise<FinvuAuthSuccessResponse | FinvuAuthFailureResponse>

Success Response:

{
  status: "SUCCESS",
  statusCode: string,        // e.g., "200", "OK"
  authType: string | null,   // Authentication method used
  token: string | null,      // Authentication token (may be null for initAuth)
  requestId?: string,        // Request identifier (echo)
  // Additional fields may be present depending on the flow
}

Failure Response:

{
  error: {
    status: "FAILURE",
    errorCode: string,       // Error code (e.g., "INVALID_REQUEST", "AUTH_FAILED")
    errorMessage: string     // Human-readable error description
  }
}

Field Details

initAuth Success Response:

• status: Always "SUCCESS"
• statusCode: HTTP-like status code
• authType: Usually null (not authenticated yet)
• token: Usually null (token comes from startAuth)
• requestId: Your request identifier

startAuth Success Response:

• status: Always "SUCCESS"
• statusCode: HTTP-like status code
• authType: Authentication type used (e.g., "SNA" for Silent Network Auth)
• token: The authentication token/JWT - this is what you need
• snaToken: May contain SNA-specific token

Common Error Codes:

• "INVALID_REQUEST": Missing or invalid parameters
• "NETWORK_ERROR": Network connectivity issue
• "AUTH_FAILED": Authentication failed
• "TIMEOUT": Request timed out
• "UNKNOWN_ERROR": Unexpected error

startAuth(snaLink: string)

Start authentication using Silent Network Authentication link.

Parameters:

• snaLink (string): SNA URL (e.g., https://80.in.safr.sekuramobile.com/...)

Returns: Promise<FinvuAuthSuccessResponse | FinvuAuthFailureResponse>

Response: Same format as initAuth

cleanupAll()

Clean up SDK resources when done.

Returns: void

Environment

enum FinvuAuthEnvironment {
  PRODUCTION = "PRODUCTION",
  DEVELOPMENT = "DEVELOPMENT"
}

Error Handling

All SDK methods return responses in a consistent format. Always check the status field:

const response = await FinvuAuthSdkInstance.startAuth(snaLink);

if (response.status === 'SUCCESS') {
  // Handle success
  console.log('Token:', response.token);
} else {
  // Handle error
  console.error('Error:', response.error.errorMessage);
}

Migration from v1.x

Breaking Changes in v2.0.0

1. Removed verifyOtp method - No longer needed in the new authentication flow
2. Changed startAuth signature - Now accepts snaLink instead of phoneNumber
3. Updated initAuth - Now only requires requestId (removed appId and phoneNumber)

Migration Steps

Before (v1.x):

await FinvuAuthSdkInstance.initAuth({
  requestId: "...",
  appId: "...",  // ❌ Removed
  phoneNumber: "+919876543210"  // ❌ Removed
});

await FinvuAuthSdkInstance.startAuth("+919876543210");  // ❌ Changed

await FinvuAuthSdkInstance.verifyOtp("+919876543210", "123456");  // ❌ Removed

After (v2.x):

await FinvuAuthSdkInstance.initAuth({
  requestId: "..."
  // appId removed ✅
  // phoneNumber removed ✅
});

await FinvuAuthSdkInstance.startAuth(snaLink);  // ✅ Now uses SNA link

// verifyOtp is removed - authentication completes in startAuth ✅

License

MIT

Support

For issues and questions, please file an issue at: https://github.com/Cookiejar-technologies/finvu-auth-sdk-react-native-implementation/issues