react-native-goodflip-bca – Integration Guide

Complete steps to integrate react-native-goodflip-bca (GoodFlip BCA device integration) into a React Native app on React Native, Android, and iOS.

Table of Contents

1. Overview
2. Required Packages
3. React Native Setup
4. Android Integration
5. iOS Integration
6. Usage in Code
7. API Reference
8. Troubleshooting

Overview

react-native-goodflip-bca provides:

• BLE-based connection to GoodFlip BCA (Body Composition Analysis) devices
• User profile (age, gender, height, etc.) for measurements
• Device events: detecting, connecting, connected, data received, timeout
• Vitals algorithms and ranges (BMI, body fat, muscle mass, etc.)
• Bluetooth and location permission handling via react-native-permissions

The library depends on react-native-ble-manager, react-native-device-info, and react-native-permissions. These must be installed and configured in your app.

Getting Started

Core dependencies (must be present in your app):

| Package | Purpose | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | react-native-goodflip-bca | Main integration package for GoodFlip BCA devices. Handles BLE scanning, device connection, data reading, and measurement processing. |

Peer dependencies (must be present in your app):

| Package | Purpose | | -------------------------- | ------------------------------------------- | | react-native-ble-manager | BLE scanning and connection for BCA devices | | react-native-device-info | Location services check (Android) | | react-native-permissions | Bluetooth and location permission requests |

Optional (used in the example app):

• react-native-safe-area-context – for safe area layout when showing full-screen BCA UI

React Native Setup

1. Install dependencies

From your project root:

npm install react-native-goodflip-bca react-native-ble-manager react-native-device-info react-native-permissions
# or
yarn add react-native-goodflip-bca react-native-ble-manager react-native-device-info react-native-permissions

2. Link native code

• Android: React Native autolinking will pick up the library. No extra step if you use autolinking (default in RN 0.60+).
• iOS: Run CocoaPods install (see iOS Integration).

3. Rebuild the app

After adding the package and configuring Android/iOS (permissions, Podfile, etc.):

# Android
npx react-native run-android

# iOS
cd ios && pod install && cd ..
npx react-native run-ios

Android Integration

1. Minimum requirements

• minSdkVersion: 24 (library uses 24)
• compileSdkVersion: 34+ (library uses 34)
• targetSdkVersion: 34+

Your root android/build.gradle or android/app/build.gradle should use at least these where applicable.

2. Permissions

The library’s own AndroidManifest (used when the library is built) declares:

• INTERNET
• ACCESS_COARSE_LOCATION / ACCESS_FINE_LOCATION (SDK 23+)
• BLUETOOTH / BLUETOOTH_ADMIN (maxSdkVersion 30)
• BLUETOOTH_SCAN (Android 12+, with neverForLocation when appropriate)
• BLUETOOTH_CONNECT, BLUETOOTH_ADVERTISE

With React Native autolinking, these are typically merged from the library. If your app’s manifest overrides or you need to guarantee them, ensure your app AndroidManifest.xml (e.g. android/app/src/main/AndroidManifest.xml) includes the same permissions your app needs for BLE and location (e.g. for scanning).

Example (add inside <manifest> if not already present):

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

3. Library dependencies (handled by the library)

The library already depends on:

• AILink BLE SDK: com.github.elinkthings:AILinkSDKRepositoryAndroid:1.14.21
• AILink Parsing: com.github.elinkthings:AILinkSDKParsingLibraryAndroid:1.9.7
• AndroidX, Gson, Material, Glide, etc.

No need to add these in your app’s build.gradle; they come with the library.

4. Build and run

cd android
./gradlew clean
cd ..
npx react-native run-android

iOS Integration

1. Install CocoaPods dependencies

From the project root (not inside ios/):

cd ios
pod install
cd ..

The library’s .podspec pulls in the native module and the vendored AILinkBleSDK.framework.

2. react-native-permissions (Podfile)

The example app’s Podfile uses react-native-permissions and sets up permissions before prepare_react_native_project!:

# At the top of your Podfile (after require)
permissions_setup_path = File.expand_path('../node_modules/react-native-permissions/scripts/setup.rb', __dir__)
require permissions_setup_path

