Lark FinServ React Native SDK

A React Native SDK for integrating Lark FinServ's loan eligibility check functionality into your mobile applications.

🚀 Features

• ✅ Easy Integration - Simple API with minimal setup
• 📱 Cross-Platform - Works on iOS and Android
• 🔒 Secure - Built-in security with API key authentication
• 🎨 Customizable - Theme and branding options
• 📊 Event-driven - Comprehensive event system for tracking
• 🔄 Session Management - Automatic session handling
• 🌐 Multiple Modes - Popup, Inline, and Embedded modes

📦 Installation

npm install larkfinserv-react-native-sdk
# or
yarn add larkfinserv-react-native-sdk

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react-native-webview
# or
yarn add react-native-webview

iOS Setup

For iOS, you need to run pod install:

cd ios && pod install && cd ..

🎯 Quick Start

1. Basic Setup

import React, { useEffect, useState } from 'react';
import { View, Button } from 'react-native';
import { LarkFinServSDK, LarkFinServWebView } from 'larkfinserv-react-native-sdk';

const App = () => {
  const [sdk] = useState(() => new LarkFinServSDK({
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    environment: 'sandbox', // or 'production'
  }));
  
  const [showSDK, setShowSDK] = useState(false);

  useEffect(() => {
    // Initialize SDK
    const initSDK = async () => {
      try {
        await sdk.initialize({
          apiKey: 'your-api-key',
          apiSecret: 'your-api-secret',
          partnerId: 'your-partner-id',
          phoneNumber: '+919876543210', // Optional: Pre-fill phone
        });
      } catch (error) {
        console.error('SDK initialization failed:', error);
      }
    };

    initSDK();
  }, []);

  return (
    <View style={{ flex: 1 }}>
      <Button title="Check Eligibility" onPress={() => setShowSDK(true)} />
      
      {showSDK && (
        <LarkFinServWebView
          sdk={sdk}
          mode="embedded"
          visible={showSDK}
          onClose={() => setShowSDK(false)}
        />
      )}
    </View>
  );
};

export default App;

2. With Event Handlers

import React, { useEffect, useState } from 'react';
import { View, Button, Alert } from 'react-native';
import { 
  LarkFinServSDK, 
  LarkFinServWebView,
  SDKEvent 
} from 'larkfinserv-react-native-sdk';

const App = () => {
  const [sdk] = useState(() => new LarkFinServSDK({
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
  }));
  
  const [showSDK, setShowSDK] = useState(false);

  useEffect(() => {
    // Setup event listeners
    sdk.on('READY', () => {
      console.log('SDK is ready');
    });

    sdk.on('ELIGIBILITY_RESULT', (event: SDKEvent) => {
      console.log('Eligibility Result:', event.data);
      Alert.alert('Success', 'Eligibility check completed!');
      setShowSDK(false);
    });

    sdk.on('ERROR', (event: SDKEvent) => {
      console.error('SDK Error:', event.data?.error);
      Alert.alert('Error', event.data?.error?.message || 'An error occurred');
    });

    sdk.on('CLOSE_FRAME', () => {
      console.log('SDK closed');
      setShowSDK(false);
    });

    // Initialize SDK
    const initSDK = async () => {
      try {
        await sdk.initialize({
          apiKey: 'your-api-key',
          apiSecret: 'your-api-secret',
          partnerId: 'your-partner-id',
        });
      } catch (error) {
        console.error('SDK initialization failed:', error);
      }
    };

    initSDK();

    // Cleanup
    return () => {
      sdk.off('READY');
      sdk.off('ELIGIBILITY_RESULT');
      sdk.off('ERROR');
      sdk.off('CLOSE_FRAME');
    };
  }, []);

  return (
    <View style={{ flex: 1 }}>
      <Button title="Check Eligibility" onPress={() => setShowSDK(true)} />
      
      {showSDK && (
        <LarkFinServWebView
          sdk={sdk}
          mode="embedded"
          visible={showSDK}
          onClose={() => setShowSDK(false)}
        />
      )}
    </View>
  );
};

export default App;

3. Inline Mode (No Modal)

import React, { useEffect, useState } from 'react';
import { View, StyleSheet } from 'react-native';
import { LarkFinServSDK, LarkFinServWebView } from 'larkfinserv-react-native-sdk';

