React Native ManiTrust SDK Bridge

A React Native bridge for the ManiTrust SDK, enabling contact management and push notification features in React Native applications for both iOS and Android.

Features

• 📱 Cross-Platform: Native integration with ManiTrust Swift SDK for iOS and Kotlin SDK for Android
• 🔔 Push Notifications: Register and manage devices for push notifications
• 👥 Contact Management: Add and remove contacts from the device's contact list
• 🛡️ Type Safety: Full TypeScript support with comprehensive type definitions
• ✅ Validation: Built-in input validation and error handling
• 🔧 Easy Setup: Simple configuration and initialization

Installation

Prerequisites

• React Native 0.60.0 or higher
• iOS: iOS 14.0 or higher, Xcode 12.0 or higher
• Android: Android SDK 21+ (API Level 21+)
• Node.js 14.0 or higher

Install the Package

npm install react-native-manitrust-sdk-bridge
# or
yarn add react-native-manitrust-sdk-bridge

iOS Setup

1. Install Pods

Navigate to your iOS directory and install the CocoaPods dependencies:

cd ios
pod install

2. Add SPM Dependency

The package automatically references the ManiTrust SDK via Swift Package Manager. Make sure your project can access the SPM repository:

1. Open your project in Xcode
2. Go to File → Add Package Dependencies
3. Add the ManiTrust SDK repository: https://github.com/dkovacs096/ManiTrust_SDK-SPM
4. Select version 1.0.0 or later

3. Configure Permissions

Add the following permissions to your Info.plist:

<key>NSContactsUsageDescription</key>
<string>This app needs access to contacts to manage your contact list.</string>
<key>NSUserNotificationsUsageDescription</key>
<string>This app needs permission to send you push notifications.</string>

4. Enable Push Notifications

In your AppDelegate.swift, add the following code to handle push notifications:

import UserNotifications

// In your AppDelegate class
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Request notification permissions
    UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
        if granted {
            DispatchQueue.main.async {
                application.registerForRemoteNotifications()
            }
        }
    }
    
    return true
}

// Handle device token registration
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
    // Store the token for use with ManiTrust SDK
    UserDefaults.standard.set(token, forKey: "deviceToken")
}

Android Setup

1. Configure settings.gradle

Add the module to your android/settings.gradle:

include ':react-native-manitrust-sdk-bridge'
project(':react-native-manitrust-sdk-bridge').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-manitrust-sdk-bridge/android')

2. Add Dependency

In your android/app/build.gradle:

dependencies {
    // ... other dependencies
    implementation project(':react-native-manitrust-sdk-bridge')
}

3. Register Package

In android/app/src/main/java/com/[your-package]/MainApplication.kt:

import com.manitrust.ManiTrustPackage

class MainApplication : Application(), ReactApplication {
    override val reactHost: ReactHost by lazy {
        getDefaultReactHost(
            context = applicationContext,
            packageList = PackageList(this).packages.apply {
                add(ManiTrustPackage())
            }
        )
    }
}

4. Add Permissions

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
<uses-permission android:name="android.permission.INTERNET" />

For detailed Android integration, see ANDROID_INTEGRATION.md.

Usage

Basic Setup

import ManiTrust from 'react-native-manitrust-sdk-bridge';

// Configure the SDK
const configureSDK = () => {
  try {
    ManiTrust.configureSDK({
      url: 'https://your-manitrust-api.com',
      projectID: 'your-project-id',
      apiKey: 'your-api-key',
      automaticContactPermission: true,
      automaticPushPermission: true
    });
    console.log('ManiTrust SDK configured successfully');
  } catch (error) {
    console.error('Failed to configure ManiTrust SDK:', error);
  }
};

Register Device

import { useEffect, useState } from 'react';
import { Platform } from 'react-native';
import ManiTrust from 'react-native-manitrust-sdk-bridge';

const App = () => {
  const [deviceToken, setDeviceToken] = useState('');

  useEffect(() => {
    // Get device token (implement your token retrieval logic)
    const getDeviceToken = async () => {
      // Your token retrieval implementation
      const token = await getPushNotificationToken();
      setDeviceToken(token);
    };
    
    getDeviceToken();
  }, []);

  const registerDevice = async (phoneNumber: string) => {
    if (Platform.OS !== 'ios') {
      console.warn('ManiTrust SDK is only available on iOS');
      return;
    }

    try {
      const response = await ManiTrust.registeredDevice(deviceToken, phoneNumber);
      console.log('Device registered:', response);
    } catch (error) {
      console.error('Failed to register device:', error);
    }
  };

  return (
    // Your component JSX
  );
};

Setup Contact from Push Notification

import ManiTrust from 'react-native-manitrust-sdk-bridge';

