@originallyus/feedback-rn-sdk

v4.0.0

Published

17 days ago

A cross-platform Feedback component for React Native.

0High
0Medium
0Low

originallyus

react-native ios android

React Native FeedbackSDK

A cross-platform Feedback component for React Native.

🚀 Live Demo

Before running the Live Demo, make sure you have Expo Go app installed.

iOS: Open in App Store
Android: Get it on Google Play

After installing:

Scan the QR code below using Expo Go (Android) or the Camera app (iOS).
Or open the Try on Expo Dev link below directly (it will try to open Expo Go; if it doesn't work yet, open it again after installing Expo Go).

Expo QR

👉 Try on Expo Dev

📦 Installation

npm install @originallyus/feedback-rn-sdk@latest

or yarn

yarn add @originallyus/feedback-rn-sdk@latest

📋 System Requirements & Compatibility

⚠️ These components are provided privately by your corporate team, please contact Group IT team for installation instructions.

@xxx-dds/icons
@xxx-dds/illustration
@xxx-dds/styles
@xxx-mobile-dds/atoms
@xxx-mobile-dds/hooks
@xxx-mobile-dds/molecules
@xxx-mobile-dds/organisms
@xxx-mobile-dds/utils

Peer Dependencies

This SDK requires several peer dependencies to function correctly. Make sure to install them in your project:

Required:

react-native-paper
react-native-reanimated
react-native-keyboard-controller
react-native-svg
react-native-svg-transformer
react-native-worklets (Required for RN >= 0.83 with Reanimated 4)
@react-native-async-storage/async-storage
expo-device (for Expo projects only)
expo-application (for Expo projects only)
react-native-device-info (Bare RN only)

Haptics (Optional but Recommended):

Expo Projects: expo-haptics
Bare RN Projects: react-native-haptic-feedback

📱 Installation Commands

1. For Expo Projects (SDK 53+)

Expo automatically resolves compatible dependency versions:

npx expo install \
  react-native-paper \
  react-native-reanimated \
  react-native-keyboard-controller \
  react-native-svg \
  @react-native-async-storage/async-storage \
  axios \
  crypto-js \
  expo-haptics \
  expo-device \
  expo-application

2. For Bare React Native Projects

[!WARNING] Important Version Compatibility Notes:
React Native 0.78 – 0.82:
react-native-reanimated: Must pin to ^3.16.0 (do not install Reanimated 4 as it requires RN >= 0.83).
@react-native-async-storage/async-storage: Recommend ^2.1.0 (AsyncStorage v3 requires Kotlin >= 2.1.0 and KSP, while RN 0.78 defaults to Kotlin 2.0.21). If you want to use AsyncStorage v3, upgrade kotlinVersion = "2.1.0" in android/build.gradle.
react-native-worklets: Built into Reanimated 3, no need to install separately.
React Native >= 0.83:
Can use react-native-reanimated@^4.0.0, react-native-worklets@^0.20.0, and @react-native-async-storage/async-storage@^3.0.0 (with Kotlin 2.1.0+).

Option A: React Native 0.78 – 0.82 (Reanimated 3):

Using npm:

npm install \
  react-native-paper \
  react-native-reanimated@^3.16.7 \
  react-native-keyboard-controller \
  react-native-svg \
  @react-native-async-storage/async-storage@^2.1.0 \
  react-native-haptic-feedback \
  react-native-device-info

Using yarn:

yarn add \
  react-native-paper \
  react-native-reanimated@^3.16.7 \
  react-native-keyboard-controller \
  react-native-svg \
  @react-native-async-storage/async-storage@^2.1.0 \
  react-native-haptic-feedback \
  react-native-device-info

Option B: React Native >= 0.83 (Reanimated 4):

Using npm:

npm install \
  react-native-paper \
  react-native-reanimated@^4.0.0 \
  react-native-worklets@^0.20.0 \
  react-native-keyboard-controller \
  react-native-svg \
  @react-native-async-storage/async-storage \
  react-native-haptic-feedback \
  react-native-device-info

Using yarn:

yarn add \
  react-native-paper \
  react-native-reanimated@^4.0.0 \
  react-native-worklets@^0.20.0 \
  react-native-keyboard-controller \
  react-native-svg \
  @react-native-async-storage/async-storage \
  react-native-haptic-feedback \
  react-native-device-info

⚠️ SVG Transformer Setup (Required for Bare RN Projects)

[!IMPORTANT] If you skip this step, the app will crash with "Element type is invalid: expected a string or class/function but got: number". This happens because Metro bundles .svg files as static assets (returning a number) instead of React components.

The SDK uses SVG icons internally. For Bare React Native projects, you must configure react-native-svg-transformer in your Metro bundler config.

Step 1: Install the packages (if not already):

# npm
npm install react-native-svg react-native-svg-transformer

# yarn
yarn add react-native-svg react-native-svg-transformer

Step 2: Update your metro.config.js:

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');

const defaultConfig = getDefaultConfig(__dirname);
const { assetExts, sourceExts } = defaultConfig.resolver;

/**
 * Metro configuration
 * https://reactnative.dev/docs/metro
 *
 * @type {import('metro-config').MetroConfig}
 */
const config = {
  transformer: {
    babelTransformerPath: require.resolve(
      'react-native-svg-transformer/react-native',
    ),
  },
  resolver: {
    assetExts: assetExts.filter(ext => ext !== 'svg'),
    sourceExts: [...sourceExts, 'svg'],
  },
};

module.exports = mergeConfig(defaultConfig, config);

[!NOTE] For Expo projects, SVG transformer is handled automatically — no manual Metro config needed.

https://www.npmjs.com/package/react-native-svg-transformer

🔡 Custom Fonts

The SDK works best with Spoqa Han Sans Neo or OpenSans. Please ensure you have these fonts installed in your React Native project.

[!IMPORTANT] Do not change font filenames on Android as the system uses exact filenames to identify them.

Font download:

https://fonts.google.com/specimen/Open+Sans
https://spoqa.github.io/spoqa-han-sans/en-US/#download

🚀 Quick Start

1. Root Mounting (`FeedbackSDK`)

Mount the FeedbackSDK component at the root of your application (typically in App.tsx). It should be at the bottom of your root view tree to stay on top of other views.

import { useRef } from 'react'
import { View } from 'react-native'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { FeedbackSDK, type FeedbackSDKRef } from '@originallyus/feedback-rn-sdk'

export default function App() {
  const feedbackRef = useRef<FeedbackSDKRef>(null)

  const config = {
    appSec: 'YOUR_APP_SEC',
    debug: true,
    language: 'en',
    userId: 'USER_123',
    metadata: { policy: '987654321' },
    topOffset: 52 // optionnal
  }

  return (
    <SafeAreaProvider>
      <View style={{ flex: 1 }}>
        <MainApp />

        {
         /*
          Please insert this mount point directly in your App.js,
          preferably at the bottom of your root view tree for it to stay on top of all other views 
         */
        }
        <FeedbackSDK
          ref={feedbackRef}
          {...config}
          onClose={() => console.log('Closed')}
          onSubmit={(res) => console.log('Submitted', res)}
        />
      </View>
    </SafeAreaProvider>
  )
}

2. Triggering Feedback

You can trigger a feedback form from anywhere in your app using the ref.

// Show a specific form by slug
feedbackRef.current.show('satisfaction-4')

// Hide the form
feedbackRef.current.hide()

🧩 Components

`FeedbackSDK` (Modal)

The primary component for showing high-intrusive or triggered surveys.

| Prop | Type | Description | | ----------- | ---------- | ------------------------------------------------ | | appSec | string | Required. Your application credentials. | | debug | boolean | Enable debug logs. | | language | string | Language code (e.g., "en", "vi", "th"). | | userId | string | Optional external user ID. | | metadata | object | Optional key-value pairs for additional context. | | onClose | function | Callback when modal is dismissed. | | onSubmit | function | Callback when form is successfully submitted. | | topOffset | number | Optional offset for the modal (default is 52). |

`ContentUsefulness` (Inline)

Use this for inline feedback (e.g., "Was this helpful?") inside your content screens.

<ContentUsefulness
    slug="content_usefulness-1"
    options={{
	appSec: '...',
	debug: true,
    }}
    onSuccess={res => console.log('Useful!', res)}
    onError={err => console.error(err)}
/>

| Prop | Type | Description | | ---------------- | ------------- | ----------------------------------------------- | | slug | string | Required. The form slug from the CMS. | | options | InitOptions | Configuration (same as FeedbackSDK props). | | style | ViewStyle | Container style override. | | initialVisible | boolean | Whether to show immediately (default: false). | | onSuccess | function | Callback on success. | | onError | function | Callback on error. |

📊 Supported Survey Types & Slugs

The SDK dynamically renders UI based on the configuration of the form slug in the backend. Use the following slugs for testing or integration:

| Form Type | Typical Slug | Icon | Description | | ---------------- | ---------------------- | ---- | -------------------------------------------------- | | Satisfaction | satisfaction-4 | ⭐ | Star rating (1-5) with optional detailed feedback. | | NPS | nps-1 | 📊 | Net Promoter Score scale. | | CES / Effort | effort-1 | ⚡ | Customer Effort Score numeric scale. | | Poll | poll-1 | 📝 | Multi-select tag-style buttons for quick surveys. | | Usefulness | content_usefulness-1 | 💡 | Inline "Yes/No" prompt for help articles. | | Comment | comment-1 | 🗨️ | Simple open-ended text feedback. | | External | external-1 | 🔗 | Triggers an external URL (App Store, Web). |

Example: Triggering a specific form

// Trigger NPS survey
feedbackRef.current.show('nps-1')

// Trigger Satisfaction survey
feedbackRef.current.show('satisfaction-4')

⏳ Delayed Form Logic

The SDK supports showing forms after a specific delay. This is useful for capturing feedback after a user has had time to interact with a feature.

How it works:

When a form is requested, the server can specify a delay_second.
The SDK saves the form data to @react-native-async-storage/async-storage.
If the app is closed and reopened, the SDK will check for pending forms and show them if the delay has passed but the delay_second_expiry has not.

Requirements:

Ensure you have installed and linked @react-native-async-storage/async-storage:

yarn add @react-native-async-storage/async-storage
# or
npm install @react-native-async-storage/async-storage

For more details on implementation, see the Delayed Form Implementation Walkthrough.

🛠️ Extra Configuration

Android (External Links)

If your forms use external URLs, ensure your AndroidManifest.xml includes queries:

<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="http" />
        <data android:scheme="https" />
    </intent>
</queries>

📄 License

Built with ❤️ by Originally US. Released under the MIT License.