React Native SDK

Features and compatibility overview.

The encatch React Native SDK provides seamless integration for React Native applications, enabling automated feedback collection, user analytics, and behavior tracking with minimal setup.

Quick Start

Get encatch running in your React Native application in under 5 minutes with the steps below.

Installation & Initialization

Installation

Install the encatch React Native SDK using your preferred package manager:

@encatch/react-native

Initialization

import { EnsightApp } from "@encatch/react-native";

EnsightApp.initialize({
  apiKey: "Your Ensight API Key",
});

import { EnsightConfig } from "@encatch/react-native";

const user = {
  user_name: "John Doe",
  properties: {
    email: "johndoe@mail.com",
    user_age: 30,
  },
};

const customConfig = new EnsightConfig({
  host: "https://custom-url.com",
  identity: user,
  isAutoCaptureEnabled: false,
  themeMode: "dark",
  language: "en"
});

EnsightApp.initialize({
  apiKey: "Your Ensight API Key",
  config: customConfig,
  debugMode: true,
});

interface UserInfoModel {
  user_name: string;
  properties: {
    email: string | null;
    user_age: number | null;
  };
}

For enterprise version

const customConfig = new EnsightConfig({
  host: 'https://your-encatch-instance'
});

EnsightApp.initialize({
  apiKey: "Your Ensight API Key",
  config: customConfig,
});

UI Component Integration

After initializing the SDK, you must integrate the EnsightRootUIComponent into your application's base layout file. This component is responsible for rendering popup UIs and is essential for displaying Ensight's interactive popups to users.

Add the component to your main layout file such as _layout.tsx, App.tsx, main.tsx, or any root-level file where your final components are rendered.

import React from 'react';
import { EnsightRootUIComponent } from "@encatch/react-native";
import YourMainApp from './YourMainApp';

export default function App() {
  return (
    <>
      <YourMainApp />
      <EnsightRootUIComponent />
    </>
  );
}

How to use

Manual Feedback Triggering

The SDK provides three methods to manually open feedback forms, giving you control over when and which feedback is displayed to users:

import React from 'react';
import { TouchableOpacity, Text } from 'react-native';
import { EnsightApp } from "@encatch/react-native";

const FeedbackComponent = () => {
  const openFeedback = async () => {
    await EnsightApp.openFeedback();
  };

  return (
    <TouchableOpacity onPress={openFeedback}>
      <Text>Open Feedback</Text>
    </TouchableOpacity>
  );
};

import React from 'react';
import { TouchableOpacity, Text } from 'react-native';
import { EnsightApp } from "@encatch/react-native";

const FeedbackComponent = () => {
  const openFeedback = async () => {
    await EnsightApp.openFeedbackById('feedback_config_123');
  };

  return (
    <TouchableOpacity onPress={openFeedback}>
      <Text>Open Specific Feedback</Text>
    </TouchableOpacity>
  );
};

import React from 'react';
import { TouchableOpacity, Text } from 'react-native';
import { EnsightApp } from "@encatch/react-native";

const FeedbackComponent = () => {
  const openFeedback = async () => {
    await EnsightApp.openFeedbackByName('Product Satisfaction Survey');
  };

  return (
    <TouchableOpacity onPress={openFeedback}>
      <Text>Open Feedback by Name</Text>
    </TouchableOpacity>
  );
};

Best Practice: Use feedback IDs for programmatic control and names for content-driven scenarios. IDs are more stable across configuration changes.

User Identification

The EnsightApp.identify(user) method is used to identify the current user and fetch personalized configurations based on the user's profile. When called, this method refreshes the list of eligible feedbacks for the identified user, ensuring they receive relevant and targeted feedback forms.

Call this method after user authentication to enable personalized experiences and appropriate feedback targeting.

import { EnsightApp } from "@encatch/react-native";

// Define user object with required properties
const user = {
  user_name: "john_doe",
  properties: {
    email: "john@example.com",
    user_age: 30,
  },
};

// Identify user after successful login
const handleUserLogin = async () => {
  await EnsightApp.identify(user);
};

Use Cases:

• User authentication integration
• Personalized feedback targeting
• User profile management
• Role-based feedback configuration

Navigation Tracking

For applications using navigation libraries other than @react-navigation/native or implementing custom navigation logic, you can create a navigation wrapper to enable automatic screen and path tracking. This wrapper ensures the SDK captures navigation events and sends the necessary information for analytics and targeting.

Custom Navigation Wrapper

Create a navigation wrapper component that tracks route changes and communicates them to the Ensight SDK:

import React, { useEffect, useRef } from "react";
import { usePathname } from "expo-router";
import { EnsightApp } from "@encatch/react-native";

interface NavigationWrapperProps {
  children: React.ReactNode;
}

export function NavigationWrapper({
  children,
}: Readonly<NavigationWrapperProps>) {
  const pathname = usePathname();
  const currentRoute = useRef<string | null>(null);

  useEffect(() => {
    if (pathname && currentRoute.current !== pathname) {
      currentRoute.current = pathname;

      try {
        EnsightApp.setCurrentPath(pathname);
      } catch (error) {
      }
    }
  }, [pathname]);

  return <>{children}</>;
}

Wrap your main layout file with the NavigationWrapper to enable automatic path tracking:

import { Stack } from "expo-router";
import { NavigationWrapper } from "./NavigationWrapper";

export default function RootLayout() {
  return (
    <NavigationWrapper>
      <Stack>
        <Stack.Screen name="index" options={{ title: "Home" }} />
        <Stack.Screen name="profile" options={{ title: "Profile" }} />
      </Stack>
    </NavigationWrapper>
  );
}

Use Cases:

• Custom navigation libraries
• Expo Router integration
• Manual route tracking
• Analytics and targeting enhancement

Theme and Language Configuration

The SDK automatically detects and applies theme and language settings based on the device's system preferences. However, if your application implements custom theming or language settings that differ from the device defaults, you can override these settings to ensure popup consistency with your app's appearance.

Manual Theme and Language Setting

Use these methods to synchronize the SDK's UI with your application's custom theme and language preferences:

import { EnsightApp, EnsightTheme } from "@encatch/react-native";

const applyCustomSettings = () => {
  // Apply custom theme based on app's theme state
  const currentTheme = userPreferences.isDarkMode ? EnsightTheme.dark : EnsightTheme.light;
  EnsightApp.setTheme(currentTheme);
  
  // Apply custom language based on app's language setting
  const selectedLanguage = userPreferences.language || "en";
  EnsightApp.setLanguage(selectedLanguage);
};

Use Cases:

• Dark mode toggle implementation
• System theme synchronization
• User preference persistence
• Internationalization (i18n) implementation
• Multi-language application support

Session Management

The SDK provides two methods to manage user sessions, each serving different use cases depending on how much user data you want to preserve or reset.

Session Control Methods

stopSession(): Ends the current session and starts a new one while preserving all user data, identity, and state. This method is useful for creating session boundaries without losing user context.

resetSession(): Performs a complete reset by starting a new session, clearing user identity, resetting analytics data, and reloading configuration. This returns the SDK to its initial anonymous state.

import { EnsightApp } from "@encatch/react-native";

// Example usage scenarios
const handleUserLogout = () => {
  // Full reset when user logs out
  EnsightApp.resetSession();
};

const handleAppBackground = () => {
  // Simple session end when app goes to background
  EnsightApp.stopSession();
};

Use Cases:

• User logout scenarios
• App lifecycle management
• Session boundary creation
• Data privacy compliance
• User context preservation

Advanced Configuration