platform :ios, min_ios_version_supported
prepare_react_native_project!

# Configure which permissions your app uses
setup_permissions([
  'Bluetooth',             # Required for BCA device
  'Notifications',
  'LocationWhenInUse',     # Often needed for BLE scanning
])

# Add else condition in linkage
linkage = ENV['USE_FRAMEWORKS']
if linkage != nil
  Pod::UI.puts "Configuring Pod with #{linkage}ally linked Frameworks".green
  use_frameworks! :linkage => linkage.to_sym
else
  use_frameworks! :linkage => :static
end

# Add this line above "use_react_native!" block
use_frameworks! :linkage => :static

#Place this inside you target block
post_install do |installer|
    react_native_post_install(
      installer,
      config[:reactNativePath],
      :mac_catalyst_enabled => false
    )

    # Ensure Firebase modules are treated as modular headers
    installer.pods_project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES'] = 'YES'
        # react-native-goodflip-bca-lib ships AILinkBleSDK.framework built for device only.
        # Exclude arm64 for simulator so the build uses x86_64 and can run on simulator (Intel or Rosetta on M1).
        config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
      end
    end

    # Apply same exclusion to the main app target so simulator build is consistent
    installer.aggregate_targets.each do |aggregate_target|
      aggregate_target.user_project.native_targets.each do |native_target|
        native_target.build_configurations.each do |config|
          config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
        end
      end
    end
  end

Add or keep Bluetooth and LocationWhenInUse (and any others you need) in setup_permissions.

3. Info.plist usage descriptions

Your app must declare usage description strings or iOS will not prompt correctly and may reject the app. In your app’s Info.plist (e.g. ios/YourApp/Info.plist), add:

<key>NSBluetoothPeripheralUsageDescription</key>
<string>We need access to your Bluetooth to connect to GoodFlip BCA devices.</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>We need access to your Bluetooth to connect to GoodFlip BCA devices.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need access to your location to scan for GoodFlip BCA devices.</string>

(You can change the strings to match your app’s wording.)

4. Simulator note (arm64)

The library ships AILinkBleSDK.framework built for device. The example Podfile excludes arm64 for the simulator so the simulator build uses x86_64:

config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'

If your Podfile already does this for the library or the app, no change needed. If you see simulator build errors related to the framework, consider adding this exclusion for the simulator SDK.

5. Build and run

cd ios
pod install
cd ..
npx react-native run-ios

Usage in Code

1. Initialize SDK and listener

Call initializeGoodFlipBcaSDK() once (e.g. in useEffect) and set up the device event listener with initializeGoodFlipBcaEventListener. Remove the listener on unmount with removeGoodFlipBcaEventListener.

2. Start BCA flow with user data

Call initializeGoodFlipBca(userData) with the current user’s profile. The library will handle Bluetooth/location permissions and then start the native BCA flow (on Android it starts the BCA Activity; on iOS it uses the native module).

Example:

import { useEffect } from 'react';
import {
  initializeGoodFlipBcaSDK,
  initializeGoodFlipBca,
  initializeGoodFlipBcaEventListener,
  removeGoodFlipBcaEventListener,
  type EventData,
} from 'react-native-goodflip-bca';

function App() {
  useEffect(() => {
    initializeGoodFlipBcaSDK();
    initializeGoodFlipBcaEventListener((eventData: EventData) => {
      console.log('GoodFlipBCADeviceEvent', eventData);
      if (eventData.status === 'DATA_RECEIVED') {
        // eventData contains vitals (processed by goodFlipBcaVitalsAlgo when applicable)
      }
    });
    return () => {
      removeGoodFlipBcaEventListener();
    };
  }, []);

  const startBCA = () => {
    initializeGoodFlipBca({
      userId: '123',
      dob: '1999-01-01',
      age: 24,
      gender: 1,  // 1 = male, 2 = female (and 0 in some validation paths)
      height: 160, // cm
    });
  };

  return (
    // ... your UI and a button that calls startBCA()
  );
}

