React Native Survey Intercept SDK

A React Native SDK wrapper for QuestionPro Survey Intercept SDK that provides JavaScript bridge to native Android and iOS survey functionality.

Architecture

Following React Native >= 0.70 best practices:

• Native SDK handles all UI components - Survey display and interaction managed by native SDKs
• JS wrapper only provides bridge - Clean separation between React Native and native functionality
• Event-driven communication - Real-time survey lifecycle events (survey_shown, survey_completed, survey_dismissed)

Features

• ✅ Cross-platform: Android Kotlin + iOS Swift bridges
• ✅ TypeScript Support: Full type definitions included
• ✅ Event System: Real-time survey lifecycle events
• ✅ DataCenter Support: US, EU, CA, SG, AU, AE, SA, KSA
• ✅ Debug Logging: Configurable debug mode
• ✅ Screen Tracking: setScreenVisited functionality
• ✅ Data Mappings: User data for survey targeting

Installation

1. Install the package

npm install @npm-questionpro/react-native-survey-intercept

or

yarn add @npm-questionpro/react-native-survey-intercept

2. iOS Setup

No extra steps needed for CocoaPods — QuestionProCXFramework is fetched automatically when you run pod install. Just run:

cd ios && pod install

How it works: The SDK's podspec includes a prepare_command that shallow-clones the ios-cx repo at the pinned version tag and vendors the pre-built QuestionProCXFramework.xcframework locally. You do not need to add any extra pod entry to your Podfile.

Note: Internet access is required on the first pod install (or after a version upgrade). Subsequent installs use the cached framework.

3. Android Setup

No repository configuration needed. The android-cx SDK is downloaded automatically the first time you build the Android project.

How it works: The SDK's build.gradle includes a download block that fetches android-cx-2.3.0.aar directly from JitPack at Gradle configuration time — no JitPack repository entry required in your app's build.gradle or settings.gradle. The AAR is cached locally and only re-downloaded when the version changes.

Note: Internet access is required on the first build (or after a version upgrade). Subsequent builds use the cached AAR.

AndroidManifest.xml Configuration

Add the following to your android/app/src/main/AndroidManifest.xml if not already present:

  <uses-permission android:name="android.permission.INTERNET" />

Usage

Basic Configuration

import InterceptSdk, {DataCenter} from '@npm-questionpro/react-native-survey-intercept';
// Configure the SDK
await InterceptSdk.configure({
  apiKey: 'your-api-key-here',
  dataCenter: DataCenter.US, // US, EU, CA, SG, AU, AE, SA, KSA
  enableDebug: true // Optional: Enable debug logging
});

Data Mappings

Set user data for survey targeting and personalization:

import InterceptSdk from '@npm-questionpro/react-native-survey-intercept';
import { DataMapping } from '@npm-questionpro/react-native-survey-intercept';

const setDataMappings = async () => {
  try {
    const dataMappings: DataMapping = {
      'firstName': 'first_name',
      'lastName': 'last_name',
      'emailAddress': '[email protected]'
    };
    
    const result = await InterceptSdk.setDataMappings(dataMappings);
    console.log('✅ setDataMappings result:', result);
  } catch (error) {
    console.error('❌ setDataMappings error:', error);
  }
};

// Call the function
await setDataMappings();

View Count / Screen Visited

Track screen visits to trigger surveys based on user navigation patterns.

How to Set-up View Count Rule on QuestionPro

The 'View Count' rule, found in the 'Rules set-up' section of the admin dashboard, allows administrators to control when an intercept is displayed to users based on their mobile application navigation. This rule uses two parameters:

• screen_name: Specify the screen(s) to monitor
• count: Set the view threshold before the intercept is triggered

Set up the rule:

1. Select the rule 'view count' from the mobile intercept settings
2. Set 'screen name' (for example: 'checkout_screen')
3. Set the count (After how many events you want to launch the survey)

How to Use in the SDK

import InterceptSdk from '@npm-questionpro/react-native-survey-intercept';

const launchFeedbackSurvey = async () => {
  try {
    const result = await InterceptSdk.setScreenVisited('checkout_screen');
    console.log('✅ Survey launch result:', result);
  } catch (error) {
    console.error('❌ Launch survey error:', error);
  }
};

// Call when user visits a specific screen
await launchFeedbackSurvey();

API Reference

Configuration Options

interface ConfigureOptions {
  apiKey: string;           // Required: Your QuestionPro API key
  dataCenter?: DataCenter;  // Required: Data center region
  enableDebug?: boolean;    // Optional: Enable debug logging
}

enum DataCenter {
  US = 'US',    // United States (default)
  EU = 'EU',    // Europe
  CA = 'CA',    // Canada
  SG = 'SG',    // Singapore
  AU = 'AU',    // Australia
  AE = 'AE',    // UAE
  SA = 'SA',    // Saudi Arabia
  KSA = 'KSA'   // Kuwait, Saudi Arabia
}

Methods

| Method | Parameters | Returns | Description | |--------|------------|---------|-------------| | configure() | ConfigureOptions | Promise<SurveyResult> | Initialize the SDK with API key and settings | | setScreenVisited() | screenName: string | Promise<any> | Track screen visits for survey targeting | | setDataMappings() | data: DataMapping | Promise<any> | Set user data for survey personalization |

Platform Support

• React Native: >= 0.70
• iOS: >= 15.0
• Android: >= API 21 (Android 5.0)

Native SDK Versions

• iOS: QuestionPro CX Framework v2.3.0
• Android: QuestionPro CX SDK v2.3.0

Troubleshooting

iOS Build Issues

1. Module not found: Run pod install again — the prepare_command will fetch QuestionProCXFramework automatically
2. Pod install fails: Try pod install --repo-update
3. Swift compilation errors: Verify iOS deployment target >= 15.0
4. Pod not installed: If the react-native-survey-intercept pod is not installed, add it manually to your Podfile:

pod 'react-native-survey-intercept', :path => '../node_modules/@npm-questionpro/react-native-survey-intercept'

Android Build Issues

1. Gradle sync fails: Check Android SDK versions in android/build.gradle
2. Kotlin compilation errors: Ensure Kotlin version >= 1.8.0
3. AAR download fails: Ensure internet access is available during the first Gradle build. If behind a corporate proxy, configure Gradle proxy settings in ~/.gradle/gradle.properties
4. lintDebug build failure: Lint has found errors in your Android project.
   • Preferred: Fix the issues reported by lint in the build output.

// ...existing code...
android {
    // ...existing config...

    lint {
        abortOnError false
        checkReleaseBuilds false
    }
}
// ...existing code...

Debug Mode

Enable debug logging to troubleshoot issues:

await InterceptSdk.configure({
  apiKey: 'your-api-key',
  enableDebug: true
});

License

MIT License. See LICENSE file for details.

Support

For technical support and questions:

• Email: [email protected]
• Documentation: QuestionPro Developer Docs
• Issues: GitHub Issues

Note: This is a bridge SDK. All survey UI components are handled by the native QuestionPro CX SDKs, ensuring optimal performance and native user experience.