// Handle push notification data
const handlePushNotification = (notificationData: any) => {
  try {
    ManiTrust.setupContact({
      name: notificationData.name,
      lastName: notificationData.lastName,
      phone: notificationData.phone,
      imageUrl: notificationData.imageUrl,
      mark: notificationData.mark,
      status: notificationData.status, // 'add' or 'delete'
      createdAt: notificationData.createdAt
    });
  } catch (error) {
    console.error('Failed to setup contact:', error);
  }
};

Remove Device

const removeDevice = async (phoneNumber: string) => {
  try {
    const response = await ManiTrust.removeDevice(deviceToken, phoneNumber);
    console.log('Device removed:', response);
  } catch (error) {
    console.error('Failed to remove device:', error);
  }
};

API Reference

ManiTrust.configureSDK(config)

Configures the ManiTrust SDK with your project settings.

Parameters:

• config (ManiTrustConfig): Configuration object
  • url (string): The base URL for the ManiTrust API
  • projectID (string): Your project ID from the ManiTrust admin panel
  • apiKey (string): Your API key for authentication
  • automaticContactPermission (boolean): Whether to automatically request contact permissions
  • automaticPushPermission (boolean): Whether to automatically request push notification permissions

Throws: ManiTrustError if configuration is invalid

ManiTrust.registeredDevice(token, phone)

Registers a device for push notifications.

Parameters:

• token (string): Device push notification token
• phone (string): Phone number associated with the device

Returns: Promise<ManiTrustResponse>

Throws: ManiTrustError if registration fails

ManiTrust.removeDevice(token, phone)

Removes a device from push notifications.

Parameters:

• token (string): Device push notification token
• phone (string): Phone number associated with the device

Returns: Promise<ManiTrustResponse>

Throws: ManiTrustError if removal fails

ManiTrust.setupContact(data)

Sets up contact from push notification data.

Parameters:

• data (ContactData): Contact data object
  • name (string, optional): Contact name
  • lastName (string, optional): Contact last name
  • phone (string, optional): Contact phone number
  • imageUrl (string, optional): Contact image URL
  • mark (string, optional): Contact mark/label
  • status ('add' | 'delete', optional): Contact status
  • createdAt (string, optional): Creation timestamp

Throws: ManiTrustError if contact data is invalid

Error Handling

The SDK provides comprehensive error handling with custom error types:

import ManiTrust, { ManiTrustError } from 'react-native-manitrust-sdk-bridge';

try {
  await ManiTrust.registeredDevice(token, phone);
} catch (error) {
  if (error instanceof ManiTrustError) {
    console.error('ManiTrust Error:', error.message);
    console.error('Error Code:', error.code);
    console.error('Error Details:', error.details);
  } else {
    console.error('Unknown Error:', error);
  }
}

Error Codes

• PLATFORM_NOT_SUPPORTED: SDK is only available on iOS
• INVALID_CONFIG: Invalid configuration object
• MISSING_FIELDS: Missing required configuration fields
• INVALID_URL: Invalid URL format
• INVALID_PROJECT_ID: Project ID cannot be empty
• INVALID_API_KEY: API key cannot be empty
• INVALID_BOOLEAN: Boolean field validation failed
• INVALID_TOKEN: Invalid device token
• INVALID_PHONE: Invalid phone number
• INVALID_PHONE_FORMAT: Invalid phone number format
• INVALID_CONTACT_DATA: Invalid contact data
• EMPTY_CONTACT_DATA: Contact data is empty
• INVALID_STATUS: Invalid contact status
• CONFIG_ERROR: Configuration error
• REGISTRATION_ERROR: Device registration error
• REMOVAL_ERROR: Device removal error
• CONTACT_ERROR: Contact setup error

TypeScript Support

The package includes comprehensive TypeScript definitions:

import ManiTrust, { 
  ManiTrustConfig, 
  ManiTrustResponse, 
  ContactData, 
  ManiTrustError 
} from 'react-native-manitrust-sdk-bridge';

Troubleshooting

Common Issues

1. "ManiTrustBridge native module is not available"

   • Ensure you've run pod install in the iOS directory
   • Check that the native module is properly linked
   • Verify your React Native version is 0.60.0 or higher

2. Build errors in Xcode

   • Make sure you've added the ManiTrust SDK via Swift Package Manager
   • Check that your iOS deployment target is 14.0 or higher
   • Verify all required permissions are added to Info.plist

3. Permission denied errors

   • Ensure you've added the required usage descriptions to Info.plist
   • Check that the user has granted the necessary permissions
   • Verify the permission request flow is working correctly

Debug Mode

Enable debug logging by checking the Xcode console for messages prefixed with "ManiTrustBridge:".

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

• Create an issue on GitHub
• Contact: [email protected]

Changelog

1.0.0

• Initial release
• iOS SDK integration
• TypeScript support
• Comprehensive error handling
• Contact management features
• Push notification support