shopsense-mobile (React Native)

Thin WebView shell for the ShopSense widget.

Cursor: implement this package in one click

Click ⓘ Open integration prompt in Cursor to open Cursor with a pre-filled Agent prompt (official cursor.com/link/prompt deeplink). It includes the full checklist from CURSOR_INTEGRATION_PROMPT.md. If the link does not open the app, paste that file’s contents into Cursor Agent instead.

Goals

• No UI owned by the package: all HTML/JS/CSS is served by your server.
• Package only:
  • Renders a WebView pointing to your server page
  • Passes widget config (zone + optional params) via query params
  • Bridges product selections back to native (callback or default deep link)
  • Keeps the WebView persisted and toggles show/hide based on screen focus

Install

npm i shopsense-mobile

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

• react-native-webview
• expo-router

Usage

1) Wrap your app root once (and provide config)

import { ShopSenseRoot } from "shopsense-mobile";

export default function RootLayout() {
  return (
    <ShopSenseRoot
      widgetProps={{
        // Put these in env / remote config in production:
        baseUrl: YOUR_WIDGET_HOST_ORIGIN,
        apiBase: YOUR_WIDGET_API_BASE,
        zoneId: YOUR_ZONE_ID,
        extraParams: OPTIONAL_PARAMS_OBJECT,
        statusTimeoutMs: 10000,
        onProductSelect: (payload) => {
          // navigate to native product screen
        },
        onDebugMessage: (msg) => {
          // optionally toggle fallback UI
        },
      }}
      webViewTopInset={SAFE_AREA_TOP_PLUS_APP_BAR}
    >
      {/* your app routes */}
    </ShopSenseRoot>
  );
}

2) Render ShopSenseWidget on the screen where it should be active

ShopSenseWidget registers callbacks for the current screen and toggles show/hide based on focus. It inherits config from ShopSenseRoot.

import { ShopSenseWidget } from "shopsense-mobile";
import { View } from "react-native";

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

If you want the widget search input focused immediately on screen open:

<ShopSenseWidget focusSearchOnScreenFocus />

Configuration

ShopSenseRoot takes widgetProps (type: ShopSenseWidgetProps).

Only zoneId is required; everything else depends on your hosting setup.

Do not hardcode environment-specific values in docs; load them from env / remote config.

statusTimeoutMs

Optional. Maximum time (ms) to wait for the widget to report WIDGET_STATUS: succeeded after a WebView load starts.

• default: 10000
• behavior: on timeout, the package emits WIDGET_STATUS with payload.state = "failed" and payload.error.message = "timeout" so your app can conditionally render a fallback UI.

Server contract

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

• Reads query params such as: zone (and any optional parameters you support)
• Loads the ShopSense widget JS/CSS from your server/CDN
• Posts NAVIGATE_TO_PRODUCT to the React Native WebView bridge when a product is tapped:

{ "type": "NAVIGATE_TO_PRODUCT", "payload": { "id": 123, "alias": "slug" } }

Default navigation behavior

If onProductSelect is not provided, the package opens:

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

Your app must register the deep link scheme for this to work.