React Native Integration

This guide covers how to integrate the Hubble SDK into a React Native application using react-native-webview.

1. Setup the WebView

Install the required dependency:

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

For iOS, run pod install after adding the dependency.

2. Initialization

Build the SDK URL with your credentials:

Parameter	Required	Description
clientId	Yes	Client ID provided by the Hubble team
appSecret	Yes	App secret provided by the Hubble team
token	Conditional	SSO token for the current user. Required unless lazy login is enabled.
appVersion	No	App version string. Defaults to "10000".
deviceId	No	Device identifier for analytics.

For React Native, set wrap-plt=rn.

const params = {
  clientId: "id_given_by_hubble",
  appSecret: "secret_given_by_hubble",
  token: "your_sso_token",
  "wrap-plt": "rn",
};

const baseUrl = "https://sdk.dev.myhubble.money/";
// prod: https://sdk.myhubble.money/

const sourceUrl = `${baseUrl}?clientId=${params.clientId}&appSecret=${params.appSecret}&token=${params.token}&wrap-plt=${params["wrap-plt"]}`;

3. Load the WebView

Render the WebView component with the required props:

<WebView
  ref={webViewRef}
  source={{ uri: sourceUrl }}
  javaScriptEnabled={true}
  domStorageEnabled={true}
  startInLoadingState={true}
  setSupportMultipleWindows={true}
  javaScriptCanOpenWindowsAutomatically={true}
  cacheEnabled={false}
  onShouldStartLoadWithRequest={handleNavigation}
  onMessage={handleEvent}
  onNavigationStateChange={(navState) => setCanGoBack(navState.canGoBack)}
/>

4. Handling Navigation

Use onShouldStartLoadWithRequest to control which URLs load in the WebView:

const handleNavigation = (request) => {
  if (request.url.startsWith(baseUrl)
      || request.url.startsWith("https://api.razorpay.com")) {
    return true; // load inside WebView
  } else {
    Linking.openURL(request.url);
    return false; // open externally
  }
};

Back Navigation

Handle the hardware back button on Android:

useEffect(() => {
  const backAction = () => {
    if (canGoBack && webViewRef.current) {
      webViewRef.current.goBack();
      return true;
    }
    return false;
  };
  const handler = BackHandler.addEventListener("hardwareBackPress", backAction);
  return () => handler.remove();
}, [canGoBack]);

5. Handling Events

The SDK communicates with your application by sending events. There are two types:

Action Events

SDK lifecycle and navigation:

Action	When It Fires	What You Should Do
app_ready	SDK has finished loading	Show the WebView / iframe. Hide your loading spinner.
close	User tapped the close or back button in the SDK	Dismiss the WebView / iframe. Navigate the user back.
error	SDK failed to load (invalid credentials, network error, SSO failure)	Hide the WebView. Show a user-friendly error with a retry option.

Always Handle the close Event

The close action is the only way the SDK tells your application that the user wants to leave. If you do not handle it, the user will be stuck inside the SDK with no way to navigate back. This is one of the most common integration issues.

Analytics Events

User interaction tracking:

{ "type": "analytics", "event": "payment_success", "properties": { "amount": 500 } }

Forward analytics events to your analytics provider (Mixpanel, CleverTap, Amplitude, etc.) to track SDK usage.

For a complete list of events, see the Full Events Reference.

Setting Up the Event Handler

Use the onMessage prop to receive events:

const handleEvent = (event) => {
  const data = JSON.parse(event.nativeEvent.data);

  if (data.type === "action") {
    if (data.action === "close") {
      navigation.goBack();
    } else if (data.action === "app_ready") {
      setLoading(false);
    } else if (data.action === "error") {
      setError(true);
    }
  } else if (data.type === "analytics") {
    // Forward to your analytics provider
    analytics.track(data.event, data.properties);
  }
};

6. Payment Configuration

The Hubble SDK supports UPI and credit/debit card payments. Credit/debit card payments are not enabled by default - contact Hubble support to enable them.

UPI on React Native

React Native uses a WebView under the hood, so UPI configuration depends on the target platform:

• iOS: Add the LSApplicationQueriesSchemes to your Info.plist (see the iOS Integration Guide for details).
• Android: Add the <queries> block to your AndroidManifest.xml (see the Android Integration Guide for details).

The onShouldStartLoadWithRequest prop on your WebView must allow UPI scheme URLs to open externally using Linking.openURL().

Best Practices

• Wrap in SafeAreaView: Always wrap the WebView in a SafeAreaView to avoid content being hidden behind the notch or status bar.
• Disable caching: Set cacheEnabled={false} to ensure a fresh session on every load.
• Handle loading state: Use startInLoadingState={true} and the app_ready event to show a smooth loading experience.
• Test on both platforms: React Native WebView behavior can differ between iOS and Android. Test on both.