@billdog.io/react-native 1.0.0-beta.2

package/src/WebViewPaywall.tsx

@@ -0,0 +1,454 @@
+/**
+ * WebViewPaywall — Optional WebView-based paywall component for the
+ * React Native SDK.
+ *
+ * The default React Native paywall path is native (`PaywallView` →
+ * `ComponentRenderer`). This component is the WebView alternative that
+ * loads the same unified renderer bundle iOS / Android / Flutter use,
+ * so paywalls visually match across all platforms at the cost of one
+ * extra `react-native-webview` dependency.
+ *
+ * Android parity reference:
+ *   - `BillDogWebViewPaywall` (Android, billdog-paywalls-webview module)
+ *   - Canonical message protocol:
+ *       packages/paywall-renderer/src/native/messageProtocol.ts
+ *   - postMessage events handled here mirror the protocol's
+ *     OutboundMessageType union: purchase / restore / close / open_url /
+ *     track / state_changed / error / ready.
+ *
+ * Architecture choice: URL-based loading (same as Flutter) rather than
+ * bundled HTML asset. The renderer is served by the `render-paywall`
+ * edge function at `https://api.billdog.io/v1/render-paywall?...`,
+ * and the paywall config is delivered to the renderer via the JS
+ * bridge function `window.loadPaywallData(...)` — same contract as
+ * the Flutter SDK uses (packages/flutter/lib/src/widgets/paywall_view.dart).
+ *
+ * Bundling the HTML as a static asset requires a metro.config.js change
+ * (`assetExts: ['html', ...]` + `metro-html-loader`). URL-based avoids
+ * that and is the simpler MVP. If first-paint latency becomes a problem,
+ * a future revision can switch to local-asset loading.
+ */
+
+import React, { useRef, useEffect, useState, useCallback } from 'react';
+import { View, ActivityIndicator, Text, StyleSheet, Modal } from 'react-native';
+import type { WebViewMessageEvent } from 'react-native-webview';
+import { BillDogConfiguration } from './BillDogConfiguration';
+
+// Lazily resolve the `react-native-webview` module. Importing it at the top
+// level runs its native-module lookup (`TurboModuleRegistry.getEnforcing(
+// 'RNCWebViewModule')`) at SDK-load time, which THROWS an Invariant Violation
+// and crashes the host app when the peer isn't fully linked (e.g. old-arch
+// RN 0.73 quirk) — even for apps using only the NATIVE paywall path. Deferring
+// the require to render time keeps `import '@billdog.io/react-native'` safe.
+let _WebView: any;
+function loadWebView(): any {
+  if (_WebView === undefined) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      _WebView = require('react-native-webview').default ?? null;
+    } catch {
+      _WebView = null;
+    }
+  }
+  return _WebView;
+}
+import { LocalizationResolver } from './LocalizationResolver';
+import { BillDog } from './BillDog';
+
+export interface WebViewPaywallProps {
+  /** Paywall identifier — matches the placement id used elsewhere. */
+  paywallIdentifier: string;
+  /** API key for the BillDog project. */
+  apiKey: string;
+  /** Optional current user id; forwarded to the renderer so it can
+   *  resolve per-user variants / experiments. */
+  customerId?: string;
+  /** Render the WebView inside a fullscreen modal. Default true. */
+  modal?: boolean;
+  /** Visibility (only meaningful when `modal=true`). */
+  visible?: boolean;
+  /**
+   * Explicit locale for the rendered paywall. When omitted the component
+   * resolves the effective locale via `LocalizationResolver.getEffectiveLocale()`
+   * (runtime override > device locale > "en") — matching the Android
+   * `WebViewPaywallActivity.effectiveLocale()` precedence.
+   */
+  locale?: string;
+
+  /** Fires when the renderer reports `ready` over the postMessage bridge. */
+  onReady?: () => void;
+  /** Fires when the consumer should initiate a purchase. The product id
+   *  comes from the renderer's `purchase` message. */
+  onPurchase?: (productIdentifier: string) => void;
+  /** Fires when the user taps Restore. */
+  onRestore?: () => void;
+  /** Fires when the user closes the paywall. */
+  onDismiss?: () => void;
+  /** Fires on `open_url` messages (e.g. terms / privacy links). */
+  onOpenUrl?: (url: string) => void;
+  /** Fires on `track` analytics events. */
+  onTrackEvent?: (eventName: string, properties?: Record<string, unknown>) => void;
+  /** Fires on any error message from the renderer. */
+  onError?: (error: Error) => void;
+  /**
+   * Optional custom action execution handler (Route B).
+   * If provided, the consumer must execute the action and return a promise
+   * resolving with the result or rejecting with an error. If omitted, the
+   * SDK automatically executes it via the server-side Edge function.
+   */
+  onExecuteAction?: (
+    paywallId: string | null,
+    componentId: string,
+    actionType: string,
+    idempotencyKey: string | null,
+  ) => Promise<unknown>;
+}
+
+/**
+ * Mirrors the BilldogMessage shape from
+ * packages/paywall-renderer/src/native/messageProtocol.ts. Kept inline
+ * here so the RN SDK doesn't need a workspace dep on the renderer
+ * package — only the wire shape matters.
+ */
+interface BilldogMessage {
+  protocol: 'billdog';
+  version: number;
+  id: string;
+  timestamp: number;
+  type: string;
+  payload: Record<string, unknown>;
+}
+
+export const WebViewPaywall: React.FC<WebViewPaywallProps> = ({
+  paywallIdentifier,
+  apiKey,
+  customerId,
+  modal = true,
+  visible = true,
+  locale,
+  onReady,
+  onPurchase,
+  onRestore,
+  onDismiss,
+  onOpenUrl,
+  onTrackEvent,
+  onError,
+  onExecuteAction,
+}) => {
+  const webViewRef = useRef<any>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [errorState, setErrorState] = useState<Error | null>(null);
+
+  // Resolve the effective locale once per render-input change. Precedence
+  // mirrors Android `WebViewPaywallActivity.effectiveLocale()`:
+  // explicit prop > runtime override > device locale > "en".
+  const effectiveLocale = React.useMemo(
+    () => locale?.trim() || LocalizationResolver.getEffectiveLocale(),
+    [locale],
+  );
+
+  // Build the renderer URL once per identifier/customer/locale change.
+  // `locale` is seeded as a query param so the renderer resolves the
+  // correct language on first paint (no flash of base-locale text) —
+  // the seed-before-load half of the Android bridge contract.
+  const rendererUrl = React.useMemo(() => {
+    const base = BillDogConfiguration.resolveEndpoint('render-paywall');
+    const params = new URLSearchParams({
+      paywall_identifier: paywallIdentifier,
+      api_key: apiKey,
+    });
+    if (customerId) params.set('customer_id', customerId);
+    if (effectiveLocale) params.set('locale', effectiveLocale);
+    return `${base}?${params.toString()}`;
+  }, [paywallIdentifier, apiKey, customerId, effectiveLocale]);
+
+  // Reset state when the identifier changes (consumer may swap paywalls).
+  useEffect(() => {
+    setIsLoading(true);
+    setErrorState(null);
+  }, [paywallIdentifier]);
+
+  /**
+   * Push `config:locale` into the renderer via a canonical `state_set`
+   * envelope. Mirrors Android `WebViewPaywallActivity.sendLocaleUpdate`
+   * (kt:1103-1120) — the renderer's inbound bridge (`window.billdog.receive`)
+   * routes `state_set` into `GlobalStateStore`, which `useLocalization`
+   * subscribes to. Tolerates both bridge globals (`window.billdog` and the
+   * older `window.paywallBridge`).
+   */
+  const sendLocaleUpdate = useCallback((loc: string) => {
+    if (!webViewRef.current || !loc) return;
+    const envelope = JSON.stringify({
+      version: 1,
+      type: 'state_set',
+      payload: { key: 'config:locale', value: loc },
+    });
+    const js = `(function(){
+      try {
+        if (window.billdog && window.billdog.receive) {
+          window.billdog.receive(${JSON.stringify(envelope)});
+        } else if (window.paywallBridge && window.paywallBridge.setState) {
+          window.paywallBridge.setState('config:locale', ${JSON.stringify(loc)});
+        }
+      } catch (e) {}
+    })(); true;`;
+    webViewRef.current.injectJavaScript(js);
+  }, []);
+
+  const handleMessage = useCallback(
+    (event: WebViewMessageEvent) => {
+      let message: BilldogMessage;
+      try {
+        message = JSON.parse(event.nativeEvent.data) as BilldogMessage;
+      } catch (parseErr) {
+        const err = parseErr instanceof Error ? parseErr : new Error(String(parseErr));
+        onError?.(err);
+        return;
+      }
+
+      // Validate envelope. Older renderer builds (pre-protocol-unification)
+      // may post flat objects without the `protocol` field; tolerate both.
+      const type = message?.type ?? '';
+      const payload = (message?.payload ?? {}) as Record<string, unknown>;
+
+      switch (type) {
+        case 'ready':
+          setIsLoading(false);
+          // Runtime half of the locale bridge: push `config:locale` into
+          // the renderer's GlobalStateStore via a `state_set` envelope so
+          // the active locale is applied even if the renderer ignored the
+          // URL `locale` query param. Mirrors Android
+          // `WebViewPaywallActivity.sendLocaleUpdate` (kt:1103-1120).
+          sendLocaleUpdate(effectiveLocale);
+          onReady?.();
+          break;
+
+        case 'purchase': {
+          const productIdentifier =
+            (payload.productIdentifier as string | undefined) ??
+            (payload.product_id as string | undefined) ??
+            '';
+          if (productIdentifier) onPurchase?.(productIdentifier);
+          break;
+        }
+
+        case 'restore':
+          onRestore?.();
+          break;
+
+        case 'close':
+          onDismiss?.();
+          break;
+
+        case 'open_url': {
+          const url = payload.url as string | undefined;
+          if (url) onOpenUrl?.(url);
+          break;
+        }
+
+        case 'track': {
+          const eventName = payload.eventName as string | undefined;
+          const properties = payload.properties as Record<string, unknown> | undefined;
+          if (eventName) onTrackEvent?.(eventName, properties);
+          break;
+        }
+
+        case 'error': {
+          const msg =
+            (payload.message as string | undefined) ??
+            (payload.error as string | undefined) ??
+            'Unknown renderer error';
+          const err = new Error(msg);
+          setErrorState(err);
+          onError?.(err);
+          break;
+        }
+
+        case 'execute_action': {
+          const paywallId = payload.paywallId as string | undefined;
+          const componentId = payload.componentId as string | undefined;
+          const actionType = payload.actionType as string | undefined;
+          const idempotencyKey = payload.idempotencyKey as string | undefined;
+
+          if (componentId && actionType) {
+            const executePromise = onExecuteAction
+              ? onExecuteAction(paywallId ?? null, componentId, actionType, idempotencyKey ?? null)
+              : BillDog.executeAction(paywallId ?? null, componentId, actionType, idempotencyKey ?? null);
+
+            executePromise
+              .then((result) => {
+                const resultObj = {
+                  actionType,
+                  componentId,
+                  success: true,
+                  data: result,
+                  idempotencyKey: idempotencyKey ?? null,
+                };
+                if (webViewRef.current) {
+                  const js = `window.dispatchEvent(new CustomEvent('billdog:execute_action_result', { detail: ${JSON.stringify(resultObj)} })); true;`;
+                  webViewRef.current.injectJavaScript(js);
+                }
+              })
+              .catch((err: Error) => {
+                const resultObj = {
+                  actionType,
+                  componentId,
+                  success: false,
+                  error: err.message || 'Action execution failed',
+                  idempotencyKey: idempotencyKey ?? null,
+                };
+                if (webViewRef.current) {
+                  const js = `window.dispatchEvent(new CustomEvent('billdog:execute_action_result', { detail: ${JSON.stringify(resultObj)} })); true;`;
+                  webViewRef.current.injectJavaScript(js);
+                }
+              });
+          }
+          break;
+        }
+
+        case 'state_changed':
+          // No-op — exposed for state-driven flows; consumer can hook
+          // via a future onStateChange prop if needed.
+          break;
+
+        default:
+          // Unknown message types are logged for debugging but don't
+          // surface as errors — the protocol may add new types over time.
+          if (__DEV__) {
+            // eslint-disable-next-line no-console
+            console.log('[WebViewPaywall] unknown message type:', type, payload);
+          }
+      }
+    },
+    [
+      effectiveLocale,
+      sendLocaleUpdate,
+      onReady,
+      onPurchase,
+      onRestore,
+      onDismiss,
+      onOpenUrl,
+      onTrackEvent,
+      onError,
+      onExecuteAction,
+    ],
+  );
+
+  /**
+   * Public method for the consumer to push updated state into the
+   * renderer (e.g. after entitlement change). Mirrors the
+   * `paywallBridge.setState(...)` global exposed by the renderer in
+   * native-SDK mode.
+   */
+  const injectState = useCallback((key: string, value: unknown) => {
+    if (!webViewRef.current) return;
+    const js = `window.paywallBridge && window.paywallBridge.setState && window.paywallBridge.setState(${JSON.stringify(key)}, ${JSON.stringify(value)}); true;`;
+    webViewRef.current.injectJavaScript(js);
+  }, []);
+
+  // Surface the method via a forwardRef-style imperative handle could
+  // be added; for the MVP we keep the API prop-only.
+  void injectState;
+
+  const WebViewComponent = loadWebView();
+
+  const content = (
+    <View style={styles.container}>
+      {isLoading && !errorState && (
+        <View style={styles.loadingContainer}>
+          <ActivityIndicator size="large" />
+        </View>
+      )}
+      {errorState && (
+        <View style={styles.errorContainer}>
+          <Text style={styles.errorText}>Failed to load paywall</Text>
+          <Text style={styles.errorDetails}>{errorState.message}</Text>
+        </View>
+      )}
+      {!errorState && !WebViewComponent && (
+        <View style={styles.errorContainer}>
+          <Text style={styles.errorText}>WebView unavailable</Text>
+          <Text style={styles.errorDetails}>
+            react-native-webview is not linked. Use the native paywall path or add the peer dependency.
+          </Text>
+        </View>
+      )}
+      {!errorState && WebViewComponent && (
+        <WebViewComponent
+          ref={webViewRef}
+          source={{ uri: rendererUrl }}
+          onMessage={handleMessage}
+          onError={(syntheticEvent: any) => {
+            const { nativeEvent } = syntheticEvent;
+            const err = new Error(nativeEvent.description ?? 'WebView load error');
+            setErrorState(err);
+            onError?.(err);
+          }}
+          onHttpError={(syntheticEvent: any) => {
+            const { nativeEvent } = syntheticEvent;
+            const err = new Error(`WebView HTTP ${nativeEvent.statusCode}`);
+            setErrorState(err);
+            onError?.(err);
+          }}
+          style={styles.webView}
+          javaScriptEnabled
+          domStorageEnabled
+          scrollEnabled
+          showsVerticalScrollIndicator={false}
+          // The renderer manages its own viewport; don't intercept taps.
+          originWhitelist={['*']}
+        />
+      )}
+    </View>
+  );
+
+  if (modal) {
+    return (
+      <Modal visible={visible} animationType="slide" onRequestClose={() => onDismiss?.()}>
+        {content}
+      </Modal>
+    );
+  }
+  return content;
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#fff',
+  },
+  webView: {
+    flex: 1,
+    backgroundColor: 'transparent',
+  },
+  loadingContainer: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: 'rgba(255, 255, 255, 0.95)',
+    zIndex: 1,
+  },
+  errorContainer: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    padding: 24,
+  },
+  errorText: {
+    fontSize: 18,
+    fontWeight: 'bold',
+    marginBottom: 8,
+    color: '#333',
+  },
+  errorDetails: {
+    fontSize: 13,
+    color: '#666',
+    textAlign: 'center',
+  },
+});
+
+export default WebViewPaywall;