react-native-uxrate 0.2.0

package/.github/workflows/pr-check.yml

@@ -0,0 +1,15 @@
+name: PR Check
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+      - run: npm install

package/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  sync-public:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Checkout public repo
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.repository_owner }}/UXRateSDK
+          token: ${{ secrets.PUBLIC_REPO_TOKEN }}
+          path: public-repo
+
+      - name: Sync docs
+        run: |
+          mkdir -p public-repo/docs/react-native
+          cp docs/public/*.md public-repo/docs/react-native/
+
+      - name: Sync tutorials
+        run: |
+          mkdir -p public-repo/docs/tutorials
+          for f in docs/tutorials/*.md; do
+            cp "$f" "public-repo/docs/tutorials/react-native-$(basename "$f")"
+          done
+
+      - name: Sync example app
+        run: |
+          rm -rf public-repo/examples/react-native
+          mkdir -p public-repo/examples/react-native
+          cp -r example/* public-repo/examples/react-native/
+
+      - name: Commit and push to public repo
+        working-directory: public-repo
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          if git diff --cached --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "sync react-native docs and example from ${{ github.ref_name }}"
+            git push
+          fi

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+## 0.1.0
+
+- Initial release
+- iOS and Android support
+- API: configure, identify, track, setScreen

package/LICENSE

@@ -0,0 +1,4 @@
+Copyright (c) 2024–2026 SVUG Tech. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly prohibited.

package/README.md

@@ -0,0 +1,68 @@
+# react-native-uxrate
+
+React Native module wrapping the native iOS and Android UXRate SDKs. Provides
+a thin JavaScript API that bridges to the platform-specific implementations
+via React Native's NativeModules.
+
+## Architecture
+
+```
+JS (index.js)  -->  NativeModules bridge  -->  iOS SDK (Swift)
+                                           -->  Android SDK (Kotlin)
+```
+
+The React Native layer is intentionally thin. All survey logic, session
+replay, networking, and UI rendering happen inside the native SDKs. This
+module exposes four methods that forward calls across the bridge:
+
+- `configure` -- initialise the SDK with an API key and options
+- `identify` -- associate the current user with a user ID and properties
+- `track` -- record a custom event
+- `setScreen` -- report the currently visible screen name
+
+TypeScript definitions are included in `index.d.ts`.
+
+## Development
+
+```bash
+git clone <repo-url>
+cd react-native-uxrate
+npm install
+```
+
+### Run the example app
+
+```bash
+cd example
+npm install
+npx react-native run-ios   # or run-android
+```
+
+The example app demonstrates configure, identify, screen tracking with React
+Navigation, and custom event tracking. See `example/App.tsx`.
+
+### Run tests
+
+```bash
+npm test
+```
+
+## Documentation
+
+- [Installation](docs/public/installation.md)
+- [Quick Start](docs/public/quick-start.md)
+- [Event Tracking](docs/public/event-tracking.md)
+- [Session Replay Configuration](docs/public/replay-config.md)
+- [API Reference](docs/public/api-reference.md)
+- [React Navigation Integration](docs/tutorials/react-navigation-integration.md)
+
+## Release
+
+1. Bump version in `package.json`.
+2. Push a version tag (e.g. `0.2.0`).
+3. CI publishes the package to npm and syncs documentation, tutorials, and the
+   example app to the public repository.
+
+## License
+
+Proprietary -- SVUG Tech

package/android/build.gradle

@@ -0,0 +1,43 @@
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.3'
+        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace 'com.uxrate.reactnative'
+    compileSdk 35
+
+    defaultConfig {
+        minSdk 24
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+    maven { url 'https://svug-tech.github.io/UXRateSDK' }
+}
+
+dependencies {
+    implementation 'com.facebook.react:react-native:+'
+    implementation 'com.uxrate:uxrate-sdk:[0.1.0, 0.2.0)'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.uxrate.reactnative">
+</manifest>

package/android/src/main/java/com/uxrate/reactnative/UXRateModule.kt

@@ -0,0 +1,105 @@
+package com.uxrate.reactnative
+
+import android.app.Application
+import com.facebook.react.bridge.*
+import com.uxrate.sdk.UXRate
+import com.uxrate.sdk.models.OverlapStrategy
+import com.uxrate.sdk.models.SDKTheme
+
+/**
+ * React Native native module for the UXRate Android SDK.
+ *
+ * Exposes the same 4 methods as the iOS module:
+ * - configure(apiKey, options)
+ * - identify(userId, properties)
+ * - track(event)
+ * - setScreen(name)
+ */
+class UXRateModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String = "UXRate"
+
+    @ReactMethod
+    fun configure(apiKey: String, options: ReadableMap, promise: Promise) {
+        try {
+            val application = reactApplicationContext.applicationContext as? Application
+            if (application == null) {
+                promise.reject("NO_APP", "Could not get Application instance")
+                return
+            }
+
+            val autoTrack = if (options.hasKey("autoTrackScreens")) {
+                options.getBoolean("autoTrackScreens")
+            } else false
+
+            val useMock = if (options.hasKey("useMockService")) {
+                options.getBoolean("useMockService")
+            } else false
+
+            val strategy = if (options.hasKey("overlapStrategy")) {
+                OverlapStrategy.from(options.getString("overlapStrategy"))
+            } else OverlapStrategy.SHOW_FIRST
+
+            val theme = if (options.hasKey("theme")) {
+                SDKTheme.from(options.getString("theme"))
+            } else SDKTheme.AUTO
+
+            UiThreadUtil.runOnUiThread {
+                UXRate.configure(
+                    application = application,
+                    apiKey = apiKey,
+                    autoTrackScreens = autoTrack,
+                    useMockService = useMock,
+                    overlapStrategy = strategy,
+                    theme = theme
+                )
+                promise.resolve(null)
+            }
+        } catch (e: Exception) {
+            promise.reject("CONFIGURE_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    fun identify(userId: String, properties: ReadableMap, promise: Promise) {
+        try {
+            val props = mutableMapOf<String, String>()
+            val iterator = properties.keySetIterator()
+            while (iterator.hasNextKey()) {
+                val key = iterator.nextKey()
+                props[key] = properties.getString(key) ?: ""
+            }
+
+            UiThreadUtil.runOnUiThread {
+                UXRate.identify(userId, props)
+                promise.resolve(null)
+            }
+        } catch (e: Exception) {
+            promise.reject("IDENTIFY_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    fun track(event: String, promise: Promise) {
+        try {
+            UiThreadUtil.runOnUiThread {
+                UXRate.track(event)
+                promise.resolve(null)
+            }
+        } catch (e: Exception) {
+            promise.reject("TRACK_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    fun setScreen(name: String, promise: Promise) {
+        try {
+            UiThreadUtil.runOnUiThread {
+                UXRate.setScreen(name)
+                promise.resolve(null)
+            }
+        } catch (e: Exception) {
+            promise.reject("SET_SCREEN_ERROR", e.message, e)
+        }
+    }
+}

package/android/src/main/java/com/uxrate/reactnative/UXRatePackage.kt

@@ -0,0 +1,26 @@
+package com.uxrate.reactnative
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+/**
+ * React Native package that registers the UXRate native module.
+ *
+ * Add this to your MainApplication's getPackages():
+ * ```kotlin
+ * override fun getPackages(): List<ReactPackage> = PackageList(this).packages.apply {
+ *     add(UXRatePackage())
+ * }
+ * ```
+ */
+class UXRatePackage : ReactPackage {
+    override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
+        return listOf(UXRateModule(reactContext))
+    }
+
+    override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+        return emptyList()
+    }
+}

package/docs/public/api-reference.md

@@ -0,0 +1,78 @@
+# API Reference
+
+All methods are available on the `UXRate` export:
+
+```tsx
+import { UXRate } from 'react-native-uxrate';
+```
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `configure(options)` | Initialise the SDK. Call once at app startup. |
+| `identify(options)` | Identify the current user for survey targeting. |
+| `track(options)` | Record a custom event. |
+| `setScreen(name)` | Report the current screen name. |
+
+All methods return `Promise<void>`.
+
+---
+
+### `configure(options: ConfigureOptions): Promise<void>`
+
+```ts
+interface ConfigureOptions {
+  apiKey: string;
+  autoTrackScreens?: boolean; // default: false
+  useMockService?: boolean;   // default: false
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `apiKey` | `string` | Yes | Your UXRate API key. |
+| `autoTrackScreens` | `boolean` | No | Enable native auto screen tracking. In React Native apps manual `setScreen` calls are preferred. |
+| `useMockService` | `boolean` | No | Use the built-in mock backend for local testing. |
+
+---
+
+### `identify(options: IdentifyOptions): Promise<void>`
+
+```ts
+interface IdentifyOptions {
+  userId: string;
+  properties?: Record<string, string>;
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `userId` | `string` | Yes | A stable user identifier. |
+| `properties` | `Record<string, string>` | No | Key-value properties for segment targeting. |
+
+---
+
+### `track(options: TrackOptions): Promise<void>`
+
+```ts
+interface TrackOptions {
+  event: string;
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `event` | `string` | Yes | The event name to record. |
+
+---
+
+### `setScreen(name: string): Promise<void>`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | `string` | Yes | The screen name to report. |
+
+## TypeScript
+
+Full type definitions are shipped with the package in `index.d.ts`.

package/docs/public/event-tracking.md

@@ -0,0 +1,60 @@
+# Event Tracking
+
+## Custom events
+
+Use `UXRate.track` to record events that can trigger surveys:
+
+```tsx
+UXRate.track({ event: 'purchase_complete' });
+UXRate.track({ event: 'onboarding_finished' });
+```
+
+Event names are arbitrary strings. Define matching trigger rules in the UXRate
+dashboard to show a survey when a specific event fires.
+
+## Screen tracking
+
+React Native apps run inside a single native ViewController (iOS) or Activity
+(Android), so the native auto-track feature sees only one screen. You should
+report screens manually using `setScreen`.
+
+### Per-screen tracking with `useFocusEffect`
+
+```tsx
+import { useFocusEffect } from '@react-navigation/native';
+import { UXRate } from 'react-native-uxrate';
+
+function SettingsScreen() {
+  useFocusEffect(() => {
+    UXRate.setScreen('Settings');
+  });
+
+  return <View>...</View>;
+}
+```
+
+### Global tracking with React Navigation
+
+You can report every navigation change from a single place:
+
+```tsx
+import { NavigationContainer } from '@react-navigation/native';
+
+<NavigationContainer
+  onStateChange={(state) => {
+    const route = state?.routes[state.index];
+    if (route) UXRate.setScreen(route.name);
+  }}
+>
+  {/* screens */}
+</NavigationContainer>
+```
+
+See the [React Navigation integration tutorial](../tutorials/react-navigation-integration.md) for a full walkthrough.
+
+## Best practices
+
+- Keep event names short and consistent (e.g. `snake_case`).
+- Report screens as early as possible so survey targeting is accurate.
+- Avoid tracking high-frequency events (e.g. scroll positions) -- they add
+  noise without improving targeting.

package/docs/public/installation.md

@@ -0,0 +1,48 @@
+# Installation
+
+## Requirements
+
+- React Native 0.70+
+- iOS 17.0+ / Android API 24+
+
+## Install the package
+
+```bash
+npm install react-native-uxrate
+# or
+yarn add react-native-uxrate
+```
+
+## iOS Setup
+
+Install the CocoaPods dependency:
+
+```bash
+cd ios && pod install
+```
+
+The UXRate iOS SDK is pulled automatically via the podspec.
+
+## Android Setup
+
+Add the UXRate Maven repository to your project-level `android/build.gradle`:
+
+```groovy
+allprojects {
+    repositories {
+        maven { url 'https://svug-tech.github.io/UXRateSDK' }
+    }
+}
+```
+
+The module auto-links -- no additional native setup is needed.
+
+## Verify
+
+Run your app on a device or simulator to confirm the module loads without errors:
+
+```bash
+npx react-native run-ios
+# or
+npx react-native run-android
+```

package/docs/public/quick-start.md

@@ -0,0 +1,52 @@
+# Quick Start
+
+Get UXRate running in your React Native app in four steps.
+
+## 1. Configure the SDK
+
+Call `configure` once at app startup, typically in your root `App.tsx`:
+
+```tsx
+import { UXRate } from 'react-native-uxrate';
+
+useEffect(() => {
+  UXRate.configure({ apiKey: 'YOUR_API_KEY' });
+}, []);
+```
+
+## 2. Identify the user
+
+After your user signs in, call `identify` so surveys can be targeted:
+
+```tsx
+UXRate.identify({
+  userId: 'user-42',
+  properties: { plan: 'pro', company: 'Acme' },
+});
+```
+
+## 3. Track events
+
+Fire custom events that can trigger surveys:
+
+```tsx
+UXRate.track({ event: 'checkout_complete' });
+```
+
+## 4. Report screen names
+
+React Native runs inside a single native view controller / activity, so
+automatic screen tracking will not distinguish between JS routes. Use
+`setScreen` on each navigation change:
+
+```tsx
+<NavigationContainer
+  onStateChange={(state) => {
+    const route = state?.routes[state.index];
+    if (route) UXRate.setScreen(route.name);
+  }}
+>
+```
+
+That's it -- surveys configured in the UXRate dashboard will now appear to
+your users based on events, screens, and segments you define.

package/docs/public/replay-config.md

@@ -0,0 +1,33 @@
+# Session Replay Configuration
+
+## Overview
+
+Session replay is handled entirely by the native UXRate SDKs (iOS and Android).
+The React Native module does not expose separate replay APIs -- replay capture
+is started automatically by the native SDK when it is enabled for your project.
+
+## Enabling replay
+
+1. Open the UXRate dashboard.
+2. Navigate to your project settings.
+3. Toggle **Session Replay** on.
+4. Configure the desired sampling rate and privacy masking options.
+
+Once enabled on the dashboard the native SDKs begin capturing replay data
+without any additional code changes in your React Native app.
+
+## Privacy masking
+
+Sensitive views can be masked from replays. Masking rules are configured in
+the UXRate dashboard and applied at the native layer. Because React Native
+renders through native view hierarchies, the standard masking rules apply
+to RN-rendered content as well.
+
+## Troubleshooting
+
+- **Replay not appearing**: Make sure the native SDK versions match the
+  minimum required for replay support (check the native SDK changelogs).
+- **Missing frames**: Replay capture runs at a reduced frame rate to minimise
+  performance impact. Short interactions may not produce visible frames.
+- **Large payload warnings**: If your app has complex view hierarchies,
+  consider increasing the masking scope to reduce payload size.

package/docs/tutorials/react-navigation-integration.md

@@ -0,0 +1,132 @@
+# React Navigation Integration
+
+This tutorial walks through integrating UXRate screen tracking with React
+Navigation in a React Native app.
+
+## Prerequisites
+
+- `react-native-uxrate` installed and linked (see [Installation](../public/installation.md))
+- `@react-navigation/native` and a navigator (e.g. `@react-navigation/native-stack`) installed
+
+## Step 1 -- Configure UXRate
+
+In your root component, initialise the SDK:
+
+```tsx
+import React, { useEffect } from 'react';
+import { UXRate } from 'react-native-uxrate';
+
+function App() {
+  useEffect(() => {
+    UXRate.configure({ apiKey: 'YOUR_API_KEY' });
+  }, []);
+
+  return (
+    // ...
+  );
+}
+```
+
+## Step 2 -- Add global screen tracking
+
+Use the `onStateChange` callback on `NavigationContainer` to report every
+route change:
+
+```tsx
+import { NavigationContainer } from '@react-navigation/native';
+
+function App() {
+  // ... configure (Step 1)
+
+  return (
+    <NavigationContainer
+      onStateChange={(state) => {
+        const route = state?.routes[state.index];
+        if (route) {
+          UXRate.setScreen(route.name);
+        }
+      }}
+    >
+      <Stack.Navigator>
+        <Stack.Screen name="Home" component={HomeScreen} />
+        <Stack.Screen name="Profile" component={ProfileScreen} />
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+```
+
+This reports the top-level route name on every navigation event.
+
+## Step 3 -- Track the initial screen
+
+`onStateChange` does not fire for the initial route. To capture it, use a
+navigation ref:
+
+```tsx
+import { useRef } from 'react';
+import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
+
+function App() {
+  const navigationRef = useNavigationContainerRef();
+
+  return (
+    <NavigationContainer
+      ref={navigationRef}
+      onReady={() => {
+        const route = navigationRef.getCurrentRoute();
+        if (route) UXRate.setScreen(route.name);
+      }}
+      onStateChange={(state) => {
+        const route = state?.routes[state.index];
+        if (route) UXRate.setScreen(route.name);
+      }}
+    >
+      {/* screens */}
+    </NavigationContainer>
+  );
+}
+```
+
+## Step 4 -- Fire custom events
+
+Add event tracking to buttons or other interactions:
+
+```tsx
+import { Button } from 'react-native';
+import { UXRate } from 'react-native-uxrate';
+
+function HomeScreen() {
+  return (
+    <Button
+      title="Complete Onboarding"
+      onPress={() => UXRate.track({ event: 'onboarding_complete' })}
+    />
+  );
+}
+```
+
+## Step 5 -- Per-screen tracking (optional)
+
+If you need per-screen side effects (analytics, etc.) you can also use
+`useFocusEffect`:
+
+```tsx
+import { useFocusEffect } from '@react-navigation/native';
+import { UXRate } from 'react-native-uxrate';
+
+function ProfileScreen() {
+  useFocusEffect(() => {
+    UXRate.setScreen('Profile');
+  });
+
+  return (/* ... */);
+}
+```
+
+## Summary
+
+- Use `onStateChange` + `onReady` on `NavigationContainer` for global
+  screen tracking.
+- Use `UXRate.track` to fire custom events from any component.
+- Optionally use `useFocusEffect` for per-screen logic.

package/example/App.tsx

@@ -0,0 +1,79 @@
+import React, { useEffect } from 'react';
+import { View, Text, Button, StyleSheet } from 'react-native';
+import { NavigationContainer } from '@react-navigation/native';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+import { UXRate } from 'react-native-uxrate';
+
+const Stack = createNativeStackNavigator();
+
+// ------------------------------------------------------------------
+// Configure the UXRate SDK at app startup.
+// Replace YOUR_API_KEY with your real key from the UXRate dashboard.
+// For the dev environment use: https://app-dev.uxrate.com
+// ------------------------------------------------------------------
+function App(): React.JSX.Element {
+  useEffect(() => {
+    UXRate.configure({
+      apiKey: 'YOUR_API_KEY',
+      useMockService: true, // set false in production
+    });
+
+    UXRate.identify({
+      userId: 'demo-user-1',
+      properties: { plan: 'trial' },
+    });
+  }, []);
+
+  return (
+    <NavigationContainer
+      onStateChange={(state) => {
+        const route = state?.routes[state.index];
+        if (route) {
+          UXRate.setScreen(route.name);
+        }
+      }}
+    >
+      <Stack.Navigator initialRouteName="Home">
+        <Stack.Screen name="Home" component={HomeScreen} />
+        <Stack.Screen name="Products" component={ProductsScreen} />
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+
+function HomeScreen({ navigation }: any): React.JSX.Element {
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Home Screen</Text>
+      <Button
+        title="Go to Products"
+        onPress={() => navigation.navigate('Products')}
+      />
+      <View style={styles.spacer} />
+      <Button
+        title="Track Button Tap"
+        onPress={() => UXRate.track({ event: 'button_tapped' })}
+      />
+    </View>
+  );
+}
+
+function ProductsScreen(): React.JSX.Element {
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Products Screen</Text>
+      <Button
+        title="Track Button Tap"
+        onPress={() => UXRate.track({ event: 'button_tapped' })}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, alignItems: 'center', justifyContent: 'center' },
+  title: { fontSize: 24, marginBottom: 20 },
+  spacer: { height: 12 },
+});
+
+export default App;

package/example/metro.config.js

@@ -0,0 +1,15 @@
+const path = require('path');
+const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
+
+const root = path.resolve(__dirname, '..');
+
+const config = {
+  watchFolders: [root],
+  resolver: {
+    extraNodeModules: {
+      'react-native-uxrate': root,
+    },
+  },
+};
+
+module.exports = mergeConfig(getDefaultConfig(__dirname), config);

package/example/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "react-native-uxrate-example",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "start": "react-native start",
+    "android": "react-native run-android",
+    "ios": "react-native run-ios"
+  },
+  "dependencies": {
+    "@react-navigation/native": "^6.1.0",
+    "@react-navigation/native-stack": "^6.9.0",
+    "react": "18.2.0",
+    "react-native": "0.73.0",
+    "react-native-safe-area-context": "^4.8.0",
+    "react-native-screens": "^3.29.0",
+    "react-native-uxrate": "file:.."
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "typescript": "^5.3.0"
+  }
+}

package/index.d.ts

@@ -0,0 +1,21 @@
+export interface ConfigureOptions {
+  apiKey: string;
+  autoTrackScreens?: boolean;
+  useMockService?: boolean;
+}
+
+export interface IdentifyOptions {
+  userId: string;
+  properties?: Record<string, string>;
+}
+
+export interface TrackOptions {
+  event: string;
+}
+
+export declare const UXRate: {
+  configure(options: ConfigureOptions): Promise<void>;
+  identify(options: IdentifyOptions): Promise<void>;
+  track(options: TrackOptions): Promise<void>;
+  setScreen(name: string): Promise<void>;
+};

package/index.js

@@ -0,0 +1,92 @@
+import { NativeModules, Platform } from 'react-native';
+
+const LINKING_ERROR =
+  `The package 'react-native-uxrate' doesn't seem to be linked. Make sure to ` +
+  (Platform.OS === 'ios'
+    ? `run \`pod install\` in your iOS project directory.\n`
+    : `rebuild your Android project.\n`);
+
+// Throw a helpful error if the native module is not linked
+const NativeUXRate = NativeModules.UXRate
+  ? NativeModules.UXRate
+  : new Proxy(
+      {},
+      {
+        get() {
+          throw new Error(LINKING_ERROR);
+        },
+      }
+    );
+
+/**
+ * React Native bridge for the UXRate SDK (iOS & Android).
+ *
+ * @example
+ * // Minimal setup (App.js / App.tsx)
+ * import { UXRate } from 'react-native-uxrate';
+ *
+ * useEffect(() => {
+ *   UXRate.configure({ apiKey: 'uxr_xxx' });
+ * }, []);
+ *
+ * @example
+ * // Manual screen tracking
+ * useFocusEffect(() => {
+ *   UXRate.setScreen('Home');
+ * });
+ */
+export const UXRate = {
+  /**
+   * Initialise the UXRate SDK. Call once at app startup.
+   *
+   * @param {string} apiKey - Your UXRate API key (required).
+   * @param {boolean} [autoTrackScreens=false] - Auto-detect screens via
+   *   UIViewController swizzle (iOS) or ActivityLifecycleCallbacks (Android).
+   *   In React Native, manual setScreen() calls are preferred.
+   * @param {boolean} [useMockService=false] - Use the built-in mock backend.
+   */
+  configure({ apiKey, autoTrackScreens = false, useMockService = false }) {
+    if (Platform.OS !== 'ios' && Platform.OS !== 'android') return Promise.resolve();
+    return NativeUXRate.configure(apiKey, { autoTrackScreens, useMockService });
+  },
+
+  /**
+   * Identify the current user for segment-based survey targeting.
+   *
+   * @param {string} userId - A stable user identifier.
+   * @param {Object} [properties={}] - Optional key/value properties.
+   */
+  identify({ userId, properties = {} }) {
+    if (Platform.OS !== 'ios' && Platform.OS !== 'android') return Promise.resolve();
+    return NativeUXRate.identify(userId, properties);
+  },
+
+  /**
+   * Track a custom event. Used for event-based trigger rules.
+   *
+   * @param {string} event - The event name.
+   */
+  track({ event }) {
+    if (Platform.OS !== 'ios' && Platform.OS !== 'android') return Promise.resolve();
+    return NativeUXRate.track(event);
+  },
+
+  /**
+   * Report the current screen name. Call this on every navigation event.
+   *
+   * @param {string} name - The screen name to report.
+   *
+   * @example
+   * // With React Navigation
+   * <NavigationContainer
+   *   onStateChange={(state) => {
+   *     const route = state?.routes[state.index];
+   *     if (route) UXRate.setScreen(route.name);
+   *   }}
+   * >
+   */
+  setScreen(name) {
+    if (Platform.OS !== 'ios' && Platform.OS !== 'android') return Promise.resolve();
+    return NativeUXRate.setScreen(name);
+  },
+};

package/ios/UXRateModule.m

@@ -0,0 +1,32 @@
+#import <React/RCTBridgeModule.h>
+
+// Registers UXRateModule.swift with React Native's Objective-C bridge.
+// Each RCT_EXTERN_METHOD must match an @objc method in UXRateModule.swift.
+
+RCT_EXTERN_MODULE(UXRate, NSObject)
+
+RCT_EXTERN_METHOD(
+  configure:(NSString *)apiKey
+  options:(NSDictionary *)options
+  resolve:(RCTPromiseResolveBlock)resolve
+  reject:(RCTPromiseRejectBlock)reject
+)
+
+RCT_EXTERN_METHOD(
+  identify:(NSString *)userId
+  properties:(NSDictionary *)properties
+  resolve:(RCTPromiseResolveBlock)resolve
+  reject:(RCTPromiseRejectBlock)reject
+)
+
+RCT_EXTERN_METHOD(
+  track:(NSString *)event
+  resolve:(RCTPromiseResolveBlock)resolve
+  reject:(RCTPromiseRejectBlock)reject
+)
+
+RCT_EXTERN_METHOD(
+  setScreen:(NSString *)name
+  resolve:(RCTPromiseResolveBlock)resolve
+  reject:(RCTPromiseRejectBlock)reject
+)

package/ios/UXRateModule.swift

@@ -0,0 +1,91 @@
+import Foundation
+import UXRateSDK
+
+/// React Native bridge module that exposes the UXRate iOS SDK to JavaScript.
+///
+/// Registered as `UXRate` via `RCT_EXTERN_MODULE` in `UXRateModule.m`.
+/// All methods dispatch to `MainActor` since `UXRate` is `@MainActor`-isolated.
+@objc(UXRate)
+class UXRateModule: NSObject {
+
+    /// Initialise the UXRate SDK.
+    ///
+    /// - Parameters:
+    ///   - apiKey: Your UXRate API key.
+    ///   - options: Dictionary with optional keys:
+    ///     - `autoTrackScreens` (Bool, default false)
+    ///     - `useMockService` (Bool, default false)
+    @objc
+    func configure(
+        _ apiKey: String,
+        options: NSDictionary,
+        resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        let autoTrack = options["autoTrackScreens"] as? Bool ?? false
+        let useMock   = options["useMockService"]   as? Bool ?? false
+        let strategy  = OverlapStrategy.from(string: options["overlapStrategy"] as? String)
+        let theme     = SDKTheme.from(string: options["theme"] as? String)
+
+        DispatchQueue.main.async {
+            UXRate.configure(
+                apiKey: apiKey,
+                autoTrackScreens: autoTrack,
+                useMockService: useMock,
+                overlapStrategy: strategy,
+                theme: theme
+            )
+            resolve(nil)
+        }
+    }
+
+    /// Identify the current user.
+    ///
+    /// - Parameters:
+    ///   - userId: Stable user identifier.
+    ///   - properties: Optional `[String: String]` attributes.
+    @objc
+    func identify(
+        _ userId: String,
+        properties: NSDictionary,
+        resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        let props = properties as? [String: String] ?? [:]
+        DispatchQueue.main.async {
+            UXRate.identify(userId: userId, properties: props)
+            resolve(nil)
+        }
+    }
+
+    /// Track a custom event.
+    @objc
+    func track(
+        _ event: String,
+        resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        DispatchQueue.main.async {
+            UXRate.track(event: event)
+            resolve(nil)
+        }
+    }
+
+    /// Report the current screen name.
+    @objc
+    func setScreen(
+        _ name: String,
+        resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
+    ) {
+        DispatchQueue.main.async {
+            UXRate.setScreen(name)
+            resolve(nil)
+        }
+    }
+
+    /// React Native requires this to declare that the module does not have
+    /// a main queue setup requirement — methods are dispatched manually.
+    @objc
+    static func requiresMainQueueSetup() -> Bool { false }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "react-native-uxrate",
+  "version": "0.2.0",
+  "description": "React Native module for the UXRate SDK — embed AI-powered surveys in your React Native app. Supports iOS and Android.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SVUG-Tech/react-native-uxrate"
+  },
+  "keywords": ["react-native", "ios", "android", "survey", "uxrate"],
+  "author": "UXRate <sdk@uxrate.app>",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "react-native": "index.js",
+  "codegenConfig": {
+    "name": "RNUXRateSpec",
+    "type": "modules",
+    "jsSrcsDir": "."
+  }
+}

package/react-native-uxrate.podspec

@@ -0,0 +1,18 @@
+Pod::Spec.new do |s|
+  s.name         = 'react-native-uxrate'
+  s.version      = '0.1.0'
+  s.summary      = 'React Native bridge for UXRate iOS SDK'
+  s.description  = 'React Native module for the UXRate iOS SDK — embed AI-powered surveys in your React Native app.'
+  s.homepage     = 'https://github.com/SVUG-Tech/UXRateSDK'
+  s.license      = { :type => 'MIT' }
+  s.author       = { 'UXRate' => 'sdk@uxrate.app' }
+  s.source       = { :git => 'https://github.com/SVUG-Tech/react-native-uxrate.git', :tag => s.version.to_s }
+
+  s.ios.deployment_target = '17.0'
+  s.swift_version = '5.9'
+
+  s.source_files = 'ios/**/*.{swift,m,h}'
+
+  s.dependency 'React-Core'
+  s.dependency 'UXRateSDK', '~> 0.1.0'
+end