@encatch/react-native-sdk 1.0.0-beta.0 → 1.0.0-beta.3

package/README.md

@@ -1,204 +1,24 @@
-# Ensight React Native SDK Documentation
+# @encatch/react-native-sdk
 
-## Overview
-
-Ensight SDK provides a seamless way to integrate user feedback collection into your React Native applications. This SDK allows you to display customized feedback forms, collect user responses, and submit them to the Ensight backend.
+The Encatch React Native SDK lets you collect user feedback in your React Native and Expo apps. Display feedback forms in using native with encatch hooks or a WebView overlay, identify users, track screens and events, and submit responses to the Encatch backend.
 
 ## Installation
 
 ```bash
-# Using npm
-npm install ensight-react-native
-
-# Using yarn
-yarn add ensight-react-native
-```
-
-## Quick Start
-
-```javascript
-import Ensight, { EnsightConfig, EnsightTheme } from "ensight-react-native";
-
-// Initialize the SDK
-const config = new EnsightConfig({
-  host: "https://app.dev.en-gage.in",
-  themeMode: "light",
-  language: "en",
-});
-
-Ensight.instance.ensightApp.initialize({
-  apiKey: "YOUR_API_KEY_HERE",
-  config: config,
-});
-
-// Open feedback form
-Ensight.instance.ensightApp.openFeedback();
+npm install @encatch/react-native-sdk
+# or
+yarn add @encatch/react-native-sdk
+# or
+pnpm add @encatch/react-native-sdk
 ```
 
-## Core Features
-
-- In-app feedback collection
-- Customizable feedback forms
-- Theme support (light/dark)
-- Multilingual support
-- User identification
-- Session management
-- Event analytics
-
-## SDK Initialization
-
-Initialize the SDK early in your application lifecycle:
-
-```javascript
-const userInfo = {
-  user_name: "user@example.com",
-  properties: {
-    email: "user@example.com",
-    user_age: 30,
-  },
-};
-
-const config = new EnsightConfig({
-  host: "https://app.dev.en-gage.in",
-  identity: userInfo,
-  processAfterIdentitySet: false,
-  isAutoCaptureEnabled: true,
-  themeMode: "light",
-  language: "en",
-});
-
-Ensight.instance.ensightApp.initialize({
-  apiKey: "YOUR_API_KEY_HERE",
-  config: config,
-});
-```
-
-## Displaying Feedback Forms
-
-### Open Default Feedback
-
-```javascript
-await Ensight.instance.ensightApp.openFeedback();
-```
-
-### Open Feedback by ID
-
-```javascript
-await Ensight.instance.ensightApp.openFeedbackById("FEEDBACK_CONFIGURATION_ID");
-```
-
-### Open Feedback by Name
-
-```javascript
-await Ensight.instance.ensightApp.openFeedbackByName("Feedback Form Title");
-```
-
-## User Identification
-
-Identify users to personalize feedback forms:
-
-```javascript
-Ensight.instance.ensightApp.identify("user@example.com", {
-  email: "user@example.com",
-  user_age: 30,
-});
-```
-
-## Session Management
-
-Control and manage user sessions:
-
-```javascript
-// Stop the current session and generate a new session ID
-await Ensight.instance.ensightApp.stopSession();
-
-// Reset the session, clear user data, and reinitialize
-await Ensight.instance.ensightApp.resetSession();
-```
-
-## Theming
-
-Customize the appearance of feedback forms:
-
-```javascript
-// Set theme to dark mode
-Ensight.instance.ensightApp.setTheme(EnsightTheme.dark);
-
-// Set theme to light mode
-Ensight.instance.ensightApp.setTheme(EnsightTheme.light);
-```
-
-## Language Support
-
-Change the language for feedback forms:
-
-```javascript
-// Set language to English
-Ensight.instance.ensightApp.setLanguage("en");
-
-// Set language to Spanish
-Ensight.instance.ensightApp.setLanguage("es");
-```
-
-## Event Tracking
-
-Track user events for analytics:
-
-```javascript
-const eventInfo = {
-  event_name: "button_click",
-  properties: {
-    button_id: "submit_form",
-    page: "checkout",
-  },
-};
-
-Ensight.instance.ensightApp.queueEvent(eventInfo);
-```
-
-## Path Observation
-
-Track user navigation within your app:
-
-```javascript
-// Set the current path
-Ensight.instance.ensightApp.setCurrentPath("/home/products");
-
-// Add path change observer
-const pathObserver = Ensight.instance.ensightApp.pathObserver;
-pathObserver.addObserver((oldPath, newPath) => {
-  console.log(`Navigation changed from ${oldPath} to ${newPath}`);
-});
-```
-
-## Troubleshooting
-
-If you encounter issues with the SDK:
-
-1. Check initialization parameters
-2. Verify API key and host URL
-3. Ensure network connectivity
-4. Check console logs for error messages
+## Documentation
 