const App = () => {
  const [sdk] = useState(() => new LarkFinServSDK({
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
  }));

  useEffect(() => {
    sdk.initialize({
      apiKey: 'your-api-key',
      apiSecret: 'your-api-secret',
    });
  }, []);

  return (
    <View style={styles.container}>
      <LarkFinServWebView
        sdk={sdk}
        mode="inline"
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

export default App;

4. Popup Mode (External Browser)

import React, { useEffect, useState } from 'react';
import { View, Button } from 'react-native';
import { LarkFinServSDK } from 'larkfinserv-react-native-sdk';

const App = () => {
  const [sdk] = useState(() => new LarkFinServSDK({
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
  }));

  useEffect(() => {
    sdk.initialize({
      apiKey: 'your-api-key',
      apiSecret: 'your-api-secret',
    });
  }, []);

  const handleOpenPopup = async () => {
    try {
      await sdk.openEligibilityCheck('popup');
    } catch (error) {
      console.error('Failed to open eligibility check:', error);
    }
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button title="Open in Browser" onPress={handleOpenPopup} />
    </View>
  );
};

export default App;

📚 API Reference

LarkFinServSDK

Constructor

const sdk = new LarkFinServSDK(config: PartnerConfig);

Methods

initialize(config: PartnerConfig): Promise<void>

Initializes the SDK with partner configuration and retrieves session data.

await sdk.initialize({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  partnerId: 'your-partner-id',
  phoneNumber: '+919876543210', // Optional
  theme: {
    primaryColor: '#16a34a',
    secondaryColor: '#22c55e',
    logoUrl: 'https://your-logo-url.com/logo.png',
  },
});

openEligibilityCheck(mode: SDKMode): Promise<void>

Opens the eligibility check in the specified mode.

// Popup mode (opens in external browser)
await sdk.openEligibilityCheck('popup');

on(event: SDKEventType, handler: EventHandler): void

Registers an event listener.

sdk.on('READY', (event) => {
  console.log('SDK is ready');
});

off(event: SDKEventType): void

Removes an event listener.

sdk.off('READY');

getIframeUrl(): string

Returns the generated URL for the WebView.

const url = sdk.getIframeUrl();

getConfig(): PartnerConfig

Returns the current SDK configuration.

const config = sdk.getConfig();

getSessionInfo(): any

Returns information about the current session.

const sessionInfo = sdk.getSessionInfo();
console.log(sessionInfo);
// {
//   hasSessionId: true,
//   hasUserId: true,
//   sessionId: "...",
//   userId: "..."
// }

handleWebViewMessage(message: string): void

Handles messages from the WebView (used internally by LarkFinServWebView).

// This is called automatically by LarkFinServWebView
sdk.handleWebViewMessage(messageString);

clearSession(): void

Manually clears the current session.

sdk.clearSession();

LarkFinServWebView

React component for rendering the SDK in a WebView.

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | sdk | LarkFinServSDK | Yes | - | The SDK instance | | mode | 'inline' \| 'embedded' | No | 'inline' | Display mode | | visible | boolean | No | true | Controls modal visibility (embedded mode) | | onClose | () => void | No | - | Callback when modal is closed | | containerStyle | StyleProp<ViewStyle> | No | - | Custom styles for container |

🔧 Configuration Options

PartnerConfig

interface PartnerConfig {
  apiKey: string;                    // Required: Your API key
  apiSecret: string;                 // Required: Your API secret
  environment?: 'sandbox' | 'production';  // Optional: Environment
  partnerId?: string;                // Optional: Partner ID
  partnerName?: string;              // Optional: Partner name
  userId?: string;                   // Optional: User ID
  phoneNumber?: string;              // Optional: Pre-fill phone number
  theme?: ThemeConfig;               // Optional: Theme customization
  consentData?: ConsentData;         // Optional: Consent data
}

ThemeConfig

interface ThemeConfig {
  primaryColor?: string;    // Primary color (hex)
  secondaryColor?: string;  // Secondary color (hex)
  fontFamily?: string;      // Font family name
  logoUrl?: string;         // Logo URL
  name?: string;            // Brand name
}

ConsentData

interface ConsentData {
  privacyConsent: boolean;      // Privacy policy consent
  promotionalConsent: boolean;  // Promotional content consent
}

📡 Events

Available Events

| Event Type | Description | Data Structure | |------------|-------------|----------------| | INITIATED | SDK initialization started | {} | | READY | SDK is ready for interaction | {} | | ELIGIBILITY_RESULT | User completed eligibility check | EligibilityResult | | ERROR | An error occurred | { error: SDKError } | | CLOSE | User closed the SDK | {} | | CLOSE_FRAME | SDK frame was closed | {} | | JOURNEY_STEP_COMPLETED | A journey step was completed | { completedStep, nextStep } | | SESSION_CLEARED | Session was cleared | { reason, timestamp } |

Event Data Structures

EligibilityResult

interface EligibilityResult {
  eligible: boolean;
  amount?: number;
  interestRate?: number;
  terms?: string[];
  reasons?: string[];
  mobile?: string;
  partnerId?: string;
  sessionId?: string;
  result?: {
    selectedOffer: any;
  };
}

SDKError

interface SDKError {
  code: string;
  message: string;
}

🎨 Modes

Inline Mode

Renders the SDK directly in your component without a modal.

<LarkFinServWebView sdk={sdk} mode="inline" />

Embedded Mode

Renders the SDK in a full-screen modal.

<LarkFinServWebView
  sdk={sdk}
  mode="embedded"
  visible={showSDK}
  onClose={() => setShowSDK(false)}
/>

Popup Mode

Opens the SDK in the device's external browser.

await sdk.openEligibilityCheck('popup');

🔒 Permissions

iOS

Add the following to your Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

Android

No additional permissions required.

🐛 Troubleshooting

SDK Not Loading

Problem: WebView shows blank screen Solutions:

• Check API credentials are correct
• Verify network connectivity
• Check console for errors
• Ensure SDK is initialized before rendering WebView

Authentication Errors

Problem: API authentication failures Solutions:

• Verify API key and secret are correct
• Check API key permissions
• Ensure proper environment configuration

WebView Not Rendering

Problem: WebView component not displaying Solutions:

• Ensure react-native-webview is installed
• Run pod install for iOS
• Check WebView permissions in AndroidManifest.xml

📱 Platform Support

• ✅ iOS 11.0+
• ✅ Android API level 21+
• ✅ React Native 0.60+

📄 License

MIT

🤝 Support

• Technical Support: [email protected]
• Documentation: https://docs.larkfinserv.in
• Issues: https://github.com/larkfinserv/larkfinserv-react-native-sdk/issues

🚀 Example Project

Check out the example folder for a complete working example.

cd example
npm install
# For iOS
cd ios && pod install && cd ..
npm run ios
# For Android
npm run android

Made with ❤️ by Lark FinServ