• initializeGoodFlipBcaSDK() – initializes the native SDK; call once at app/screen load.
• initializeGoodFlipBcaEventListener(callback) – subscribes to device events; callback receives EventData (and for DATA_RECEIVED, may receive processed vitals).
• removeGoodFlipBcaEventListener() – unsubscribes; call in cleanup.
• initializeGoodFlipBca(userData) – checks permissions and user data, then starts the BCA flow (opens native UI on Android, triggers native flow on iOS).

API Reference

Core functions

| Function | Description | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | initializeGoodFlipBcaSDK() | Initialize the GoodFlip BCA SDK. Returns a Promise. Call once. | | initializeGoodFlipBca(userData: UserData) | Validate user data, handle Bluetooth/location permissions, and start the BCA flow. | | initializeGoodFlipBcaEventListener(callback) | Subscribe to device events (GoodFlipBCADeviceEvent). | | removeGoodFlipBcaEventListener() | Remove the event listener. Call on unmount. | | onPressConnect(userData) | Lower-level: start the native BCA Activity (Android) / flow (iOS) with user data. Usually used internally by initializeGoodFlipBca. |

Permission helpers (from library)

| Function | Description | | ----------------------------------------------------------------- | -------------------------------------------------------------------- | | checkBluetoothPermission() | Check current Bluetooth (and location on Android) permission status. | | requestBluetoothPermission() | Request Bluetooth (and location where needed) permissions. | | managePermission(permission, userData, enableRequestPermission) | Handle permission result and optionally start BCA flow. | | enableBluetooth() | Turn on Bluetooth (Android). | | promptEnableLocation() | Show alert to enable location (Android). |

Data and types

| Export | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------- | | goodFlipBcaVitalsAlgo(eventData) | Process raw event data into vitals (used internally for DATA_RECEIVED). | | Event | Enum: DETECTING, CONNECTING, CONNECTED, DATA_RECEIVED, TIMEOUT, WRONG_SCALE_DETECTED. | | EventData | { data, status: Event, ranges?, userInfo? }. | | UserData | `{ userId: string, dob: string, age: number, height: number, gender: 1 |

Troubleshooting

“The package 'react-native-goodflip-bca' doesn't seem to be linked”

• Run pod install in ios/ and rebuild.
• Clean and rebuild Android: cd android && ./gradlew clean && cd .. then npx react-native run-android.
• Ensure you are not using Expo Go; use a dev build or bare workflow.

Android: permissions not granted or BLE not working

• Confirm all required permissions are in your app’s AndroidManifest.xml (or that the library’s manifest is being merged).
• On Android 12+, ensure BLUETOOTH_SCAN and BLUETOOTH_CONNECT are requested at runtime via react-native-permissions (the library uses these in permission helpers).
• Ensure location is enabled on device if your app uses it for BLE scanning.

iOS: Bluetooth or location permission not asked

• Add the three usage description keys to your app’s Info.plist (see iOS Integration).
• Ensure setup_permissions(['Bluetooth', 'LocationWhenInUse']) is set in the Podfile and run pod install again.

iOS: Simulator build fails (e.g. arm64 / AILinkBleSDK)

• The library’s framework is device-oriented. Exclude arm64 for the simulator in your Podfile’s post_install if needed (see iOS Integration). Prefer testing on a real device for BLE.

Event listener not firing

• Call initializeGoodFlipBcaSDK() before initializeGoodFlipBcaEventListener.
• Call initializeGoodFlipBca(userData) to start the flow; events are sent when the device is detected, connected, and when data is received.

Summary Checklist

React Native

• Install react-native-goodflip-bca, react-native-ble-manager, react-native-device-info, react-native-permissions
• Initialize SDK and event listener in your app; call initializeGoodFlipBca(userData) to start BCA

Android

• minSdk 24+, targetSdk/compileSdk 34+
• Permissions in manifest (or merged from library): Bluetooth, Location
• Rebuild after installing the library

iOS

• Add Bluetooth and LocationWhenInUse in Podfile setup_permissions
• Add NSBluetooth and NSLocationWhenInUseUsageDescription in Info.plist
• Run pod install and rebuild

After completing these steps, you can integrate GoodFlip BCA scanning, connection, and vitals in your React Native app on both Android and iOS.