react-native-braintree-dropin-turbo/MIGRATION.md

Migration Guide

Migrating from Old Braintree Drop-In Implementation

This guide helps you migrate from the legacy Braintree implementation to the new Turbo Module version.

Key Differences

Architecture

• Old: Bridge-based module
• New: Turbo Module with full New Architecture support

SDK Versions

• iOS: Upgraded to Braintree 6.0, BraintreeDropIn 9.0
• Android: Upgraded to Drop-In 6.16.0, Card 4.45.0

Language

• iOS: Migrated from Objective-C to Swift
• Android: Migrated from Java to Kotlin

Breaking Changes

1. Import Statement

Old:

import RNBraintreeDropIn from 'react-native-braintree-dropin';

New:

import BraintreeDropIn from 'react-native-braintree-dropin-turbo';

2. Method Calls

Old:

RNBraintreeDropIn.show(options)
  .then(result => {
    console.log(result.nonce);
  })
  .catch(error => {
    console.error(error);
  });

New:

try {
  const result = await BraintreeDropIn.show(options);
  console.log(result.nonce);
} catch (error) {
  console.error(error);
}

3. Options Structure

Most options remain the same, but there are some changes:

Old:

{
  clientToken: 'token',
  darkTheme: true,
  merchantIdentifier: 'merchant.id', // iOS
  // ...
}

New (unchanged, but TypeScript-typed):

{
  clientToken: 'token',
  darkTheme: true,
  merchantIdentifier: 'merchant.id',
  // ...
}: DropInOptions

4. Android Setup Changes

Old:

// No special initialization needed

New:

import com.braintreedroptinturbo.RNBraintreeDropInModule

class MainActivity : FragmentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        RNBraintreeDropInModule.initDropInClient(this)
    }
}

Important: MainActivity must now extend FragmentActivity instead of ReactActivity.

5. Package Name Changes

Old (AndroidManifest.xml):

<!-- Old package name -->

New:

package com.braintreedroptinturbo

6. iOS Podspec

Old:

pod 'RNBraintreeDropIn', :path => '../node_modules/react-native-braintree-dropin'

New (auto-linked):

# No manual podspec needed - auto-linked
# Or if manual:
pod 'react-native-braintree-dropin-turbo', :path => '../node_modules/react-native-braintree-dropin-turbo'

Step-by-Step Migration

Step 1: Uninstall Old Package

npm uninstall react-native-braintree-dropin
# or
yarn remove react-native-braintree-dropin

Step 2: Clean iOS Pods

cd ios
rm -rf Pods Podfile.lock
cd ..

Step 3: Install New Package

npm install react-native-braintree-dropin-turbo
# or
yarn add react-native-braintree-dropin-turbo

Step 4: Update iOS

cd ios
pod install
cd ..

Step 5: Update Android MainActivity

Update your MainActivity.kt (or convert from .java to .kt):

import android.os.Bundle
import androidx.fragment.app.FragmentActivity
import com.braintreedroptinturbo.RNBraintreeDropInModule

class MainActivity : FragmentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        RNBraintreeDropInModule.initDropInClient(this)
    }
    
    // If you have other ReactActivity methods, you may need to adjust them
}

Step 6: Update Import Statements

Find and replace in your codebase:

# Find
import RNBraintreeDropIn from 'react-native-braintree-dropin';

# Replace with
import BraintreeDropIn from 'react-native-braintree-dropin-turbo';

Step 7: Update Method Calls

Convert from promise chains to async/await (recommended):

Before:

RNBraintreeDropIn.show(options)
  .then(result => {
    // handle result
  })
  .catch(error => {
    // handle error
  });

After:

try {
  const result = await BraintreeDropIn.show(options);
  // handle result
} catch (error) {
  // handle error
}

Step 8: Add TypeScript Types (Optional but Recommended)

If using TypeScript, add proper typing:

import BraintreeDropIn, { 
  type DropInOptions, 
  type PaymentResult 
} from 'react-native-braintree-dropin-turbo';

const options: DropInOptions = {
  clientToken: 'your-token',
  orderTotal: 10.00,
  // ...
};

const result: PaymentResult = await BraintreeDropIn.show(options);

Step 9: Test Thoroughly

Test all payment flows:

• Credit/Debit cards
• Apple Pay (iOS)
• Google Pay (Android)
• Venmo
• PayPal
• 3D Secure

API Changes

Unchanged Methods

These methods work the same way:

• show(options) - Display Drop-In UI
• fetchMostRecentPaymentMethod(clientToken) - Get last payment method
• tokenizeCard(clientToken, cardInfo) - Tokenize a card

New Methods

• collectDeviceData(clientToken) - Now available as a standalone method

Return Types

The return types are now properly typed with TypeScript:

interface PaymentResult {
  nonce: string;
  type: string;
  description: string;
  isDefault: boolean;
  deviceData: string;
}

Compatibility

React Native Version Support

• Old: React Native 0.60+
• New: React Native 0.68+ (Turbo Modules support)

If you're on an older React Native version, you'll need to upgrade first.

New Architecture

The new package supports both:

• Old Architecture (Bridge)
• New Architecture (Turbo Modules)

Enable New Architecture by setting:

• iOS: ENV['RCT_NEW_ARCH_ENABLED'] = '1' in Podfile
• Android: newArchEnabled=true in gradle.properties

Common Migration Issues

Issue 1: MainActivity Compilation Error

Error: "MainActivity must extend FragmentActivity"

Solution:

// Change from
class MainActivity : ReactActivity()

// To
class MainActivity : FragmentActivity()

Issue 2: Swift Bridging Header

Error: "No such module 'BraintreeDropIn'"

Solution:

1. Clean and rebuild
2. Check Swift version is 5.0+
3. Run pod install again

Issue 3: Android Build Failures

Error: Various Gradle errors

Solution:

cd android
./gradlew clean
cd ..
# Rebuild

Issue 4: Type Errors

Error: TypeScript type mismatches

Solution: Make sure you're importing types:

import type { DropInOptions, PaymentResult } from 'react-native-braintree-dropin-turbo';

Testing After Migration

Create a test checklist:

• Drop-In UI displays correctly
• Card payment works
• Apple Pay works (iOS)
• Google Pay works (Android)
• Venmo works
• PayPal works
• 3D Secure verification works
• Error handling works
• Device data collection works
• Vault manager works (if used)

Rollback Plan

If you need to rollback:

# Uninstall new package
npm uninstall react-native-braintree-dropin-turbo

# Reinstall old package
npm install react-native-braintree-dropin@[old-version]

# Clean iOS
cd ios && rm -rf Pods Podfile.lock && pod install && cd ..

# Revert MainActivity changes
# Rebuild

Benefits of Migration

1. ✅ Performance: Turbo Modules are faster than the old bridge
2. ✅ Latest SDKs: Access to latest Braintree features and security updates
3. ✅ Type Safety: Full TypeScript support
4. ✅ Future-proof: Compatible with React Native's New Architecture
5. ✅ Better Maintenance: Modern codebase with Swift and Kotlin
6. ✅ Improved Error Handling: Better error messages and handling

Getting Help

If you encounter issues during migration:

1. Check this migration guide
2. Review the Installation Guide
3. Check closed issues on GitHub
4. Open a new issue with:
   • Old package version
   • New package version
   • React Native version
   • Complete error messages
   • Migration steps attempted

Timeline Recommendation

• Testing Phase: 1-2 days
• Migration: 2-3 hours
• QA Testing: 1-2 days
• Monitoring: 1 week post-release

Good luck with your migration! 🚀