-## API Reference
+For the full API reference, configuration options, and usage examples, visit the official documentation:
 
-| Method/Property         | Description                             | Parameters                                                     | Return          |
-| ----------------------- | --------------------------------------- | -------------------------------------------------------------- | --------------- |
-| `initialize`            | Initializes the SDK                     | `apiKey: string, config?: EnsightConfig`                       | `void`          |
-| `openFeedback`          | Opens the default feedback form         | None                                                           | `Promise<void>` |
-| `openFeedbackById`      | Opens a feedback form by ID             | `id: string`                                                   | `Promise<void>` |
-| `openFeedbackByName`    | Opens a feedback form by name           | `name: string`                                                 | `Promise<void>` |
-| `identify`              | Identifies a user                       | `userId: string, traits?: Record<string, any>`                 | `void`          |
-| `submitFeedback`        | Submits feedback data                   | `feedback?: Record<string, any>`                               | `Promise<void>` |
-| `stopSession`           | Stops the current session               | None                                                           | `Promise<void>` |
-| `resetSession`          | Resets the session and clears user data | None                                                           | `Promise<void>` |
-| `setTheme`              | Sets the theme                          | `theme: EnsightTheme`                                          | `void`          |
-| `setLanguage`           | Sets the language                       | `language: string`                                             | `void`          |
-| `queueEvent`            | Adds an event to the analytics queue    | `event: EventInfo`                                             | `void`          |
-| `setCurrentPath`        | Sets the current path for analytics     | `path: string`                                                 | `void`          |
-| `addPopupStateListener` | Adds a listener for popup state changes | `listener: (isVisible: boolean, props?: PopupUIProps) => void` | `() => void`    |
-| `pathObserver`          | Gets the path observer instance         | None                                                           | `PathObserver`  |
+**[https://encatch.com/docs/sdk-reference/mobile-sdk/react-native](https://encatch.com/docs/sdk-reference/mobile-sdk/react-native)**
 
-## Support
+## License
 
-For additional support, please contact support@ensight.com or visit our documentation at https://docs.ensight.com
+MIT
+ 

package/dist/index.d.mts

@@ -39,6 +39,8 @@ interface ShowFormInterceptorPayload {
     prefillResponses: Record<string, unknown>;
     locale?: string;
     theme?: Theme;
+    /** Serialized caller context (Dates already converted to ISO strings) */
+    context?: Record<string, string | number | boolean>;
 }
 interface StartSessionOptions {
     /** When true, do not call the immediate ping (30s ping interval still runs) */
@@ -75,12 +77,23 @@ type Theme = 'light' | 'dark' | 'system';
  * - 'never': Never clear form data (preserve user's previous answers)
  */
 type ResetMode = 'always' | 'on-complete' | 'never';
+/**
+ * Context values that can be attached to a form submission.
+ * Date values are automatically serialized to ISO strings before being sent.
+ */
+type ContextValue = string | number | Date | boolean;
 interface ShowFormOptions {
     /**
      * Controls when form data should be cleared.
      * @default 'always'
      */
     reset?: ResetMode;
+    /**
+     * Arbitrary key-value pairs attached to the form submission.
+     * Useful for passing caller-side metadata (e.g. plan tier, feature flag states).
+     * Date values are automatically serialized to ISO 8601 strings.
+     */
+    context?: Record<string, ContextValue>;
 }
 type EventType = 'form:show' | 'form:started' | 'form:submit' | 'form:complete' | 'form:close' | 'form:dismissed' | 'form:error' | 'form:section:change' | 'form:answered';
 interface EventPayload {
@@ -112,8 +125,6 @@ interface ShowFormResponse {
     formConfiguration?: Record<string, unknown>;
     questionnaireFields?: any;
     otherConfigurationProperties?: any;
-    welcomeScreenProperties?: any;
-    endScreenProperties?: any;
     appearanceProperties?: any;
     partialResponseEnabled?: boolean;
     pingAgainIn?: number;
@@ -136,6 +147,7 @@ interface RefineTextResponse {
     pingOnNextPageVisit?: boolean;
     $feedbackTransactions?: string;
 }
+type QuestionType = 'rating' | 'single_choice' | 'nps' | 'nested_selection' | 'multiple_choice_multiple' | 'short_answer' | 'long_text' | 'annotation' | 'welcome' | 'thank_you' | 'message_panel' | 'yes_no' | 'rating_matrix' | 'matrix_single_choice' | 'matrix_multiple_choice' | 'exit_form';
 interface QuestionAnswer {
     nps?: number;
     rating?: number;
@@ -151,10 +163,14 @@ interface QuestionAnswer {
         fileData?: string;
         fileName?: string;
     };
+    yesNo?: boolean;
+    ratingMatrix?: Record<string, number | string>;
+    matrixSingleChoice?: Record<string, string>;
+    matrixMultipleChoice?: Record<string, string[]>;
 }
 interface QuestionResponse {
     questionId: string;
-    type?: string;
+    type?: QuestionType;
     answer?: QuestionAnswer;
 }
 interface FormDetails {
@@ -166,6 +182,10 @@ interface FormDetails {
         questions?: QuestionResponse[];
     };
     completionTimeInSeconds?: number;
+    /** Caller-provided metadata attached to this submission (Dates already serialized to ISO strings) */
+    context?: Record<string, string | number | boolean>;
+    /** IDs of questions the user actually navigated to, in order. Used for drop-off analysis. */
+    visitedQuestionIds?: string[];
 }
 interface SubmitFormRequest {
     triggerType?: 'automatic' | 'manual';
@@ -233,6 +253,12 @@ declare class EncatchSDK {
     private _showFormById;
     dismissForm(formConfigurationId?: string): Promise<void>;
     private _pendingResponses;
+    /**
+     * Pre-fills a response before showing a form.
+     * @param questionId - The ID or slug of the question to prepopulate. When a slug
+     *   is provided the form engine resolves it to the matching question ID automatically.
+     * @param value - The value to set
+     */
     addToResponse(questionId: string, value: unknown): void;
     getPendingResponses(): Record<string, unknown>;
     clearPendingResponses(): void;
@@ -308,7 +334,7 @@ interface EncatchContextValue {
     showForm: (formId: string, options?: ShowFormOptions) => void;
     /** Call Encatch.dismissForm */
     dismissForm: (formConfigurationId?: string) => void;
-    /** Call Encatch.addToResponse */
+    /** Call Encatch.addToResponse. Accepts a question ID or slug. */
     addToResponse: (questionId: string, value: unknown) => void;
     /** Call Encatch.resetUser */
     resetUser: () => void;

package/dist/index.d.ts

@@ -39,6 +39,8 @@ interface ShowFormInterceptorPayload {
     prefillResponses: Record<string, unknown>;
     locale?: string;
     theme?: Theme;
+    /** Serialized caller context (Dates already converted to ISO strings) */
+    context?: Record<string, string | number | boolean>;
 }
 interface StartSessionOptions {
     /** When true, do not call the immediate ping (30s ping interval still runs) */
@@ -75,12 +77,23 @@ type Theme = 'light' | 'dark' | 'system';
  * - 'never': Never clear form data (preserve user's previous answers)
  */
 type ResetMode = 'always' | 'on-complete' | 'never';
+/**
+ * Context values that can be attached to a form submission.
+ * Date values are automatically serialized to ISO strings before being sent.
+ */
+type ContextValue = string | number | Date | boolean;
 interface ShowFormOptions {
     /**
      * Controls when form data should be cleared.
      * @default 'always'
      */
     reset?: ResetMode;
+    /**
+     * Arbitrary key-value pairs attached to the form submission.
+     * Useful for passing caller-side metadata (e.g. plan tier, feature flag states).
+     * Date values are automatically serialized to ISO 8601 strings.
+     */
+    context?: Record<string, ContextValue>;
 }
 type EventType = 'form:show' | 'form:started' | 'form:submit' | 'form:complete' | 'form:close' | 'form:dismissed' | 'form:error' | 'form:section:change' | 'form:answered';
 interface EventPayload {
@@ -112,8 +125,6 @@ interface ShowFormResponse {
     formConfiguration?: Record<string, unknown>;
     questionnaireFields?: any;
     otherConfigurationProperties?: any;
-    welcomeScreenProperties?: any;
-    endScreenProperties?: any;
     appearanceProperties?: any;
     partialResponseEnabled?: boolean;
     pingAgainIn?: number;
@@ -136,6 +147,7 @@ interface RefineTextResponse {
     pingOnNextPageVisit?: boolean;
     $feedbackTransactions?: string;
 }
+type QuestionType = 'rating' | 'single_choice' | 'nps' | 'nested_selection' | 'multiple_choice_multiple' | 'short_answer' | 'long_text' | 'annotation' | 'welcome' | 'thank_you' | 'message_panel' | 'yes_no' | 'rating_matrix' | 'matrix_single_choice' | 'matrix_multiple_choice' | 'exit_form';
 interface QuestionAnswer {
     nps?: number;
     rating?: number;
@@ -151,10 +163,14 @@ interface QuestionAnswer {
         fileData?: string;
         fileName?: string;
     };
+    yesNo?: boolean;
+    ratingMatrix?: Record<string, number | string>;
+    matrixSingleChoice?: Record<string, string>;
+    matrixMultipleChoice?: Record<string, string[]>;
 }
 interface QuestionResponse {
     questionId: string;
-    type?: string;
+    type?: QuestionType;
     answer?: QuestionAnswer;
 }
 interface FormDetails {
@@ -166,6 +182,10 @@ interface FormDetails {
         questions?: QuestionResponse[];
     };
     completionTimeInSeconds?: number;
+    /** Caller-provided metadata attached to this submission (Dates already serialized to ISO strings) */
+    context?: Record<string, string | number | boolean>;
+    /** IDs of questions the user actually navigated to, in order. Used for drop-off analysis. */
+    visitedQuestionIds?: string[];
 }
 interface SubmitFormRequest {
     triggerType?: 'automatic' | 'manual';
@@ -233,6 +253,12 @@ declare class EncatchSDK {
     private _showFormById;
     dismissForm(formConfigurationId?: string): Promise<void>;
     private _pendingResponses;
+    /**
+     * Pre-fills a response before showing a form.
+     * @param questionId - The ID or slug of the question to prepopulate. When a slug
+     *   is provided the form engine resolves it to the matching question ID automatically.
+     * @param value - The value to set
+     */
     addToResponse(questionId: string, value: unknown): void;
     getPendingResponses(): Record<string, unknown>;
     clearPendingResponses(): void;
@@ -308,7 +334,7 @@ interface EncatchContextValue {
     showForm: (formId: string, options?: ShowFormOptions) => void;
     /** Call Encatch.dismissForm */
     dismissForm: (formConfigurationId?: string) => void;
-    /** Call Encatch.addToResponse */
+    /** Call Encatch.addToResponse. Accepts a question ID or slug. */
     addToResponse: (questionId: string, value: unknown) => void;
     /** Call Encatch.resetUser */
     resetUser: () => void;

package/dist/index.js

@@ -553,7 +553,8 @@ var EncatchSDK = class {
     // ============================================================================
     // Form response helpers
     // ============================================================================
-    // Pre-filled responses stored by addToResponse, sent with sdk:prefillResponses
+    // Pre-filled responses stored by addToResponse, sent with sdk:prefillResponses.
+    // Keys may be question IDs or slugs; the form engine resolves slugs to IDs.
     this._pendingResponses = {};
   }
   // ============================================================================
@@ -787,6 +788,13 @@ var EncatchSDK = class {
     var _a, _b, _c, _d, _e, _f, _g;
     const resetMode = (_a = options == null ? void 0 : options.reset) != null ? _a : "always";
     const triggerType = (_b = options == null ? void 0 : options.triggerType) != null ? _b : "manual";
+    const serializedContext = (options == null ? void 0 : options.context) ? Object.entries(options.context).reduce(
+      (acc, [key, value]) => {
+        acc[key] = value instanceof Date ? value.toISOString() : value;
+        return acc;
+      },
+      {}
+    ) : void 0;
     const deviceInfo = await this._buildDeviceInfo();
     const req = {
       formSlugOrId: formId,
@@ -811,7 +819,8 @@ var EncatchSDK = class {
         triggerType,
         prefillResponses,
         locale: (_f = this._locale) != null ? _f : void 0,
-        theme: this._theme
+        theme: this._theme,
+        context: serializedContext
       };
       if (this._onBeforeShowForm) {
         const allow = await Promise.resolve(this._onBeforeShowForm(payload));
@@ -827,7 +836,8 @@ var EncatchSDK = class {
         triggerType,
         prefillResponses: Object.keys(prefillResponses).length > 0 ? prefillResponses : void 0,
         locale: (_g = this._locale) != null ? _g : void 0,
-        theme: this._theme
+        theme: this._theme,
+        context: serializedContext
       });
       this._isFormVisible = true;
     } catch (err) {
@@ -864,6 +874,12 @@ var EncatchSDK = class {
     }
     this.emitEvent("form:dismissed", { formId: formConfigurationId != null ? formConfigurationId : "" });
   }
+  /**
+   * Pre-fills a response before showing a form.
+   * @param questionId - The ID or slug of the question to prepopulate. When a slug
+   *   is provided the form engine resolves it to the matching question ID automatically.
+   * @param value - The value to set
+   */
   addToResponse(questionId, value) {
     this._pendingResponses[questionId] = value;
   }
@@ -1626,11 +1642,12 @@ var EncatchWebView = () => {
       switch (type) {
         case "form:ready": {
           if (!formPayload) return;
-          const { formConfig, resetMode, triggerType, prefillResponses, locale, theme } = formPayload;
+          const { formConfig, resetMode, triggerType, prefillResponses, locale, theme, context } = formPayload;
           injectSDKMessage({
             type: "sdk:formConfig",
             data: __spreadProps(__spreadValues({}, formConfig), {
-              triggerType
+              triggerType,
+              context
             })
           });
           if (resetMode === "always") {
@@ -1681,7 +1698,9 @@ var EncatchWebView = () => {
               feedbackIdentifier: data.feedbackIdentifier,
               responseLanguageCode: data.responseLanguageCode,
               response: data.response,
-              completionTimeInSeconds: data.completionTimeInSeconds
+              completionTimeInSeconds: data.completionTimeInSeconds,
+              context: data.context,
+              visitedQuestionIds: data.visitedQuestionIds
             },
             $feedbackTransactions: void 0
           };

package/dist/index.mjs

@@ -522,7 +522,8 @@ var EncatchSDK = class {
     // ============================================================================
     // Form response helpers
     // ============================================================================
-    // Pre-filled responses stored by addToResponse, sent with sdk:prefillResponses
+    // Pre-filled responses stored by addToResponse, sent with sdk:prefillResponses.
+    // Keys may be question IDs or slugs; the form engine resolves slugs to IDs.
     this._pendingResponses = {};
   }
   // ============================================================================
@@ -756,6 +757,13 @@ var EncatchSDK = class {
     var _a, _b, _c, _d, _e, _f, _g;
     const resetMode = (_a = options == null ? void 0 : options.reset) != null ? _a : "always";
     const triggerType = (_b = options == null ? void 0 : options.triggerType) != null ? _b : "manual";
+    const serializedContext = (options == null ? void 0 : options.context) ? Object.entries(options.context).reduce(
+      (acc, [key, value]) => {
+        acc[key] = value instanceof Date ? value.toISOString() : value;
+        return acc;
+      },
+      {}
+    ) : void 0;
     const deviceInfo = await this._buildDeviceInfo();
     const req = {
       formSlugOrId: formId,
@@ -780,7 +788,8 @@ var EncatchSDK = class {
         triggerType,
         prefillResponses,
         locale: (_f = this._locale) != null ? _f : void 0,
-        theme: this._theme
+        theme: this._theme,
+        context: serializedContext
       };
       if (this._onBeforeShowForm) {
         const allow = await Promise.resolve(this._onBeforeShowForm(payload));
@@ -796,7 +805,8 @@ var EncatchSDK = class {
         triggerType,
         prefillResponses: Object.keys(prefillResponses).length > 0 ? prefillResponses : void 0,
         locale: (_g = this._locale) != null ? _g : void 0,
-        theme: this._theme
+        theme: this._theme,
+        context: serializedContext
       });
       this._isFormVisible = true;
     } catch (err) {
@@ -833,6 +843,12 @@ var EncatchSDK = class {
     }
     this.emitEvent("form:dismissed", { formId: formConfigurationId != null ? formConfigurationId : "" });
   }
+  /**
+   * Pre-fills a response before showing a form.
+   * @param questionId - The ID or slug of the question to prepopulate. When a slug
+   *   is provided the form engine resolves it to the matching question ID automatically.
+   * @param value - The value to set
+   */
   addToResponse(questionId, value) {
     this._pendingResponses[questionId] = value;
   }
@@ -1615,11 +1631,12 @@ var EncatchWebView = () => {
       switch (type) {
         case "form:ready": {
           if (!formPayload) return;
-          const { formConfig, resetMode, triggerType, prefillResponses, locale, theme } = formPayload;
+          const { formConfig, resetMode, triggerType, prefillResponses, locale, theme, context } = formPayload;
           injectSDKMessage({
             type: "sdk:formConfig",
             data: __spreadProps(__spreadValues({}, formConfig), {
-              triggerType
+              triggerType,
+              context
             })
           });
           if (resetMode === "always") {
@@ -1670,7 +1687,9 @@ var EncatchWebView = () => {
               feedbackIdentifier: data.feedbackIdentifier,
               responseLanguageCode: data.responseLanguageCode,
               response: data.response,
-              completionTimeInSeconds: data.completionTimeInSeconds
+              completionTimeInSeconds: data.completionTimeInSeconds,
+              context: data.context,
+              visitedQuestionIds: data.visitedQuestionIds
             },
             $feedbackTransactions: void 0
           };

package/package.json

@@ -5,14 +5,14 @@
     "type": "git",
     "url": "https://github.com/get-encatch/react-native-sdk"
   },
-  "homepage": "https://github.com/get-encatch/react-native-sdk#readme",
+  "homepage": "https://encatch.com",
   "bugs": {
     "url": "https://github.com/get-encatch/react-native-sdk/issues"
   },
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.3",
   "files": [
     "dist"
   ],