@lvble/sdk-react-native

React Native SDK that wraps the native Livble iOS and Android SDKs.

• iOS: vendored prebuilt LivbleSDK.xcframework under ios/Frameworks/ (built from livble-ios-sdk SwiftPM package).
• Android: vendored AAR from android_sdk/:sdk (under android/libs/). Consumer apps must add a one-line flatDir block — see Consumer setup (Android).
• Architecture: works with both Old and New Architecture (TurboModules + Fabric interop).
• Expo: works in Expo apps via expo prebuild. Not Expo Go (custom native code).

Install

yarn add @lvble/sdk-react-native       # or: npm install
cd ios && pod install

Usage

import {
  Livble,
  LivbleEnvironment,
  LivbleProductVariant,
  LivbleWidgetView,
  LivbleExperienceView,
  type LivbleTokenProvider,
  type LivbleMessage,
} from '@lvble/sdk-react-native';

const tokenProvider: LivbleTokenProvider = (callback) => {
  fetchTokenFromYourBackend().then(callback);
};

const livble = new Livble({
  tokenProvider,
  environment: LivbleEnvironment.SANDBOX,
  productVariant: LivbleProductVariant.RENT,
  pms: 'demo_pms_partner',
  externalId: 'tenant-123',
  signature: '<HMAC-SHA256 hex of `pms+externalId` keyed by your apiKey>',
  balance: 187500, // cents
});

livble.onMessage((m: LivbleMessage) => console.log(m.eventType, m.data));

// Inline widget — embeds the native WebView in your screen
<LivbleWidgetView livble={livble} style={{ height: 250 }} />

// Open the fullscreen Experience (presents native modal on iOS,
// launches ExperienceActivity on Android)
livble.openExperience(token);

// Or embed the Experience inline instead of fullscreen
<LivbleExperienceView livble={livble} token={token} style={{ flex: 1 }} />

// Lifecycle (Android pauses WebView; iOS is a no-op for now)
livble.pauseTarget(LivbleTarget.WIDGET);
livble.resumeTarget(LivbleTarget.WIDGET);

// Always destroy on screen unmount
livble.destroy();

API

| Symbol | Type | Notes | | --- | --- | --- | | new Livble(config) | class | Creates a native instance. One per screen. | | livble.openExperience(token) | method | Presents native fullscreen Experience. | | livble.onMessage(listener) | method | Subscribe to events emitted by Widget/Experience. | | livble.pauseTarget(target) / resumeTarget(target) | method | LivbleTarget.WIDGET or .EXPERIENCE. | | livble.destroy() | method | Required on unmount. Frees native resources. | | <LivbleWidgetView livble style?> | component | Inline widget. | | <LivbleExperienceView livble token style?> | component | Inline experience. | | LivbleEnvironment | enum | SANDBOX / PRODUCTION. | | LivbleProductVariant | enum | RENT / HOA. | | LivbleTarget | enum | WIDGET / EXPERIENCE. | | LivbleConfig | type | Constructor argument. | | LivbleMessage | type | { eventType: string; data?: unknown }. | | LivbleTokenProvider | type | (callback: (token: string) => void) => void. |

Consumer setup (Android)

The Android side ships as a vendored AAR consumed via flatDir. Gradle's flat-dir resolution doesn't propagate transitively, so the consumer app must declare the same flatDir at root scope. Add this to your app's android/build.gradle (the root one, not app/build.gradle):

allprojects {
  repositories {
    flatDir {
      dirs "${rootProject.projectDir}/../node_modules/@lvble/sdk-react-native/android/libs"
    }
  }
}

Without this snippet you will see Could not find :livble-sdk-0.0.5:. from the consumer app's link step. Gradle will also print one WARNING: Using flatDir should be avoided… — accepted tradeoff for AAR distribution.

Architecture compatibility

| RN config | Result | | --- | --- | | Old Architecture (legacy bridge) | Uses RCT_EXPORT_METHOD + SimpleViewManager directly. | | New Architecture (TurboModules + Fabric) | Codegen specs in src/Native*.ts produce JSI bindings; the wrapper's runtime classes (RCTEventEmitter on iOS, ReactContextBaseJavaModule on Android) are adapted via the New-Arch interop layer. | | Expo bare workflow | Autolinked on pod install / Gradle sync. | | Expo prebuild | Same as bare. | | Expo Go | Not supported — custom native code is never loaded by Expo Go. |

The New-Arch interop layer is enabled by default in RN 0.74+. If the host app explicitly disables it (reactNativeArchitectures = "..." + bridgelessEnabled = true without interop), the wrapper would need dedicated TurboModule subclasses — not provided in v0.1.

Known caveats

• iOS minimum: 15.0 (inherited from native iOS SDK).
• Android minimum: API 24 (inherited from native Android SDK).
• pauseTarget/resumeTarget on iOS: the native iOS SDK is currently a no-op for these (WebKit throttles offscreen WKWebViews automatically). The wrapper still exposes the surface so cross-platform code can call them unconditionally.
• Multi-instance: a single Livble is paired widget+experience. If a screen renders both <LivbleWidgetView> and <LivbleExperienceView> simultaneously, they must share the same livble instance.
• Vendored AAR transitive deps: android/build.gradle redeclares androidx.appcompat and androidx.core-ktx because flat-dir AARs don't carry Maven coordinates.