@shopsensepro/react-native

Thin React Native / Expo WebView shell for the ShopSense search widget.

Goals

• No UI owned by the package — all HTML/JS/CSS is served by your server.
• The package only:
  • Renders a single persistent WebView pointed at your server page
  • Passes widget config (zone + optional params) via query params
  • Bridges product selections back to native via a callback (or a default deep link)
  • Toggles WebView show/hide based on screen focus — one WebView, zero re-mounts

Install

npm i @shopsensepro/react-native

Peer deps (should already exist in an Expo app):

• react-native-webview
• expo-router

Quick start

1. Wrap your app root with ShopSenseRoot

Place ShopSenseRoot once, inside your SafeAreaProvider and Redux Provider (if you use them), but outside GestureHandlerRootView. This keeps the WebView alive for the lifetime of the app.

// app/_layout.jsx
import { ShopSenseRoot } from "@shopsensepro/react-native";
import { useSafeAreaInsets } from "react-native-safe-area-context";
import { useCallback, useMemo, useState } from "react";
import { router } from "expo-router";

/** Height of your app bar, used so the WebView overlay clears the notch + header. */
const APP_BAR_HEIGHT = 56;

function RootLayout({ children }) {
  const insets = useSafeAreaInsets();

  const webViewTopInset = useMemo(
    () => insets.top + APP_BAR_HEIGHT,
    [insets.top],
  );

  const handleProductSelect = useCallback((product) => {
    // product.productUrl is the canonical URL from your server,
    // e.g. "/products/my-item?id=123"
    const [path, query] = product.productUrl.split("?");
    const alias = path.split("/").pop();
    const id = query ? new URLSearchParams(query).get("id") : null;
    router.push({ pathname: "/product/[alias]", params: { id, alias } });
  }, []);

  const handleDebugMessage = useCallback((msg) => {
    // See "Fallback UI" section below
  }, []);

  const widgetProps = useMemo(
    () => ({
      zoneId: process.env.EXPO_PUBLIC_SHOPSENSE_ZONE_ID,
      statusTimeoutMs: 10000,
      onProductSelect: handleProductSelect,
      onDebugMessage: handleDebugMessage,
    }),
    [handleProductSelect, handleDebugMessage],
  );

  return (
    <ShopSenseRoot widgetProps={widgetProps} webViewTopInset={webViewTopInset}>
      {children}
    </ShopSenseRoot>
  );
}

webViewTopInset

Pixels to offset the WebView overlay from the top of the screen. Set it to safeAreaInsets.top + <your app bar height> so the overlay does not overlap the status bar or notch.

2. Render ShopSenseWidget on your search screen

ShopSenseWidget inherits all config from the nearest ShopSenseRoot. It shows the WebView when the screen is focused and hides it when the screen blurs.

// app/search.jsx
import { ShopSenseWidget } from "@shopsensepro/react-native";
import { View } from "react-native";

export default function SearchScreen() {
  return (
    <View style={{ flex: 1, minHeight: 0 }}>
      <ShopSenseWidget />
    </View>
  );
}

To auto-focus the search input when the screen opens:

<ShopSenseWidget focusSearchOnScreenFocus />

Fallback UI

The package emits status events through onDebugMessage. Use them to conditionally render a native fallback when the widget fails (network error, timeout, server down).

// Recommended pattern — track fallback state at the root,
// share it via context to the search screen.

const [showFallback, setShowFallback] = useState(false);

const handleDebugMessage = useCallback((msg) => {
  if (msg?.type === "WIDGET_STATUS") {
    const state = msg?.payload?.state;
    if (state === "failed") {
      setShowFallback(true);
      return;
    }
    if (state === "succeeded") {
      setShowFallback(false);
      return;
    }
  }
  if (msg?.type === "WEBVIEW_ERROR" || msg?.type === "WEBVIEW_HTTP_ERROR") {
    setShowFallback(true);
  }
}, []);

Then on the search screen:

import { useShopSenseApp } from "@/shopSenseAppContext";
import NativeSearch from "./native-search";

export default function SearchScreen() {
  const { showFallback } = useShopSenseApp();

  if (showFallback) return <NativeSearch />;

  return (
    <View style={{ flex: 1, minHeight: 0 }}>
      <ShopSenseWidget focusSearchOnScreenFocus />
    </View>
  );
}

Debug message types

| msg.type | When fired | | -------------------- | ---------------------------------------------- | | WIDGET_STATUS | Widget loaded successfully or failed/timed out | | WEBVIEW_ERROR | Native WebView onError fired | | WEBVIEW_HTTP_ERROR | Server returned a non-2xx HTTP response |

WIDGET_STATUS payload shape:

{
  state: "succeeded" | "failed";
  error?: { message: string }; // present when state === "failed"
}

Configuration reference

ShopSenseRoot props

| Prop | Type | Required | Description | | ----------------- | ---------------------- | -------- | ---------------------------------------------------------------- | | widgetProps | ShopSenseWidgetProps | ✓ | Config forwarded to the WebView and widget callbacks (see below) | | webViewTopInset | number | | Pixels from top to offset the WebView overlay (default: 0) | | children | ReactNode | ✓ | Your app's route tree |

ShopSenseWidgetProps

| Prop | Type | Required | Description | | ----------------- | ----------------------------------------------- | -------- | --------------------------------------------------------------------------------------- | | zoneId | number \| string | ✓ | ShopSense zone identifier | | baseUrl | string | | Origin of your widget host (e.g. https://search.myapp.com) | | apiBase | string | | Base URL of your ShopSense API | | extraParams | Record<string, string \| number \| undefined> | | Extra query params forwarded to the widget page (e.g. user tier, group id) | | statusTimeoutMs | number | | Max ms to wait for WIDGET_STATUS: succeeded before emitting failure. Default: 10000 | | onProductSelect | (product: ProductPayload) => void | | Called when a product is tapped in the widget. Receives { productUrl }. | | onDebugMessage | (msg: DebugMessage) => void | | Called for all internal events (status, errors, navigation). Use for fallback logic. |

ShopSenseWidget props

| Prop | Type | Default | Description | | -------------------------- | --------- | ------- | --------------------------------------------------------- | | focusSearchOnScreenFocus | boolean | false | Sends a focus command to the widget input on screen focus |

All config is inherited from ShopSenseRoot — no need to repeat it on ShopSenseWidget.

Default navigation behavior

If onProductSelect is not provided, the package opens the following deep link:

app.shopsense://product/:id/:alias

Your app must register this deep link scheme for it to resolve.

Server contract

Your server must host an HTML page (default path: /embed/widget.html) that:

1. Reads query params: zone, plus any extraParams you pass
2. Loads ShopSense widget JS/CSS from your server or CDN
3. Posts a message to the React Native WebView bridge when a product is tapped:

{
  "type": "NAVIGATE_TO_PRODUCT",
  "payload": { "id": 123, "alias": "my-product" }
}

One-click Cursor integration

Click the link below to open Cursor Agent with a pre-filled prompt that writes app/_layout.jsx, app/shopsense-search.jsx, and app/shopSenseAppContext.js for you:

→ Open integration prompt in Cursor

If the link does not open Cursor, paste the contents of CURSOR_INTEGRATION_PROMPT.md directly into Cursor Agent.

License

MIT