React Native SDK
Complete integration guide for the Encatch React Native SDK — in-app feedback forms, user identification, and event tracking for React Native and Expo apps
Beta
This SDK is currently in beta. APIs may change, and we welcome your feedback. Use with caution in production environments.
The Encatch React Native SDK lets you collect user feedback in your React Native and Expo apps. Display feedback forms in a WebView overlay, identify users, track screens and events, and submit responses to the Encatch backend.
Overview
- Package:
@encatch/react-native-sdk - Version: 1.0.0-beta.0
- Repository: github.com/get-encatch/react-native-sdk
Installation
npm install @encatch/react-native-sdkyarn add @encatch/react-native-sdkpnpm add @encatch/react-native-sdkQuick Start
1. Wrap your app with EncatchProvider
import { EncatchProvider, EncatchWebView } from '@encatch/react-native';
function App() {
return (
<EncatchProvider
apiKey="YOUR_API_KEY"
config={{
apiBaseUrl: 'https://app.encatch.com',
theme: 'system',
debugMode: false,
}}
navigationType="react-navigation">
<EncatchWebView />
{/* Your app content */}
</EncatchProvider>
);
}2. Use the useEncatch hook
import { useEncatch } from '@encatch/react-native';
function FeedbackButton() {
const { showForm, trackEvent } = useEncatch();
return (
<Button
title="Give Feedback"
onPress={() => showForm('your-form-id')}
/>
);
}Configuration
EncatchProvider props
<EncatchProvider
apiKey="YOUR_API_KEY"
config={{ apiBaseUrl: 'https://app.encatch.com' }}
navigationType="react-navigation"
skippedRoutes={['/login', '/splash']}>
<App />
</EncatchProvider>Prop
Type
EncatchConfig
config={{
apiBaseUrl: 'https://app.encatch.com',
webHost: 'https://app.encatch.com',
theme: 'system',
isFullScreen: false,
debugMode: false,
appVersion: '1.0.0',
onBeforeShowForm: async (payload) => {
// Return false to block and show custom UI
return true;
},
}}Prop
Type
Components
EncatchProvider
Wraps your app and:
- Initializes the SDK on mount
- Optionally tracks screen changes (Expo Router or React Navigation)
- Exposes the SDK via
useEncatch()
<EncatchProvider
apiKey="YOUR_API_KEY"
config={{ apiBaseUrl: 'https://app.encatch.com' }}
navigationType="react-navigation"
skippedRoutes={['/login', '/splash']}>
<App />
</EncatchProvider>EncatchWebView
Renders the Encatch form inside a WebView overlay. Place it once in your root layout (typically inside EncatchProvider). No props required.
<EncatchProvider apiKey="..." config={...}>
<EncatchWebView />
<App />
</EncatchProvider>useEncatch Hook
useEncatch() returns the full SDK API. Use it inside components that are children of EncatchProvider.
Return value
const {
showForm,
trackEvent,
identifyUser,
addToResponse,
resetUser,
} = useEncatch();Prop
Type
User Identification
Identify users to personalize feedback and link responses to accounts.
const { identifyUser } = useEncatch();
identifyUser('user@example.com', {
$set: { email: 'user@example.com', plan: 'premium' },
$setOnce: { signupDate: new Date().toISOString() },
}, {
locale: 'en',
country: 'US',
});Secure identification
For secure user identification, pass secure in options:
identifyUser('user@example.com', traits, {
secure: {
signature: '...',
generatedDateTimeinUTC: '2025-01-15T12:00:00Z',
},
});Showing Forms
By form ID or slug
const { showForm } = useEncatch();
// Show form by ID or slug
showForm('my-feedback-form');Reset options
Control when form data is cleared:
showForm('my-form', {
reset: 'always', // Clear every time (default)
reset: 'on-complete', // Clear only if form was previously completed
reset: 'never', // Preserve previous answers
});Prefilling responses
const { addToResponse, showForm } = useEncatch();
addToResponse('question-id-1', 5); // Rating
addToResponse('question-id-2', 'Great app!'); // Short answer
showForm('my-form');Event Tracking
Custom events
const { trackEvent } = useEncatch();
trackEvent('button_clicked');
trackEvent('checkout_completed');Screen tracking
If you use navigationType, screens are tracked automatically. Otherwise, call trackScreen manually:
const { trackScreen } = useEncatch();
trackScreen('/home/products/123');SDK Events
Subscribe to form lifecycle and other events:
const { on, off } = useEncatch();
useEffect(() => {
const callback = (eventType, payload) => {
console.log(eventType, payload);
};
const unsubscribe = on(callback);
return unsubscribe;
}, []);Custom Native Forms
Use the onBeforeShowForm interceptor to show your own native form instead of the WebView. Return false to block the default form.
import { Encatch } from '@encatch/react-native';
<EncatchProvider
apiKey="..."
config={{
onBeforeShowForm: async (payload) => {
const { formId, formConfig, prefillResponses } = payload;
// Show your custom native form
const result = await showCustomForm(formConfig, prefillResponses);
if (result) {
const req = buildSubmitRequest(
{ formConfigurationId: formConfig.feedbackConfigurationId },
result.responses
);
Encatch.submitForm(req);
}
return false; // Don't show default WebView form
},
}}>
<EncatchWebView />
<App />
</EncatchProvider>buildSubmitRequest
Helper to build a SubmitFormRequest from native form responses:
import { buildSubmitRequest, Encatch } from '@encatch/react-native';
const responses = [
{ questionId: 'q1', type: 'rating', value: 5 },
{ questionId: 'q2', type: 'short_answer', value: 'Great product!' },
];
const req = buildSubmitRequest(
{
formConfigurationId: formConfig.feedbackConfigurationId,
triggerType: 'manual',
completionTimeInSeconds: 45,
},
responses
);
Encatch.submitForm(req);Session & User Reset
Reset user
Clears identity, session, and feedback transactions. Use after logout:
const { resetUser } = useEncatch();
const handleLogout = async () => {
await signOut();
resetUser();
};