# Welcome to encatch Documentation (/docs)
## Introduction

encatch (en-catch) is a feedback platform that allows you to collect feedback from your users. You can seamlessly integrate it into your app or website using our SDKs.

## What is Next?

<Cards>
  <Card icon={<CodeIcon className="text-purple-300" />} title="Developer Guide" href="/docs/developer-guide" description="Learn how to get started with encatch integration in your app or website" />

  <Card icon={<CpuIcon className="text-purple-300" />} title="Administrative Guide" description="Learn how to manage your encatch account and projects" href="/docs/administrative-guide" />

  <Card icon={<CpuIcon className="text-purple-300" />} title="Framework Examples" description="Learn how to use encatch with different frameworks" href="/docs/framework-examples" />

  <Card icon={<CpuIcon className="text-purple-300" />} title="General FAQ" description="Frequently Asked Questions" href="/docs/general-faq" />
</Cards>


# encatch Admin Guide (/docs/administrative-guide)
## Introduction

encatch is a feedback platform that allows you to collect feedback from your users. You can seamlessly integrate it into your app or website using our SDKs.

This section provides high-level guide for setting up, configuring, and managing your encatch platform. Whether you're an organization owner, project admin, or team member, you'll find detailed instructions for every aspect of the system.

## Platform Hierarchy

The encatch platform follows a hierarchical structure that organizes your feedback collection and management:

<Mermaid
  chart="graph TD
    A[Organization] --> B[P1]
    A --> C[P2]
    A --> D[PN]

    B --> E[F1]
    B --> F[F2]
    B --> G[F3]

    C --> H[F1]
    C --> I[F2]

    D --> J[F1]
    D --> K[F2]

    E --> L[D1]
    E --> M[D2]
    F --> N[D1]
    F --> O[D2]
    G --> P[D1]
    G --> Q[D2]
    H --> R[D1]
    H --> S[D2]
    I --> T[D1]
    J --> U[D1]
    J --> V[D2]
    K --> W[D1]

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#f3e5f5
    style D fill:#f3e5f5
    style E fill:#e8f5e8
    style F fill:#e8f5e8
    style G fill:#e8f5e8
    style H fill:#e8f5e8
    style I fill:#e8f5e8
    style J fill:#e8f5e8
    style K fill:#e8f5e8
    style L fill:#fff3e0
    style M fill:#fff3e0
    style N fill:#fff3e0
    style O fill:#fff3e0
    style P fill:#fff3e0
    style Q fill:#fff3e0
    style R fill:#fff3e0
    style S fill:#fff3e0
    style T fill:#fff3e0
    style U fill:#fff3e0
    style V fill:#fff3e0
    style W fill:#fff3e0"
/>

#### Organizations

Organizations are the top-level entities in the encatch platform. They represent your company (or a group of companies in an enterprise setup) and provide a central point for managing your feedback collection and management across all projects / applications that you own.

#### P - Projects

Each project is like a container (logical isolation) for your application that you want to collect feedback from. You can choose to create one project for all channels like website, webapp, mobile app, etc (recommended). or create one project for each channel, if you have different teams handling different channels / want exclusive feedback management for each channel.

#### F - Feedback Collections

Feedback collections are the actual forms and surveys that collect user input. They can be embedded in your applications, websites, or distributed via various channels.

#### D - Data Pipelines

Currently, data pipelines include destinations such as email, Slack, Jira, GitLab, and webhook endpoints. They allow you to integrate the feedback received from your users into your existing tools and systems. You could use destinations are a means to notify or trigger workflows by calling the workflow webhooks.

## What is Next?

<Cards>
  <Card icon={<BuildingIcon className="text-purple-300" />} title="Organizations" href="/docs/administrative-guide/organization-management/overview" description="Set up your organization structure, manage team members, and configure role-based access control" />

  {" "}

  <Card icon={<FolderIcon className="text-purple-300" />} title="Projects" href="/docs/administrative-guide/project-management/overview" description="Create and manage projects, configure API keys, manage members, and control project settings" />

  {" "}

  <Card icon={<MessageSquareIcon className="text-purple-300" />} title="Feedback Management" href="/docs/administrative-guide/feedback-management/overview" description="Design feedback forms, configure targeting rules, and analyze responses throughout the feedback lifecycle" />

  {" "}

  <Card icon={<GitBranchIcon className="text-purple-300" />} title="Integrations & Notifications" href="/docs/administrative-guide/data-pipelines/overview" description="Connect feedback to your tools with email notifications and database storage" />
</Cards>


# Quick Start (/docs/developer-guide)
## Get Started in Minutes

Encatch provides everything you need to build, deploy, and scale your applications. Whether you're integrating our SDK, setting up data pipelines, working with APIs, or implementing AI features, we've got you covered.

***

## 🚀 Choose Your Starting Point

### 📦 SDK Guide

**Get up and running with the Encatch SDK**

Learn how to integrate our JavaScript/TypeScript SDK into your applications. This section covers installation and setup, configuration options, authentication methods, core SDK features and methods, code examples and best practices, and advanced configuration options.

Perfect for developers who want to integrate Encatch functionality directly into their web applications.

**[Explore SDK Guide →](/docs/developer-guide/sdk-guides/web)**

***

### Administrative Guide

**Manage your organization, projects, feedback forms, and data pipelines**

Learn how to manage your organization, projects, feedback forms, and data pipelines in the application. This section includes organization management, project management, feedback management, and data pipeline management.

**[Learn Administrative Guide →](/docs/administrative-guide)**

***

### 🔗 Data Pipelines

**Build robust data processing workflows**

Create and manage scalable data pipelines for your applications. This section includes pipeline architecture overview, data ingestion methods, transformation and processing, output destinations and formats, monitoring and debugging, and performance optimization.

Ideal for teams working with large datasets and complex data workflows.

**[Learn Data Pipelines →](/docs/developer-guide/data-pipelines/destination)**

***

*Ready to gather feedback for your users and take action on it? Pick a section above and start your Encatch journey today!*


# Rate Limits (/docs/developer-guide/rate-limits)
We enforce rate limits to prevent abuse and ensure that the APIs (called from SDKs for feedback fetching and submission) is used fairly by all users.

### Rate Limit Enforcement

The rate limits are applied on a combination of user's IP address and API key generated for the environment (test or production). The following table shows the rate limits for different API endpoints for each environment:

|  Endpoint Name                 | Test Environment | Production Environment |
| ------------------------------ | ---------------- | ---------------------- |
|  List elligible feedback forms | 10 RPM           | 200 RPM                |
|  Get feedback questions        | 10 RPM           | 80 RPM                 |
|  Submit Feedback               | 5 RPM            | 40 RPM                 |
|  Audit feedback viewed         | 5 RPM            | 80 RPM                 |
|  Open sharable link            | 5 RPM            | 200 RPM                |
|  AI obfuscation                | 5 RPM            | 24 RPM                 |
|  All other requests            | 5 RPM            | 50 RPM                 |

<Callout type="info">
  RPM means requests per minute.
</Callout>

#### Rate Limit Headers

When you make requests to the API, you'll receive rate limit information in the response headers:

* `X-RateLimit-Limit`: The maximum number of requests allowed per time window
* `X-RateLimit-Remaining`: The number of requests remaining in the current time window
* `X-RateLimit-Reset`: The time at which the current rate limit window resets (Unix timestamp in seconds)

#### Handling Rate Limits

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response. You should:

1. Wait for the rate limit window to reset
2. Implement exponential backoff in your application
3. Consider caching responses to reduce API calls

#### Best Practices

* Monitor your rate limit usage through the response headers
* Implement proper error handling for 429 responses
* Use caching to minimize API calls
* Reach out to us if your usecase requires customized rate limits


# Test Mode (/docs/developer-guide/test-mode)
Test Mode allows you to preview and validate your feedback forms before deploying them to production.

It helps ensure that everything works correctly across different devices, browsers, and trigger configurations—without polluting real feedback data.

***

### Why Use Test Mode?

* **Keep production reports clean:** Test submissions won’t appear in your production analytics or reports.
* **Save credits:** Actions performed in test mode (such as viewing or submitting feedback or pipelines) do not consume production credits.
* **Validate end-to-end flows:** Test all trigger types, integrations, and UI behavior before a public launch.

***

### How to Enable Test Mode

1. **Generate a Test API Key**
   * Go to your project’s **API Keys** section.
   * When creating a new key, select **Test** in the **Environment** dropdown.
   * Use a clear **Application Name** to identify test instances (e.g., `test-app-1`, `test-app-2`, etc.).

2. **Configure Feedback Form (Auto Trigger)**
   * In the feedback form configuration, map the **application names** associated with test keys.
   * This ensures that forms can be auto-triggered in test environments.

3. **Set Up SDK Configuration**
   * For both Auto and Manual triggers, use the **test API key** in your SDK setup.

<Callout title="Notes" type="info">
  1) Test Mode does not consume production credits.
  2) Feedback actions such as submission or viewing, and data pipelines, are excluded from production usage.
</Callout>

<Callout title="Important" type="warning">
  * Test Mode has lower rate limits than production.
  * Avoid including test keys in your production build / bundles / deployments.
</Callout>

### Rate Limits in Test Mode

Refer to the [Rate Limits](/docs/developer-guide/rate-limits) guide for specific limits applied in Test Mode.

***

### What Is Covered in Test Mode?

* Feedback form configuration (Auto trigger) mapped to test application names
* Summary and reports for feedbacks received via test applications
* Feedback reports (Audience Overview, Response Summary, Individual Reports, Export, Destinations)
* Data pipelines enabled under test mode (not counted toward usage)

<Callout type="info">
  1. When manually triggered, a feedback form can open in both production and test mode.
  2. **AI-powered message APIs** are always counted under production usage. Test Mode does not apply to AI messages.
</Callout>

***

## Switching Back to Production Mode

1. Go to your project’s **API Keys** section.
2. Generate a new API key and select **Production** in the **Environment** dropdown.
3. Update your **Feedback Form Configuration** to map production application names.
4. Update your **SDK configuration** to use the production API key.


# Hello World 22 (/docs/framework-examples/hello)
hello world22


# Overview (/docs/framework-examples)
hello world ss


# General FAQ (/docs/general-faq)
### General FAQ

<Accordions type="single">
  <Accordion title="Who is organization owner and how to change it?">
    <p>
      The organization owner is the user who has created the organization. To change the organization owner, you need to contact us at 

      [support@encatch.com](mailto:support@encatch.com)

      .
    </p>
  </Accordion>

  <Accordion title="How to delete the organization?">
    <p>
      To delete the organization, you need to contact us at 

      [support@encatch.com](mailto:support@encatch.com)

      .
    </p>
  </Accordion>

  <Accordion title="How to add a new member to the organization?">
    <p>
      You can add a new member to the organization by going to the 

      **organization**

       menu in your dashboard and clicking the add member button. You can add a new member to the organization by clicking the add member button.
    </p>
  </Accordion>

  <Accordion title="What counts as AI API calls?">
    <p>
      AI API calls are the calls made to the AI API endpoints when using the application.
    </p>

    <ul>
      <li>
        AI Generated Feedback form creation
      </li>

      <li>
        AI Obfuscation
      </li>

      <li>
        External Insights chats and report generation
      </li>

      <li>
        AI Filtering in destination
      </li>

      <li>
        Question translations generated using AI
      </li>

      <li>
        AI translation of qualitative responses
      </li>
    </ul>
  </Accordion>

  <Accordion title="What counts as data pipeline triggers?">
    <p>
      Data pipeline triggers are the triggers that are used to trigger the data pipeline.
    </p>

    <ul>
      <li>
        When a destination is configured for feedback form submission (irrespective of the message is sent to destination or dropped in the filter process)
      </li>

      <li>
        All other data pipeline processes where AI is explicitly mentioned in the triggers
      </li>
    </ul>
  </Accordion>
</Accordions>

#### Other documents and questions:

1. Billing FAQ, click [here](/docs/administrative-guide/billing/billing-faq) for more details.
2. Referrals FAQ, click [here](/docs/administrative-guide/referrals/referrals) for more details.
3. Rate Limiting, click [here](/docs/developer-guide/rate-limits) for more details.
4. Test Mode, click [here](/docs/developer-guide/test-mode) for more details.
5. Privacy Policy, click [here](/docs/administrative-guide/legal/privacy-policy) for more details.
6. Terms of Service, click [here](/docs/administrative-guide/legal/terms-of-service) for more details.


# Billing FAQ (/docs/administrative-guide/billing/billing-faq)
<Accordions type="multiple">
  <Accordion title="How to check my usage and plan limits?">
    <p>
      You can check your usage and plan limits by going to the 

      **billing**

       menu which is available in the left sidebar in your dashboard.
    </p>
  </Accordion>

  <Accordion title="When is my upgrade effective?">
    <p>
      Your upgrade will be effective immediately. 
    </p>
  </Accordion>

  <Accordion title="When is my downgrade effective?">
    <p>
      Your downgrade will be effective after the current billing cycle ends (for which you have already been charged). 
    </p>
  </Accordion>

  <Accordion title="How to upgrade or downgrade my plan?">
    <p>
      You can upgrade or downgrade your plan by going to the 

      **billing**

       menu which is available in the left sidebar in your dashboard.
    </p>
  </Accordion>

  <Accordion title="Refund Policy?">
    <p>
      We do not offer refunds. If you are not satisfied with Encatch, you can cancel your subscription at any time. Scheduled payments will not be deducted.
    </p>
  </Accordion>

  <Accordion title="Can I cancel my subscription?">
    <p>
      Yes, you can cancel your subscription at any time by going to the billing page in your dashboard and clicking the cancel subscription button. You'll continue to have access to your account until the end of your current billing period / expiry of your already paid plan.
    </p>
  </Accordion>

  <Accordion title="What happens if i dont renew my subscription?">
    <p>
      If you don't renew your subscription, you will be automatically downgraded to the free plan and you will lose access to all the features of the current plan which you were on.
    </p>
  </Accordion>

  <Accordion title="Do you offer upfront payments?">
    <p>
      Yes, we do offer upfront payments so that you can try out the features of the corresponsding plans. You can purchase a plan for a upfront payment and you will have access to the features of the plan for the duration of the payment.
    </p>
  </Accordion>
</Accordions>


# Destinations (/docs/administrative-guide/data-pipelines/destinations)
Using AI filter you can decide which feedback data to filter before it is sent to the destination. An example usecase is send feedback notifications only if rating is 3 or below.

#### Available Destinations

* Email
* Slack
* Jira
* GitLab
* Custom Webhook (that can be used with Zappier,n8n, MS power automate, etc. or your own custom webhook endpoint)


# Filters (/docs/administrative-guide/data-pipelines/filters)
### Example use cases

* Filter out feedback from specific users based on their email, department, role, etc.
* Filter out feedback from specific devices based on their device id, device type, device model, etc.
* Filter out feedback from based on responses captures, such as someone entering junk text in a text field.

<Callout type="info">
  This feature is coming soon.
</Callout>


# Transformations (/docs/administrative-guide/data-pipelines/transformations)
### Example use cases

* Mask IP address
* Transform URLs into simpler formats

<Callout type="info">
  This feature is coming soon.
</Callout>


# Additional Settings (/docs/administrative-guide/feedback-management/additional-settings)
When you create API key, they are associated with your defined app names. To provide best and fast experience we cache feedback configurations for specific app names.

## Configuration Settings

Below settings are available to configure:

* **Config sync interval**: The interval at which the config sync will be performed by your SDK for any changes in your feedback configurations.
* **Feedback frequency**: A global setting to control the frequency between two feedback forms being displayed to your users, unless a form is marked as important.
* **Disable all feedback forms**: A global setting to disable all feedback forms from being displayed to your users for this specific app name.

<Callout type="info">
  The disable all feedback forms does not disable the feedback forms for other app names.
</Callout>

## Cache Management

* When you make changes to already created feedback forms, you can clear the cache for a specific app name by clicking the clear cache button, so that during next cycles of config sync, your SDK will fetch the latest feedback configurations.
* If your changes are not immediately needed, you dont need to perform this step since the cache will be cleared automatically after 15 minutes.

<Callout type="info" title="Usecase of disabling all feedback forms">
  Suppose your app is active for multiple channels(android - MYAPP\_ANDROID, ios - MYAPP\_IOS, web - MYAPP\_WEB) and you want to temporarily disable feedback forms for web then you can use this feature to disable all feedback forms for web where you have defined the app name as MYAPP\_WEB, during API key creation.
</Callout>


# API Keys (/docs/administrative-guide/feedback-management/api-keys)
## Managing API Keys

API keys are essential for integrating encatch feedback collection into your applications. They provide secure authentication between your application and the encatch platform.

### Understanding API Keys

Each API key consists of:

* **Name**: A descriptive identifier for your reference.
* **Key Prefix**: Helps you identify the generated key with the key name
* **Expiry Date**: When the key will automatically expire
* **Application Name**: The app names for which the key is valid. This is used to link which feedback forms are linked.
* **Environment**: The environment for which the key is valid. Test keys are used for testing purposes and are not counted towards your usage.
* **Allowed Domains**: The domains (for website it is the domain name and for mobile app it is the bundle id) for which the key is valid. This is used to restrict the key to only be used on specific domains.

<Callout type="warning">
  Use **\*** Asterisk to generate a key for all domains. Not recommended for production environments.
</Callout>

<Callout type="info" title="Important Notes">
  * System does not store the generated key. Incase you lose the key, you can generate a new key and use it in your application and delete the old key, keeping the application name same.
  * Keep **application name** same across two keys which are  meant for same purpose when old key is about to expire.
  * API keys are public when embedded in public websites. We apply rate limits to prevent abuse and ensure that the APIs (called from SDKs for feedback fetching and submission) is used fairly by all users. For information on rate limits, refer to the [Rate Limits](/docs/developer-guide/rate-limits) guide.
</Callout>

### Permissions

Permissions are associated with the API key and are used to control the actions that can be performed with the key.

1. **Users**: Manage users who can use the key.
   * **create**: Use create permission if you want to add a new user using the key.
   * **delete**: Use delete permission if you want to remove a user using the key.
   * **update**: Use update permission if you want to update the users using the key.
   * **read**: Use read permission if you want to view the users information using the key.
2. **Feedback Forms**: Manage feedback forms that can be used with the key.
   * **create**: Use create permission if you want to submit feedback using the key.
   * **read**: Use read permission if you want to read feedback configurations using the key.

<Callout type="warning" title="Important Notes on Permissions">
  * When creating API keys for frontend SDK's you enable create and update permissions, so that new users created in your application are automatically synced with encatch users in the current project.
  * You would chose not to enable the create permission if you have fixed users and prefer to sync from backend directly. Example,employee based applications where users are managed by HRMS.
  * When creating API keys for website (no login applications) you disable all user permissions, so that no one can create users, but can only submit feedback anonymously.
</Callout>


# Form Creation & Customization (/docs/administrative-guide/feedback-management/form-creation)
## Creating Feedback Forms

encatch provides a powerful visual form builder and pre-built templates to help you create effective feedback forms quickly.

### Getting Started

You can chose to create a feedback form using;

1. Pre-built templates
2. AI form builder
3. Start from scratch

All options allow you to fully manually customize the form to your needs before launching it.

### Features

1. **Multi-page support**: Either have one question per page or multiple questions per page. One question per page is recommended for best user experience for in-app feedback. For sharable link based feedback forms, you could chose to have multiple questions per page.
2. **Question types**: You can choose from a variety of question types including multiple choice, short answer, long answer, rating, and more.
3. **Multi-lingual support**: You can translate the form into different languages using AI's contextual understanding or translate it manually.
4. **Mobile-responsive**: The form is responsive and is build for all resolution.
5. **Dark mode**: The form is available in light and dark mode.
6. **Branding**: You can brand the form with your brand colors.

### Advanced customization options:

1. **Custom CSS**: You can add link to your own CSS file to override the default styles when basic branding options are not enough.
2. **Popup position**: You can choose to position the form in the top right, top left, bottom right, bottom left, center of the screen, or in a custom position.

### Frequency & Scheduling options:

Control when and how often your feedback forms appear to users:

**Feedback Frequency Types:**

* **Single-use**: One-time display per user, best for major campaigns
* **Recurring**: Periodic display with customizable intervals (days/weeks/months)
* **Only Show Once**: Prevents re-display even if dismissed without completion

**Scheduling Controls:**

* **Start Feedback**: Immediately or custom date/time
* **Stop Feedback**: Never (continuous) or custom end date
* **Stop Responses**: Set maximum response limits

### Targeting & Triggering options:

Control who sees your feedback forms and when they appear:

**Trigger Modes:**

* **Auto Trigger**: Automatic display based on configured conditions
* **Manual Trigger**: Programmatic control via JavaScript API for custom events

**Auto Trigger:**
Set triggers based on:

* **Time on Page**: After X seconds
* **Scroll Depth**: When user scrolls Y% (You need to define the element and pass scrolled percentage in your code.)
* **Custom Events**: Based on custom events you define in your code.
* **Page Views**: When user visits specific page url.

**Audience Targeting (WHO):**

* **User Types**: Everyone, logged-in users only, anonymous users only, or custom segments
* **User Filters**: Demographics, behavior, account type, custom attributes
* **Priority Levels**: High priority (bypasses frequency rules) or standard priority

**Application Targeting (WHERE):**

* **Platforms**: Web applications, mobile apps, desktop apps, browser extensions
* **Device Filters**: Desktop, mobile, tablet, smart TV
* **Operating Systems**: Windows, macOS, iOS, Android, Linux


# Overview (/docs/administrative-guide/feedback-management/overview)
## Introduction

Feedback Management in encatch provides a comprehensive suite of tools to collect, analyze, and act on user feedback. From creating customized feedback forms to setting up sophisticated targeting rules, you have complete control over how and when you engage with your users.

## Next Steps

<Cards>
  <Card icon={<BuildingIcon className="text-purple-300" />} title="Form Creation & Customization" href="/docs/administrative-guide/feedback-management/form-creation" description="Learn how to create and customize feedback forms in encatch" />

  <Card icon={<BuildingIcon className="text-purple-300" />} title="Reports & Export" href="/docs/administrative-guide/feedback-management/reports" description="Learn how to monitor, analyze, and understand feedback data in encatch" />

  <Card icon={<BuildingIcon className="text-purple-300" />} title="Additional Settings" href="/docs/administrative-guide/feedback-management/additional-settings" description="Learn how to configure additional features in encatch" />

  <Card icon={<BuildingIcon className="text-purple-300" />} title="Feedback Destinations" href="/docs/administrative-guide/feedback-management/feedback-destinations" description="Learn how to configure feedback destinations in encatch" />

  <Card icon={<BuildingIcon className="text-purple-300" />} title="API Keys" href="/docs/administrative-guide/feedback-management/api-keys" description="Learn how to manage API keys in encatch" />

  <Card icon={<BuildingIcon className="text-purple-300" />} title="Users" href="/docs/administrative-guide/feedback-management/users" description="Learn how to manage users in encatch" />
</Cards>


# Reports & Export (/docs/administrative-guide/feedback-management/reports)
## Overview of Feedback Reports

Encatch provides three comprehensive reporting views to help you understand and analyze your feedback data:

1. **Audience Analytics**: Provides insights about your audience and how they're engaging with your feedback forms.

2. **Response Summary**:
   Provides insights about what users are saying and question-level insights.

3. **Individual Responses**:
   Provides detailed insights into each user's feedback.

Each report provides filters that help you narrow down the data to your specific needs example date filters.

## Export Report

The Export Report feature enables you to download feedback data for offline analysis, reporting, and integration with other tools.

## Realtime Feedback Notifications

The destination feature in encatch allows you to filter and chose which individual user feedback you would like to be notified about.

Few available destinations are:

* Email
* Slack
* Jira
* GitLab
* Custom Webhook (that can be used with Zappier,n8n, MS power automate, etc.)

Some usecase for this feature are:

* You want to be notified about negative feedback from your users.
* You want to be notified about feedback from your users about a specific bug.


# Response Summary (/docs/administrative-guide/feedback-management/response-summary)
## Analyzing Response Data

The Response Summary provides detailed insights into how users are answering your feedback questions, helping you understand patterns and extract actionable insights.

### Overview Metrics

Track key performance indicators for your feedback form:

#### Response Statistics

* **Total Responses**: Number of completed submissions
* **Response Rate**: Percentage of users who complete vs view
* **Completion Time**: Average time to finish the form
* **Drop-off Points**: Where users abandon the form

### Question-Level Analytics

Dive deep into individual question performance:

#### Response Distribution

For each question, view:

* **Response Count**: How many users answered
* **Skip Rate**: Percentage who skipped (if optional)
* **Response Types**: Distribution of answers

#### Chart Types

Visualize data using appropriate formats:

##### Pie Charts

* **Best For**: Single-choice questions
* **Shows**: Percentage distribution
* **Example**: Yes/No questions, satisfaction ratings

##### Bar Charts

* **Best For**: Multiple choice, rankings
* **Shows**: Comparative volumes
* **Example**: Feature preferences, priority lists

##### Donut Charts

* **Best For**: Categories with sub-options
* **Shows**: Hierarchical data
* **Example**: Department feedback, nested choices

### Filtering and Segmentation

Customize your analysis with advanced filters:

#### Time Period Filters

* **Date Range**: Select specific time periods
* **Comparison**: Compare different periods
* **Trends**: Track changes over time

#### Add Conditions

Filter responses by:

* **User Segments**: Demographics, behavior
* **Response Values**: Specific answers
* **Metadata**: Device, location, source

#### Add Breakdowns

Segment data by:

* **User Attributes**: Age, plan type, etc.
* **Response Groups**: Satisfaction levels
* **Time Periods**: Daily, weekly, monthly

#### Behavior Filters

Analyze based on user actions:

* **Completion Status**: Full vs partial
* **Response Time**: Fast vs slow responders
* **Interaction Pattern**: Linear vs non-linear

### Interpreting Results

Transform raw data into insights:

#### Rating Questions

For satisfaction or NPS questions:

* **Average Score**: Overall satisfaction level
* **Distribution**: Spread of ratings
* **Trends**: Improvement or decline
* **Segments**: Which groups are happiest

**Action Items**:

* Address low-score feedback
* Identify improvement areas
* Celebrate high ratings
* Track progress over time

#### Multiple Choice Questions

For preference or feature questions:

* **Popular Choices**: Most selected options
* **Unexpected Results**: Surprising preferences
* **Missing Options**: Write-in responses
* **Correlations**: Related answer patterns

**Applications**:

* Product roadmap prioritization
* Resource allocation decisions
* Marketing message refinement
* User persona validation

#### Open-Ended Responses

For text-based feedback:

* **Theme Analysis**: Common topics
* **Sentiment Tracking**: Positive vs negative
* **Keyword Frequency**: Repeated terms
* **Actionable Feedback**: Specific suggestions

**Processing Tips**:

* Export for detailed analysis
* Use text analytics tools
* Categorize manually for accuracy
* Share verbatim quotes internally

### Advanced Analytics

#### Cross-Question Analysis

* **Answer Correlation**: How questions relate
* **Path Analysis**: Response sequences
* **Segment Profiles**: Group characteristics
* **Predictive Indicators**: Future behavior clues

#### Statistical Significance

* **Sample Size**: Ensure adequate responses
* **Confidence Intervals**: Margin of error
* **P-Values**: Statistical validity
* **Effect Size**: Practical importance

### View Detailed Metrics

Expand analysis capabilities:

#### Detailed Metric Views

Access additional data:

* **Response Timestamps**: When submitted
* **Completion Paths**: Navigation flow
* **Edit Patterns**: Changed answers
* **Device Analytics**: Platform details

#### Export Options

* **Raw Data**: CSV for custom analysis
* **Summary Reports**: PDF presentations
* **API Access**: Programmatic retrieval
* **Real-time Feeds**: Live data streams

### Best Practices

#### Regular Analysis

* **Daily Monitoring**: Active campaigns
* **Weekly Reviews**: Ongoing feedback
* **Monthly Reports**: Trend analysis
* **Quarterly Planning**: Strategic insights

#### Data Quality

* **Remove Duplicates**: Clean data sets
* **Filter Test Data**: Exclude internal tests
* **Validate Responses**: Check for quality
* **Handle Missing Data**: Appropriate methods

#### Actionable Insights

* **Prioritize Findings**: Focus on impact
* **Share Results**: Stakeholder communication
* **Track Actions**: Monitor improvements
* **Close the Loop**: Inform users of changes

### Common Analysis Scenarios

#### Product Feedback

* Feature request prioritization
* Usability issue identification
* Satisfaction trend tracking
* Competitive positioning

#### Customer Experience

* Journey pain points
* Service quality metrics
* Channel preferences
* Support effectiveness

#### Market Research

* Segment identification
* Preference mapping
* Price sensitivity
* Brand perception

### Integration with BI Tools

Connect response data to your analytics stack:

* **Export Formats**: CSV, JSON, API
* **Scheduling**: Automated exports
* **Data Warehouse**: ETL pipelines
* **Visualization**: Tableau, PowerBI

### Troubleshooting

Common issues and solutions:

* **Missing Responses**: Check question logic
* **Skewed Data**: Verify sampling method
* **Low Completion**: Analyze drop-off points
* **Export Errors**: Check data volume limits


# User Management (/docs/administrative-guide/feedback-management/users)
Users in encatch are your application users (end users) who interact with your application and provide feedback.

<Callout type="warning" title="Understanding Users vs Members">
  * **Users**: End users of your application who submit feedback. Your users can scoped to the project level. Therefore, same user in two projects are counted as two different users.
  * **Members**: Administrators who manage the project and have access to the portal.
</Callout>

### User Attributes

You can configure users atrributes like email, department, role, etc. to help you filter and analyze feedback data. User attributes are broken into 3 types

**Pre-configured attributes**: Attributes that are pre-defined by you, that are filterable in the portal.

* Examples include: email, department, role, etc.

**Dynamic attributes**: Attributes that are not planned in advance and are created on the fly from your code.

* Examples include: custom attributes, traits, etc.

**System attributes**: Attributes that are pre-defined by the system and are not editable by you.

* Examples include: user\_name, last\_seen, first\_seen, created\_at, updated\_at, etc.

### Manage Users

You can manage (create, view,edit,delete) users in the portal.

* Individually
* Bulk upload
* Sync from your backend using API keys (Comming soon)

<Callout type="info" title="Important Notes">
  - **user\_name** field should be unique for each user in the project.
  - When chosing to create a user from SDK, ensure that this field is not easily guessable or reproducible.
  - Only configure user fields which are useful for you to create filters and segments in the portal.
  - To protect users information, the API SDK cannot send back the user fields to your frontend application. Unless explicitly configured to show certain fields where dynamic attribute of users data is shown in your form. Example, a question like, "How has **\{\{user\_f\_name}}** been expereincing the app?"
</Callout>


# External Insights (/docs/administrative-guide/feedback-studio/external-insights)
External insights allows you to load feedback data from your external tools using csv format and then analyze it using AI.

### How to use External Insights

1. Go to the **Feedback Studio -> External Insights**
2. Upload your csv file which includes the feedback data you want to analyze.
3. Verify the sample loaded data is correct.
4. Start asking questions about the feedback data.
5. Once you are satisfied with the results, you can ask AI to generate a report in HTML format.
6. You can further enhance the report by asking AI to add additional data points to the report.
7. The report is self contained HTML which you can save as a file and share with your team members or modify further manually as needed.

### Example use cases

* You want to analyze the feedback data from social accounts like Twitter, Instagram, Youtube, Glassdoor, etc.
* Existing reports from encatch are not enough to answer your questions, you can export that data to a csv file and analyze it using External Insights.


# Privacy Policy (/docs/administrative-guide/legal/privacy-policy)
## Privacy Policy

This privacy policy explains how we collect, use, and share your personal information when you use our services.

### Information We Collect

We collect information from you when you register on our site, place an order, subscribe to our newsletter, respond to a survey or fill out a form.


# Terms of Service (/docs/administrative-guide/legal/terms-of-service)
## Terms of Service

This terms of service explains how we collect, use, and share your personal information when you use our services.

a sadas d


# Referrals (/docs/administrative-guide/referrals/referrals)
We believe in the power of community and we want to reward you for referring and continuous educating your users about encatch and potential benefits of using it.

### Referral Program Rules and Guidelines

<Callout type="info" title="Who can refer?">
  1. Only users who have purchased a paid plan can refer new users.
  2. Your referral codes are applicable till the code expiry period / no of times
     the code is used (You can view this information in the **billing page -> referrals**).
  3. If you discontinue your subscription, your referral code will be temporarily disabled (and not elligible for commissions) until you have an active subscription again.
</Callout>

<Accordions type="multiple">
  <Accordion title="How to refer a user to encatch?">
    <p>
      You can refer a user by sharing the referral link with them (generated from your 

      **billing page -> referrals**

      ). When the user signs up and purchases a paid plan anytime in the future, you will earn a commission.
    </p>
  </Accordion>

  <Accordion title="Will referral code be automatically shown on subscription page?">
    <p>
      If the user had clicked on your referral link, the referral code will be automatically shown on the subscription page during renewals. User can chose to manually enter / edit the referral code if they want to.
    </p>
  </Accordion>

  <Accordion title="Is referrals one time or recurring?">
    <p>
      Referrals are recurring. You will earn a commission for as long as the user
      you referred is a customer of encatch and on renewal chose to use your
      referral code. If they update with someone else's referral code, you will no
      longer be eligible for commissions.
    </p>
  </Accordion>

  <Accordion title="How much can I earn?">
    <p>
      You will earn a commission of % percentage of the purchase amount of the new user (This percentage is shown to you while creating the referral code). The commission is paid in the form of payout which can be requested via email.
    </p>
  </Accordion>

  <Accordion title="How to view my estimated earnings?">
    <p>
      You can view your estimated earnings by going to the 

      **referrals**

       menu in your dashboard and clicking the view estimated earnings page. You can see the estimated earnings amount where subscription for current billing month is already paid for.
    </p>
  </Accordion>
</Accordions>

## Payout FAQ

<Accordions type="multiple">
  <Accordion title="How to request a payout?">
    <p>
      At the moment, you can request a payout only via email. Please send an email to 

      [support@encatch.com](mailto:support@encatch.com)

       with your payout request amount and the payment method you want to be paid in.
    </p>
  </Accordion>

  <Accordion title="How will I be paid?">
    <p>
      You will be paid via Paypal / Payoneer. You can request a payout at any time by going to the 

      **referrals**

       menu in your dashboard and clicking the request payout button.
    </p>
  </Accordion>

  <Accordion title="How often will I be paid?">
    <p>
      You are eligible for payout 15 days after the user has consumed current billing month's subscription. You can request a payout of maximum once in a month and once minimum payout amount is $100. Payout requests will be processed within 25 business days.
    </p>
  </Accordion>

  <Accordion title="How much will be deducted during payout?">
    <p>
      During payout, an applicable deduction as per the payment provider charges will be deducted from the payout amount.
    </p>
  </Accordion>

  <Accordion title="How to view my payout history?">
    <p>
      You can view your payout history by going to the 

      **referrals**

       menu in your dashboard and clicking the view payout history page. You can see the list of payouts you have received.
    </p>
  </Accordion>
</Accordions>

#### Program Terms and Conditions

<Callout type="warning">
  **Encatch's Rights and Discretion:**

  Encatch reserves the right to reverse any final referral decisions, modify the referral program terms, conditions, and benefits at its sole discretion. This includes but is not limited to:

  * Reversing referral commissions that have been awarded
  * Modifying commission rates and payout structures
  * Changing eligibility requirements for referrals
  * Suspending or terminating elligible users' referral accounts
  * Updating program rules and guidelines

  Any modifications to the referral program will be communicated to elligible users through appropriate channels. Continued participation in the referral program constitutes acceptance of any such changes.
</Callout>


# Members (/docs/administrative-guide/system-setup/members)
### Inviting Team Members

* Only users with appropriate permissions can invite new members to the organization or project level.
* By inviting member at organization level you grant them across all projects (based on scopes defined in that role).
* By inviting member at project level you grant them only to that project.
* People you are invite are auto accepted to the organization and project. If a user has previously not joined encatch, you will see **invited** status in the members list. If the invited member has already joined encatch, you will see **active** status in the members list.
* An invitation email is sent to the invited member to join the organization / project.

<Callout type="info" title="Important Notes">
  - Any member assigned at organization level cannot be added as a member at project level and vice versa.
  - If you want to add a member at project level, you need to remove them from the organization level first.
  - If you want to remove a member from a project, you need to remove them from the organization level first.
  - Organization owner will have access to all organization and project level features and cannot be removed from the organization.
  - A user can be added as organization admin in multiple organizations but will be owner of only one organization.
</Callout>

### Enterprise Feature

Enterprises have the flexibility to send invitation emails from their own email domain or use encatch's email domain with custom branding and mail content.


# Organization & Projects (/docs/administrative-guide/system-setup/overview)
## Platform Hierarchy

The encatch platform follows a hierarchical structure that organizes your feedback collection and management:
read about the platform hierarchy [here](/docs/administrative-guide#platform-hierarchy).

## Organization / Project Management

* Use the **Manage** option in the sidebar to access the organization and project management page. The page will show you the list of organizations and projects you have access to.
* Roles and permissions (for orgnization and projects level) are created / managed at the organization level only.
* Members can be chosen to be invited at organization level or at project level.

#### Important Notes:

* One email address can only be associated with one organization as owner.
* At present, reassigning organization owner to a different user is restricted from admin portal as self service. Contact us for such requests.
* You can only access the organization and project management page if you have the **Manage** permission.
* Every new user registration on the encatch admin portal automatically creates an organization, with the registering user becoming the organization owner.


# Role & Permissions (/docs/administrative-guide/system-setup/roles-permissions)
## Roles and permissions

Roles define what actions users can perform within the organization and projects. Permissions can be customized at both the **organization level** and the **project level**.

#### Default Roles

* By default, a organization admin role is created with all permissions at organization level. This role cannot be deleted or modified.

#### Custom Roles

You can create custom roles to meet your organizational and project needs.

* When creating a new role at organization level, you can choose to limit the role with permissions at organization level or across projects.

<Callout type="info" title="Important Notes">
  - Organization admin role cannot be deleted or modified.
  - Organization Owner (the user who creates the organization) is automatically added as an organization admin and cannot be removed.
</Callout>

#### Example of custom roles:

* You may create a role as system admin, which will have access to organization level features that allow to manage roles and member invitations only.
* You may create a project level role as feedback management who has access to view and manage feedback within the project.
* You may create a project level role as integration manager who has access to manage data pipelines within the project, since these contain sensitive information and may need to be managed by a dedicated team.


# Encatch with LLMs (/docs/developer-guide/ai-guides/llms)
### Full Global Context:

You can use the [llms-full.txt](/llms-full.txt) file to get updated code suggestions to easily integrate with your LLM / vibe coding tools.

This link covers the full documentation of the Encatch API and SDKs including administrative guide.

### Page Specific Context:

If you would like to get only a page specific context you can

1. Choose **Copy Markdown** option from the page actions (Below the page title).
2. From page actions, choose **Open** with your favorite LLM like Claude, ChatGPT, etc (Below the page title).
3. append the current url with **.mdx** (dot mdx extension). Example: **[docs/developer-guide/ai-guides/llms](/docs/developer-guide/ai-guides/llms)** -> **[docs/developer-guide/ai-guides/llms.mdx](/docs/developer-guide/ai-guides/llms.mdx)**


# User API Guide (/docs/developer-guide/api-guides/user-api-guides)
### Overview

The UI uses a small set of REST endpoints via internal fetch hooks (for example `useGetConnectors`, `useGetDestinations`, `useCreateDestination`, `useEnableDestination`, `useDeleteDestination`). Each hook delegates to backend URLs configured in `modulePermissions.*` (see code for exact url/method values used in your deployment).

> Note: The examples below use generic routes and shapes. Replace `BASE_URL` and paths with the actual `modulePermissions.*` URLs from your environment.

***

### Auth & headers

The UI sends standard headers (see `@encatch/-constants/headers`) and relies on session/auth middleware. A typical header set looks like:

```http
Authorization: Bearer <access_token>
Content-Type: application/json
X-Engage-Org: <organizationId>
X-Engage-Project: <projectId>
```

Use the existing `useEngageFetchApi()` wrapper in UI code to match the project's auth flow.

***

### List connectors (pre-configured templates)

Purpose: fetch connector templates (Slack, webhook, email, gitlab, jira, ...)

Query params commonly supported:

* page (number) — 1-indexed
* page\_size (number)
* purpose (optional) — purpose filter (R/B/P)

Example request (GET):

```http
GET BASE_URL/pre-configured-connectors?page=1&page_size=20
Authorization: Bearer <token>
```

Example JSON response shape

```json
{
  "pagination": { "current_page": 1, "page_size": 20, "total_count": 42, "total_pages": 3 },
  "connectors": [
    {
      "connector_id": 10,
      "connector_type": "slack",
      "connector_name": "Slack Incoming Webhook",
      "connector_description": "Post to slack",
      "connector_config": "{...}",
      "pipeline_type": "realtime",
      "purpose": "R"
    }
  ]
}
```

Hook used in UI: `useGetConnectors(params)` — returns `connectors`, `pagination`, `isLoading`, `isError`.

***

### List destinations (project-level bindings)

Purpose: fetch destinations for a project (optionally filtered by feedback configuration). Supports pagination and column filtering.

Query params commonly supported:

* page (number)
* page\_size (number)
* feedback\_configuration\_id (optional)
* plus additional filter params (column filter keys supported by backend)

Example request (GET):

```http
GET BASE_URL/destinations?page=1&page_size=10&feedback_configuration_id=fc_abc123
Authorization: Bearer <token>
```

Example response shape

```json
{
  "pagination": { "current_page": 1, "page_size": 10, "total_count": 2, "total_pages": 1 },
  "connectors": [
    {
      "project_connector_id": "pc_001",
      "project_id": 123,
      "feedback_configuration_id": "fc_abc123",
      "connector_id": 10,
      "connector_project_name": "Slack - Feedback Alerts",
      "connector_project_description": "Post feedback to #feedback",
      "connector_name": "Slack Incoming Webhook",
      "connector_type": "slack",
      "purpose": "R",
      "pipeline_type": "realtime",
      "is_enabled": "Y",
      "updated_by": "user_1",
      "updated_at": "2025-09-03T12:00:00Z"
    }
  ]
}
```

Hook used in UI: `useGetDestinations(page, pageSize, filters, enabled, feedbackId)` — returns `destinations`, `pagination`, `isLoading`, `isError`.

***

### Create destination

Purpose: create a new project-scoped destination (bind a connector to a project/feedback).

Request body (CreateDestinationRequest)

```json
{
  "connector_id": 123,
  "feedback_configuration_id": "fc_abc123",
  "connector_project_name": "Slack - Feedback Alerts",
  "connector_project_description": "Post feedback to #feedback",
  "purpose": "R",
  "pipeline_type": "realtime",
  "is_enabled": "Y",
  "active_status": "A"
}
```

Example response (on success)

```json
{
  "message": "Destination created",
  "project_connector_id": "pc_001"
}
```

Hook used in UI: `useCreateDestination()` — this wraps a POST mutation and invalidates `QUERY_KEYS.DESTINATIONS` on success.

***

### Update destination definition / config

Purpose: update destination definition (connector selection) or connector-specific config. Use the destination edit endpoint. The body typically includes connector config blob and updateable fields like `connector_project_name`, `connector_project_description`, `is_enabled`, and connector-specific config payload.

Example patch request shape (pseudo)

```json
{
  "connector_project_name": "Slack - Alerts v2",
  "connector_config": { "webhook_url": "https://hooks..." },
  "is_enabled": "Y"
}
```

There are separate endpoints in the UI hooks for `updateDef` and `updateConfig` (see `-services/hooks/useUpdateDestinationDefiniton.ts` and `useUpdateDestinationConfig.ts`).

***

### Enable / disable destination

Purpose: toggle `is_enabled` flag for a destination.

Example request (PATCH / POST):

```json
{ "destinationId": "pc_001", "is_enabled": "N" }
```

Hook used in UI: `useEnableDestination()` — toggles and refetches cache.

***

### Delete destination

Purpose: remove a destination from a project.

Example request (DELETE):

```http
DELETE BASE_URL/destinations/pc_001
Authorization: Bearer <token>
```

Hook used in UI: `useDeleteDestination(projectConnectorId)` — invalidates queries and shows a toast on success.

***

### Export / Test endpoints

* `TestTemplateDialog` triggers a test payload to verify a destination's connector config. It typically calls a `test` endpoint with the destination ID and returns success/failure and raw response body for debugging.
* Export endpoints exist for downloading feedback results (see `results/export` hooks); they may trigger background jobs and offer job status polling endpoints.

***

### Pagination & filtering

* Pagination is 1-indexed in the UI hooks and returned in a `pagination` object with `current_page`, `page_size`, `total_count`, `total_pages`.
* Column filtering is passed as query params. Use `getFilterParams()` (see UI code) to map column filters to query params.

***

### Error handling and retries

* The UI expects standard HTTP status codes. On 4xx the UI surfaces an error page/toast. On 5xx you may want to implement retries with exponential backoff.
* For webhooks and external sinks, backend should implement retry/backoff and a dead-letter strategy for permanent failures.

***

### Example JS (client) snippets

Create destination (fetch wrapper):

```js
async function createDestination(data) {
  const res = await fetch(`${BASE_URL}/destinations`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
    body: JSON.stringify(data)
  });
  if (!res.ok) throw new Error(`Create failed: ${res.status}`);
  return res.json();
}
```

Get destinations with pagination:

```js
async function getDestinations(page=1, pageSize=10, filters={}) {
  const params = new URLSearchParams({ page, page_size: pageSize });
  Object.entries(filters).forEach(([k,v]) => v !== undefined && v !== '' && params.append(k, v));
  const res = await fetch(`${BASE_URL}/destinations?${params.toString()}`, { headers: { Authorization: `Bearer ${token}` } });
  if (!res.ok) throw new Error('Fetch failed');
  return res.json();
}
```

***

### Notes & references

* Exact URLs and methods are configured in `modulePermissions.*` in the UI codebase; reference these values for the canonical endpoints and HTTP verbs.
* See the UI hooks in `admin/ui-v2/src/routes/.../module/encatch/destinations/-services/hooks/` for concrete usage and response handling.

If you'd like, I can also:

* Extract the `modulePermissions.*` URL/method values and embed them into this guide for a specific environment.
* Generate an OpenAPI-style JSON example for the destination endpoints.


# Flutter SDK (/docs/developer-guide/sdk-guides/flutter)
import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { StatusGrid } from '@/components/fumadocs-custom/status-grid';

Features and compatibility overview.

<StatusGrid
  items={[
  { status: "check", label: "Android",description: "Has been tested" },
  { status: "check", label: "iOS",description: "Has been tested" },
  { status: "unknown", label: "MacOS",description: "Not tested or verified" },
  { status: "unknown", label: "Windows",description: "Not tested or verified" },
  { status: "unknown", label: "Linux",description: "Not tested or verified" },
  { status: "unknown", label: "Web",description: "Not tested or verified" },
  ]}
/>

<Callout type="warn" title="Beta version alert">
  This sdk is in beta version and is bound to change. Usage in production is not recommended.
</Callout>

The encatch Flutter SDK provides a seamless way to integrate user feedback collection into your Flutter applications. This SDK allows you to display customized feedback forms, collect user responses, and submit them to the encatch backend with full support for both traditional navigation and Flutter's new Router API.

## Installation

Add the encatch Flutter SDK to your `pubspec.yaml` file:

```yaml
dependencies:
  flutter:
    sdk: flutter
  ...other libraries  
  encatch_flutter: ^latest_version
  ...other libraries
```

Then run:

```bash
flutter pub get
```

### Initialization

The SDK must be initialized early in your application lifecycle, typically in your `main.dart` file, to ensure proper functionality across all screens and widgets.

<Tabs items={['Basic','Advanced']}>
  <Tab value="Basic">
    For standard implementations, initialize the SDK with just your API key and a navigator key. This provides all essential functionality with default configuration settings that work for most applications.

    <CodeBlockTabs defaultValue="main.dart">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="main.dart">
          main.dart
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="main.dart">
        ```dart
        import 'package:flutter/material.dart';
        import 'package:encatch_flutter/encatch_flutter.dart';

        final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

        void main() {
          WidgetsFlutterBinding.ensureInitialized();

          // Initialize the SDK
          encatchFlutter.init(
            '<YOUR_PROJECT_API_KEY>',
            navigatorKey: navigatorKey,
          );

          runApp(const MyApp());
        }

        class MyApp extends StatelessWidget {
          const MyApp({super.key});

          @override
          Widget build(BuildContext context) {
            return MaterialApp(
              navigatorKey: navigatorKey,
              navigatorObservers: [encatchFlutter.pathObserver],
              home: const HomePage(),
            );
          }
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Advanced">
    For applications requiring custom configuration, the SDK supports advanced initialization options. This approach allows you to specify custom configuration parameters and fine-tune the SDK behavior to match your specific requirements.

    <CodeBlockTabs defaultValue="main.dart">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="main.dart">
          main.dart
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="main.dart">
        ```dart
        import 'package:flutter/material.dart';
        import 'package:encatch_flutter/encatch_flutter.dart';

        final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

        void main() {
          WidgetsFlutterBinding.ensureInitialized();

          // Initialize with advanced configuration
          encatchFlutter.init(
            '<YOUR_PROJECT_API_KEY>',
            navigatorKey: navigatorKey,
            config: encatchConfig(
              host: 'https://your-encatch-instance',
              identity: UserInfo(
                userName: 'user123',
                properties: {
                  'email': 'user@example.com',
                  'plan': 'premium'
                }
              ),
              isAutoCaptureEnabled: true,
              themeMode: 'light',
              language: 'en',
              useRouterAPI: false,
              ignoredRoutes: ['/settings', '/privacy']
            ),
          );

          runApp(const MyApp());
        }

        class MyApp extends StatelessWidget {
          const MyApp({super.key});

          @override
          Widget build(BuildContext context) {
            return MaterialApp(
              navigatorKey: navigatorKey,
              navigatorObservers: [encatchFlutter.pathObserver],
              home: const HomePage(),
            );
          }
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    **encatchConfig Properties:**

    <TypeTable
      type={{
    host: {
      description: 'The base URL for the encatch backend API endpoint',
      type: 'String?',
      default: '"https://app.dev.en-gage.in"',
      required: false
    },
    identity: {
      description: 'User information object containing username and properties',
      type: 'UserInfo',
      default: 'UserInfo(userName: "anonymous", properties: {"email": null, "user_age": null})',
      required: false
    },
    processAfterIdentitySet: {
      description: 'Whether to delay processing until user identity is established',
      type: 'bool',
      default: 'false',
      required: false
    },
    isAutoCaptureEnabled: {
      description: 'Enables or disables automatic event capture functionality',
      type: 'bool?',
      default: 'true',
      required: false
    },
    themeMode: {
      description: 'Theme mode for the SDK UI (e.g., "light", "dark")',
      type: 'String?',
      default: 'null',
      required: false
    },
    language: {
      description: 'Language code for SDK localization',
      type: 'String?',
      default: 'null',
      required: false
    },
    assetUrl: {
      description: 'Custom URL for loading SDK assets and resources',
      type: 'String?',
      default: 'null',
      required: false
    },
    ignoredRoutes: {
      description: 'List of routes to exclude from automatic tracking',
      type: 'List<String>?',
      default: 'null',
      required: false
    },
    useRouterAPI: {
      description: 'Whether to use Flutter Router API for navigation tracking',
      type: 'bool',
      default: 'false',
      required: false
    }
  }}
    />

    **UserInfo Class:**

    ```dart
    class UserInfo {
      String userName;
      Map<String, dynamic>? properties;

      UserInfo({
        required this.userName,
        this.properties,
      });
    }
    ```
  </Tab>
</Tabs>

#### For enterprise version

```dart
encatchFlutter.init(
  '<YOUR_PROJECT_API_KEY>',
  navigatorKey: navigatorKey,
  config: encatchConfig(
    host: 'https://your-encatch-instance'
  ),
);
```

<Accordions type="single">
  <Accordion title="Requirements & Permissions">
    **Internet Permission**: Your app needs internet access to communicate with the encatch backend.

    **SSL Pinning**: If your app uses SSL pinning, include the certificate of the encatch application.

    **Navigator Key**: A `GlobalKey<NavigatorState>` is required for the SDK to display popup dialogs.

    **Minimum SDK Version**: Flutter SDK version 1.17.0 or higher is required.
  </Accordion>
</Accordions>

## How to use

### User Identification

The `identify(String userName, [Map<String, dynamic>? traits])` method is used to identify the current user and fetch personalized configurations based on the user's profile.

**Example Usage:**

```dart
// After successful user authentication
await encatchFlutter.identify('user_123', {
  'email': 'user@example.com',
  'name': 'John Doe',
  'plan': 'premium',
  'signup_date': '2025-01-15'
});
```

**Use Cases:**

* User authentication integration
* Personalized feedback targeting
* User profile synchronization
* Analytics user tracking

### Session Management

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

<Tabs items={['stopSession()','resetSession()']}>
  <Tab value="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.

    ```dart
    // End current session but keep user data
    await encatchFlutter.stopSession();
    ```

    **Use Cases:**

    * Creating session boundaries
    * Preserving user context across session changes
    * Session timeout handling
    * Application state transitions
  </Tab>

  <Tab value="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.

    ```dart
    // Complete session reset
    await encatchFlutter.resetSession();
    ```

    **Use Cases:**

    * User logout (best use case)
    * Complete session termination
    * Clearing all user data and feedback configurations
    * Privacy compliance requirements
  </Tab>
</Tabs>

### Triggers

The e-Ncatch Flutter SDK provides comprehensive event tracking capabilities with three distinct approaches: manual feedback control for programmatic trigger management, custom event tracking for business-specific metrics, and navigation tracking for user journey analysis.

<Tabs items={['Manual','Custom Event','Navigation Tracking']}>
  <Tab value="Manual">
    ### Programmatic Feedback Display

    Override automatic triggering with manual control over feedback form presentation.

    <Tabs items={['openFeedback()','openFeedbackById()','openFeedbackByName()']}>
      <Tab value="openFeedback()">
        Opens the first feedback from the list of eligible feedbacks.

        **Example Usage:**

        ```dart
        // Open first available feedback
        await encatchFlutter.openFeedback();
        ```

        **Use Cases:**

        * General feedback collection
        * Default feedback trigger
        * Quick feedback access
      </Tab>

      <Tab value="openFeedbackById()">
        Display a specific feedback form by its unique identifier.

        **Example Usage:**

        ```dart
        // Basic usage
        await encatchFlutter.openFeedbackById('feedback_config_123');

        // With theme and language overrides
        await encatchFlutter.openFeedbackById(
          'feedback_config_123',
          theme: 'dark',
          language: 'es'
        );
        ```

        **Use Cases:**

        * Programmatic feedback form display
        * Integration with existing UI components
        * Custom feedback triggers
        * A/B testing specific feedback forms

        **Parameters:**

        <TypeTable
          type={{
      feedbackId: {
        description: 'Unique feedback configuration ID',
        type: 'String',
        required: true
      },
      theme: {
        description: 'Override default theme for the feedback form',
        type: '"light" | "dark"',
        default: 'Current theme setting',
        required: false
      },
      language: {
        description: 'Override default language for the feedback form',
        type: 'String',
        default: 'Current language setting',
        required: false
      }
    }}
        />
      </Tab>

      <Tab value="openFeedbackByName()">
        Display a feedback form by its configured title/name.

        **Example Usage:**

        ```dart
        // Open by form title
        await encatchFlutter.openFeedbackByName('Product Satisfaction Survey');

        // With customization options
        await encatchFlutter.openFeedbackByName(
          'Feature Feedback',
          theme: 'dark',
          language: 'fr'
        );
        ```

        **Use Cases:**

        * Content-driven feedback display
        * User-friendly feedback triggers
        * CMS integration scenarios
        * Non-technical implementation

        **Parameters:**

        <TypeTable
          type={{
      feedbackTitle: {
        description: 'Display name of the feedback form',
        type: 'String',
        required: true
      },
      theme: {
        description: 'Override default theme for the feedback form',
        type: '"light" | "dark"',
        default: 'Current theme setting',
        required: false
      },
      language: {
        description: 'Override default language for the feedback form',
        type: 'String',
        default: 'Current language setting',
        required: false
      }
    }}
        />
      </Tab>
    </Tabs>

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

  <Tab value="Custom Event">
    **Custom Events**: Track specific events that are unique to your application's needs and business logic using the `trackEvent` method.

    **`trackEvent(String eventName, [Map<String, dynamic>? properties])`**

    **Use Cases:**

    * User behavior analytics
    * Feature usage tracking
    * Conversion funnel analysis
    * Custom business metrics
    * Application-specific interactions
    * A/B test tracking
    * User journey mapping

    **Parameters:**

    <TypeTable
      type={{
    eventName: {
      description: 'Unique identifier for the event',
      type: 'String',
      required: true
    },
    properties: {
      description: 'Additional event metadata and context',
      type: 'Map<String, dynamic>?',
      default: 'null',
      required: false
    }
  }}
    />

    **Example Usage:**

    ```dart
    // Basic event tracking
    await encatchFlutter.trackEvent('page_view');

    // E-commerce events
    await encatchFlutter.trackEvent('purchase_completed', {
      'product_id': 'prod_123',
      'amount': 99.99,
      'currency': 'USD',
      'category': 'electronics',
      'quantity': 2,
      'payment_method': 'credit_card'
    });

    // User interaction tracking
    await encatchFlutter.trackEvent('button_click', {
      'button_id': 'cta-subscribe',
      'location': 'hero-section',
      'action': 'newsletter_signup'
    });

    // Feature usage tracking
    await encatchFlutter.trackEvent('feature_used', {
      'feature': 'advanced_search',
      'filters_applied': ['price', 'category', 'rating'],
      'results_count': 25,
      'search_time': 1.2
    });

    // Video engagement
    await encatchFlutter.trackEvent('video_interaction', {
      'video_id': 'tutorial_101',
      'action': 'play',
      'current_time': 45,
      'total_duration': 180,
      'quality': '720p'
    });

    // Form analytics
    await encatchFlutter.trackEvent('form_step_completed', {
      'form_name': 'onboarding',
      'step': 2,
      'step_name': 'personal_info',
      'time_spent': 120,
      'completion_rate': 0.75
    });
    ```

    **Event Enhancement:**
    The SDK automatically enriches tracked events with:

    * Current page path and title
    * Session information and user identity
    * Device and browser metadata
    * Timestamp and user agent
    * Geographic location (if available)

    <Accordions type="single">
      <Accordion title="Enhanced Event Tracking">
        **Automatic Context Enrichment**

        All tracked events are automatically enhanced with contextual information:

        ```dart
        // Basic event call
        await encatchFlutter.trackEvent('purchase_completed', {
          'product_id': 'item_123',
          'amount': 99.99
        });

        // Automatically enhanced with:
        // {
        //   product_id: 'item_123',
        //   amount: 99.99,
        //   path: '/checkout/success',        // Current page path
        //   event: 'purchase_completed',      // Event name
        //   timestamp: 1642694400000,         // Unix timestamp
        //   session_id: 'sess_abc123',        // Session identifier
        //   user_agent: 'Flutter/2.0...',     // Device information
        //   referrer: 'home_screen',          // Previous screen
        //   viewport: '1080x1920'             // Screen resolution
        // }
        ```

        **Event-Driven Feedback Triggers**

        Events can automatically trigger relevant feedback forms based on your configuration:

        ```dart
        // E-commerce example
        await encatchFlutter.trackEvent('purchase_completed', {
          'order_id': 'order_123',
          'total': 149.99,
          'items_count': 3
        });
        // May trigger post-purchase satisfaction survey

        // Feature usage example
        await encatchFlutter.trackEvent('feature_used', {
          'feature': 'advanced_search',
          'user_type': 'premium',
          'success': true
        });
        // May trigger feature-specific feedback form

        // Support interaction example
        await encatchFlutter.trackEvent('support_chat_ended', {
          'duration': 180, // seconds
          'resolved': true,
          'agent_id': 'agent_456'
        });
        // May trigger support experience survey
        ```
      </Accordion>
    </Accordions>
  </Tab>

  <Tab value="Navigation Tracking">
    **Navigation Tracking**: The SDK provides automatic navigation tracking through Flutter's RouteObserver. You must add the path observer to your MaterialApp's navigatorObservers to enable automatic screen tracking.

    > **Important:** This is essential for the SDK to track user navigation patterns and determine when to show relevant feedback forms.

    <Tabs items={['Traditional Navigation','Router API']}>
      <Tab value="Traditional Navigation">
        For apps using traditional named routes or PageRoute-based navigation:

        ```dart
        class MyApp extends StatelessWidget {
          @override
          Widget build(BuildContext context) {
            return MaterialApp(
              navigatorKey: navigatorKey,
              navigatorObservers: [encatchFlutter.pathObserver], // Add this line
              initialRoute: '/',
              routes: {
                '/': (context) => HomePage(),
                '/profile': (context) => ProfilePage(),
              },
            );
          }
        }
        ```
      </Tab>

      <Tab value="Router API">
        For apps using Flutter's new Router API (GoRouter, etc.), enable the Router API support:

        ```dart
        void main() {
          WidgetsFlutterBinding.ensureInitialized();

          encatchFlutter.init(
            '<YOUR_PROJECT_API_KEY>',
            navigatorKey: navigatorKey,
            config: encatchConfig(
              useRouterAPI: true, // Enable Router API support
              // ... other config
            ),
          );

          runApp(const MyApp());
        }

        class MyApp extends StatelessWidget {
          @override
          Widget build(BuildContext context) {
            return MaterialApp.router(
              routerConfig: _router,
              // ... other configuration
            );
          }
        }
        ```
      </Tab>
    </Tabs>

    **Auto-captured Navigation Events**: The SDK automatically tracks navigation events without any manual implementation required.

    <Accordions type="single">
      <Accordion title="Properties">
        | Event            | Description                         | Properties                                |
        | ---------------- | ----------------------------------- | ----------------------------------------- |
        | `page_view`      | Screen navigation and route changes | `path`, `title`, `referrer`, `timestamp`  |
        | `session_start`  | User session initialization         | `session_id`, `user_agent`, `device_info` |
        | `app_foreground` | App brought to foreground           | `timestamp`, `session_id`                 |
        | `app_background` | App sent to background              | `timestamp`, `session_id`                 |
      </Accordion>
    </Accordions>

    **Configuration:**

    ```dart
    // Disable automatic navigation tracking
    encatchFlutter.init(
      '<YOUR_PROJECT_API_KEY>',
      navigatorKey: navigatorKey,
      config: encatchConfig(
        isAutoCaptureEnabled: false
      ),
    );

    // Enable specific auto-events only
    encatchFlutter.init(
      '<YOUR_PROJECT_API_KEY>',
      navigatorKey: navigatorKey,
      config: encatchConfig(
        isAutoCaptureEnabled: true,
        ignoredRoutes: ['/settings', '/privacy'] // Exclude specific routes
      ),
    );
    ```

    **Use Cases:**

    * Basic user behavior analytics without custom implementation
    * Screen engagement and navigation tracking
    * User journey analysis
    * App usage patterns
    * Screen flow optimization

    **Automatic Context Enrichment:**
    All auto-captured navigation events are automatically enhanced with:

    * Current screen path and title
    * Session information and user identity
    * Device and platform metadata
    * Timestamp and user agent
    * Geographic location (if available)
  </Tab>
</Tabs>

### UI Customization

Dynamically control the appearance and localization of feedback forms and interfaces.

<Tabs items={['Theme','Language']}>
  <Tab value="Theme">
    **`setTheme(String theme)`**

    <TypeTable
      type={{
  theme: {
    description: 'Theme mode for the interface',
    type: '"light" | "dark"',
    required: true
  }
}}
    />

    **Example Usage:**

    ```dart
    // Basic theme switching
    await encatchFlutter.setTheme('dark');   // Switch to dark theme
    await encatchFlutter.setTheme('light');  // Switch to light theme
    ```

    **Use Cases:**

    * Dark mode toggle implementation
    * System theme synchronization
    * User preference persistence
    * Accessibility compliance
  </Tab>

  <Tab value="Language">
    **`setLanguage(String languageCode)`**

    <TypeTable
      type={{
  languageCode: {
    description: 'ISO 639-1 language code for UI localization',
    type: 'String',
    required: true
  }
}}
    />

    **Example Usage:**

    ```dart
    // Language localization
    await encatchFlutter.setLanguage('es');      // Spanish
    await encatchFlutter.setLanguage('fr');      // French
    await encatchFlutter.setLanguage('de');      // German
    await encatchFlutter.setLanguage('YOUR_ADMIN_CONFIG_LANGUAGE_CODE');
    ```

    **Use Cases:**

    * Internationalization (i18n) implementation
    * Multi-language application support
    * User language preference persistence
    * Browser language detection and fallback

    > **Note:** Language changes affect all subsequent feedback forms. You may ideally call this when user switches languages in your application.
  </Tab>
</Tabs>

### Advanced Configuration

<Accordions type="single">
  <Accordion title="Advanced SDK Methods">
    <Tabs items={['Popup Positioning','Route Filtering','Custom Styling']}>
      <Tab value="Popup Positioning">
        The SDK supports various popup positions:

        * `center` - Center of the screen
        * `top-left`, `top-center`, `top-right` - Top positions
        * `bottom-left`, `bottom-center`, `bottom-right` - Bottom positions
        * `center-left`, `center-right` - Side positions
      </Tab>

      <Tab value="Route Filtering">
        You can exclude specific routes from tracking by adding them to the `ignoredRoutes` list in your encatchConfig:

        ```dart
        encatchConfig(
          ignoredRoutes: ['/settings', '/privacy'],
          // ... other config
        )
        ```
      </Tab>

      <Tab value="Custom Styling">
        The SDK automatically adapts to your app's theme and supports:

        * Custom overlay colors
        * Dark/light theme switching
        * Responsive design for mobile, tablet, and desktop
        * Keyboard-aware positioning
      </Tab>
    </Tabs>
  </Accordion>
</Accordions>

<Accordions type="single">
  <Accordion title="Best Practices">
    1. **Initialize Early**: Always initialize the SDK in your main.dart file before running your app.

    2. **Navigator Key**: Use a singleton pattern for your navigator key to ensure consistency.

    3. **Theme Synchronization**: Update the SDK theme whenever your app's theme changes.

    4. **User Identification**: Call identify() after successful user authentication.

    5. **Session Management**: Use resetSession() on user logout and stopSession() for session boundaries.

    6. **Error Handling**: Wrap SDK calls in try-catch blocks for production apps.
  </Accordion>

  <Accordion title="Troubleshooting">
    **Common Issues:**

    * **Popup not showing**: Ensure navigator key is properly set and has a valid context
    * **Theme not matching**: Call `setTheme()` after theme changes in your app
    * **Navigation not tracked**: Verify that pathObserver is added to navigatorObservers
    * **User identification fails**: Check that the user data format matches the expected UserInfo structure
  </Accordion>
</Accordions>


# Other SDKs (/docs/developer-guide/sdk-guides/others)
import { Button } from "@/components/ui/button";
import { VoteIcon, Code, Zap, Webhook, MessageSquare, AlertCircle } from "lucide-react";

<div className="flex justify-between w-full">
  <p>
    We are always looking to add more SDKs as adoption takes place. Don't see your favorite SDK? Let us know which SDK you'd like us to build next!
  </p>

  <Button variant="outline" className="mt-4">
    <VoteIcon className="w-4 h-4 mr-2" />

    Suggest a framework
  </Button>
</div>


# React Native SDK (/docs/developer-guide/sdk-guides/react-native)
import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { StatusGrid } from '@/components/fumadocs-custom/status-grid';

Features and compatibility overview.

<StatusGrid
  items={[
  { status: "check", label: "Android",description: "Has been tested" },
  { status: "check", label: "iOS",description: "Has been tested" },
  { status: "unknown", label: "MacOS",description: "Not tested or verified" },
  { status: "unknown", label: "Windows",description: "Not tested or verified" },
  { status: "unknown", label: "Linux",description: "Not tested or verified" },
  { status: "unknown", label: "Web",description: "Not tested or verified" },
  ]}
/>

<Callout type="warn" title="Beta version alert">
  This sdk is in beta version and is bound to change. Usage in production is not recommended.
</Callout>

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:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    @encatch/react-native
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    @encatch/react-native
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    @encatch/react-native
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    @encatch/react-native
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### Initialization

<Tabs items={['Basic Setup','Advanced Setup','EnsightConfig Properties']}>
  <Tab value="Basic Setup">
    For standard implementations, initialize the SDK with just your API key. This provides all essential functionality with default configuration settings that work for most applications.

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

    EnsightApp.initialize({
      apiKey: "Your Ensight API Key",
    });
    ```
  </Tab>

  <Tab value="Advanced Setup">
    For applications requiring custom configuration, the SDK supports advanced initialization options. This approach allows you to specify custom configuration parameters using the EnsightConfig class, enable debug mode for development and testing, and fine-tune the SDK behavior to match your specific requirements.

    ```javascript
    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,
    });
    ```
  </Tab>

  <Tab value="EnsightConfig Properties">
    | Property               | Type            | Default Value                  | Description                                                  |
    | ---------------------- | --------------- | ------------------------------ | ------------------------------------------------------------ |
    | `host`                 | `string`        | `"https://app.dev.en-gage.in"` | The base URL for the Ensight backend API endpoint            |
    | `identity`             | `UserInfoModel` | `undefined`                    | User information object containing user\_name and properties |
    | `isAutoCaptureEnabled` | `boolean`       | `true`                         | Enables or disables automatic event capture functionality    |
    | `themeMode`            | `string`        | `undefined`                    | Theme mode for the SDK UI (e.g., "light", "dark")            |
    | `language`             | `string`        | `undefined`                    | Language code for SDK localization                           |
    | `assetUrl`             | `string`        | `undefined`                    | Custom URL for loading SDK assets and resources              |

    **UserInfoModel Interface:**

    ```typescript
    interface UserInfoModel {
      user_name: string;
      properties: {
        email: string | null;
        user_age: number | null;
      };
    }
    ```
  </Tab>
</Tabs>

#### For enterprise version

```javascript
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.

<CodeBlockTabs defaultValue="App.tsx">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="App.tsx">
      App.tsx
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="App.tsx">
    ```javascript
    import React from 'react';
    import { EnsightRootUIComponent } from "@encatch/react-native";
    import YourMainApp from './YourMainApp';

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

## 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:

<Tabs items={['openFeedback()','openFeedbackById()','openFeedbackByName()']}>
  <Tab value="openFeedback()">
    **`openFeedback()`**: Opens the first feedback from the list of eligible feedbacks.

    ```javascript
    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>
      );
    };
    ```

    **Use Cases:**

    * General feedback collection
    * Default feedback form display
    * Simple feedback triggers
  </Tab>

  <Tab value="openFeedbackById()">
    **`openFeedbackById(id: string)`**: Opens a specific feedback based on its unique ID.

    ```javascript
    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>
      );
    };
    ```

    **Use Cases:**

    * Programmatic feedback form display
    * Integration with existing UI components
    * Custom feedback triggers
    * A/B testing specific feedback forms

    **Parameters:**

    <TypeTable
      type={{
    id: {
      description: 'Unique feedback configuration ID',
      type: 'string',
      required: true
    }
  }}
    />
  </Tab>

  <Tab value="openFeedbackByName()">
    **`openFeedbackByName(name: string)`**: Opens a specific feedback based on its name.

    ```javascript
    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>
      );
    };
    ```

    **Use Cases:**

    * Content-driven feedback display
    * User-friendly feedback triggers
    * CMS integration scenarios
    * Non-technical implementation

    **Parameters:**

    <TypeTable
      type={{
    name: {
      description: 'Display name of the feedback form',
      type: 'string',
      required: true
    }
  }}
    />
  </Tab>
</Tabs>

> **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.

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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.

```javascript
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

<Accordions type="single">
  <Accordion title="Session Management Reference">
    | Method           | Behavior                                  | Use Case                              |
    | ---------------- | ----------------------------------------- | ------------------------------------- |
    | `stopSession()`  | Ends current session, preserves user data | App backgrounding, session boundaries |
    | `resetSession()` | Complete reset, clears all user data      | User logout, privacy compliance       |

    **Important Notes:**

    * `stopSession()` maintains user identity and feedback configurations
    * `resetSession()` returns the SDK to anonymous state
    * Choose the appropriate method based on your privacy and UX requirements
  </Accordion>
</Accordions>

### Advanced Configuration

<Accordions type="single">
  <Accordion title="Advanced Configuration Options">
    The SDK provides several advanced configuration options for fine-tuning behavior:

    **Debug Mode:**

    ```javascript
    EnsightApp.initialize({
      apiKey: "Your Ensight API Key",
      debugMode: true, // Enable debug logging
    });
    ```

    **Custom Host Configuration:**

    ```javascript
    const customConfig = new EnsightConfig({
      host: "https://your-custom-instance.com",
      assetUrl: "https://your-cdn.com/assets"
    });
    ```

    **Auto-capture Control:**

    ```javascript
    const customConfig = new EnsightConfig({
      isAutoCaptureEnabled: false // Disable automatic event capture
    });
    ```

    **Use Cases:**

    * Development and testing environments
    * Enterprise deployments with custom infrastructure
    * Compliance scenarios requiring manual event control
    * Performance optimization for specific use cases
  </Accordion>
</Accordions>


# JavaScript Web SDK (/docs/developer-guide/sdk-guides/web)
import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { StatusGrid } from '@/components/fumadocs-custom/status-grid';

{/* Features and compatibility overview. */}

{/* <StatusGrid
    items={[
    { status: "check", label: "Android",description: "Has been tested" },
    { status: "check", label: "iOS",description: "Has been tested" },
    { status: "unknown", label: "MacOS",description: "Not tested or verified" },
    { status: "unknown", label: "Windows",description: "Not tested or verified" },
    { status: "unknown", label: "Linux",description: "Not tested or verified" },
    { status: "unknown", label: "Web",description: "Not tested or verified" },
    ]}
  /> */}

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

## Quick Start

Get e-Ncatch running in your application in under 5 minutes with below steps.

## Installation & Initialization

<Tabs items={['Package Manager','CDN']}>
  <Tab value="Package Manager">
    Install the e-Ncatch JavaScript SDK using your preferred package manager:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        @encatch/web-sdk
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        @encatch/web-sdk
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        @encatch/web-sdk
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        @encatch/web-sdk
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    After installation, import and initialize the SDK in your application:

    <CodeBlockTabs defaultValue="ES6 Modules">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="ES6 Modules">
          ES6 Modules
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="CommonJS">
          CommonJS
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="TypeScript">
          TypeScript
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="ES6 Modules">
        ```javascript
        import { Encatch } from '@encatch/web-sdk';

        // Initialize the SDK
        const encatch = new Encatch();
        encatch.init('<YOUR_PROJECT_API_KEY>');
        ```
      </CodeBlockTab>

      <CodeBlockTab value="CommonJS">
        ```javascript
        const { Encatch } = require('@encatch/web-sdk');

        // Initialize the SDK
        const encatch = new Encatch();
        encatch.init('<YOUR_PROJECT_API_KEY>');
        ```
      </CodeBlockTab>

      <CodeBlockTab value="TypeScript">
        ```typescript
        import { Encatch } from '@encatch/web-sdk';

        // Initialize the SDK with TypeScript support
        const encatch = new Encatch();
        encatch.init('<YOUR_PROJECT_API_KEY>');
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="CDN">
    Add the following script to the `<head>` section of your HTML, preferably just before the closing `</head>` tag. Replace `<your_project_api_key>` with your actual project API key from the e-Ncatch dashboard.

    ```html
    <html>
        <head>
            ....other head content
            <script type="module">
                (function(){window.encatch||(window.encatch={_i:[],apiKey:"",config:{host:void 0,isAutoCaptureEnabled:!0,themeMode:"light",language:"en"},initialized:!1,chunkUrlLoader:i=>window.encatch.config.host+i,init(i,e){if(window.encatch.initialized)return;window.encatch.apiKey=i,e!=null&&e.host&&(window.encatch.config.host=e.host),e!=null&&e.identity&&(window.encatch.config.identity=e.identity),(e==null?void 0:e.processAfterIdentitySet)!==void 0?window.encatch.config.processAfterIdentitySet=e.processAfterIdentitySet:window.encatch.config.processAfterIdentitySet=!1,(e==null?void 0:e.isAutoCaptureEnabled)!==void 0&&(window.encatch.config.isAutoCaptureEnabled=e.isAutoCaptureEnabled),e!=null&&e.themeMode?window.encatch.config.themeMode=e.themeMode:window.encatch.config.themeMode="light",e!=null&&e.language?window.encatch.config.language=e.language:window.encatch.config.language="en",window.encatch.initialized=!0;const g=`${window.encatch.config.host}/plugin/sdk/encatch-web-sdk.js`,t=document.createElement("script");t.src=g,t.type="module",t.async=!0;const n=document.head.firstChild;n?document.head.insertBefore(t,n):document.head.appendChild(t);const d=document.createElement("div");d.id="enisght-root",document.body.appendChild(d)}},["trackEvent","stopSession","identify","resetSession","openFeedbackById","openFeedbackByName","setThemeMode","setLanguage","verifyFeedbackIds","forceFetchEligibleFeedbacks","capturePageScrollEvent"].forEach(i=>{window.encatch[i]=(...e)=>{window.encatch._i.push([i,...e])}}))})();
                encatch.init('<YOUR_PROJECT_API_KEY>');
            </script>
        </head>
    <body>
        ....other body content
    </body>
    </html>
    ```
  </Tab>
</Tabs>

<Callout title="Note on Server Side Rendering Frameworks (SSR)" type="warn">
  encatch web is a client side SDK and relies on window object to be available. So ensure it is not used in server side components.
</Callout>

#### Framework Examples

<Tabs items={['React','Vue.js','Svelte','Angular','SolidJS','Next.js','Nuxt.js','TanStack']}>
  <Tab value="React">
    ```javascript
    import { Encatch } from '@encatch/web-sdk';
    import { useEffect } from 'react';

    function App() {
      useEffect(() => {
        const encatch = new Encatch();
        encatch.init('<YOUR_PROJECT_API_KEY>');
      }, []);

      return <div>Your React App</div>;
    }
    ```
  </Tab>

  <Tab value="Vue.js">
    ```javascript
    import { Encatch } from '@encatch/web-sdk';
    import { onMounted } from 'vue';

    export default {
      setup() {
        onMounted(() => {
          const encatch = new Encatch();
          encatch.init('<YOUR_PROJECT_API_KEY>');
        });
      }
    }
    ```
  </Tab>

  <Tab value="Svelte">
    <Steps>
      <Step>
        **Create a Svelte Component**

        Create a new component file `src/lib/EncatchComponent.svelte`:

        ```svelte
        <script>
          import { onMount } from 'svelte';
          import { Encatch } from '@encatch/web-sdk';

          onMount(() => {
            const encatch = new Encatch();
            encatch.init('<YOUR_PROJECT_API_KEY>');
          });
        </script>
        ```
      </Step>

      <Step>
        **Include in Layout**

        Add the component to your root layout file `src/routes/+layout.svelte`:

        ```svelte
        <script>
          import EncatchComponent from '$lib/EncatchComponent.svelte';
        </script>

        <EncatchComponent />
        <slot />
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab value="Angular">
    <Steps>
      <Step>
        **Create an Angular Service**

        Create a new service file `src/app/services/encatch.service.ts`:

        ```typescript
        import { Injectable } from '@angular/core';
        import { Encatch } from '@encatch/web-sdk';

        @Injectable({
          providedIn: 'root'
        })
        export class EncatchService {
          private encatch: any;

          constructor() {
            this.encatch = new Encatch();
            this.encatch.init('<YOUR_PROJECT_API_KEY>');
          }
        }
        ```
      </Step>

      <Step>
        **Include in App Component**

        Add the service to your main app component `src/app/app.component.ts`:

        ```typescript
        import { Component } from '@angular/core';
        import { EncatchService } from './services/encatch.service';

        @Component({
          selector: 'app-root',
          template: `
            <router-outlet></router-outlet>
          `
        })
        export class AppComponent {
          constructor(private encatchService: EncatchService) {}
        }
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab value="SolidJS">
    <Steps>
      <Step>
        **Create a Component**

        Create a new component file `src/components/EncatchComponent.tsx`:

        ```typescript
        import { onMount } from 'solid-js';
        import { Encatch } from '@encatch/web-sdk';

        export default function EncatchComponent() {
          onMount(() => {
            const encatch = new Encatch();
            encatch.init('<YOUR_PROJECT_API_KEY>');
          });

          return null;
        }
        ```
      </Step>

      <Step>
        **Include in App**

        Add the component to your main app file `src/App.tsx`:

        ```typescript
        import { Component } from 'solid-js';
        import EncatchComponent from './components/EncatchComponent';

        const App: Component = () => {
          return (
            <>
              <EncatchComponent />
              <div>Your SolidJS App</div>
            </>
          );
        };

        export default App;
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab value="Next.js">
    <Steps>
      <Step>
        **Create a Client Component**

        Create a new component file `components/EncatchComponent.tsx`:

        ```javascript
        'use client';
        import { Encatch } from '@encatch/web-sdk';
        import { useEffect } from 'react';

        export default function EncatchComponent({ children }: { children: React.ReactNode }) {
          useEffect(() => {
            const encatch = new Encatch();
            encatch.init('<YOUR_PROJECT_API_KEY>');
          }, []);

          return (
            <>
              {children}
            </>
          );
        }
        ```
      </Step>

      <Step>
        **Include in Layout**

        Add the component to your root layout file `app/layout.tsx`:

        ```javascript
        import EncatchComponent from '@/components/EncatchComponent';

        export default function Layout({ children }) {
          return (
            <>
              <Navbar />
              <EncatchComponent/>
              <main>
                {children}
              </main>
              <Footer />
            </>
          )
        }
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab value="Nuxt.js">
    <Steps>
      <Step>
        **Create a Plugin**

        Create a new plugin file `plugins/encatch.client.ts`:

        ```typescript
        import { Encatch } from '@encatch/web-sdk';

        export default defineNuxtPlugin(() => {
          const encatch = new Encatch();
          encatch.init('<YOUR_PROJECT_API_KEY>');
        });
        ```
      </Step>

      <Step>
        **Alternative: Use in App.vue**

        You can also initialize the SDK directly in your `app.vue` file:

        ```vue
        <template>
          <div>
            <NuxtPage />
          </div>
        </template>

        <script setup>
        import { Encatch } from '@encatch/web-sdk';

        onMounted(() => {
          const encatch = new Encatch();
          encatch.init('<YOUR_PROJECT_API_KEY>');
        });
        </script>
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab value="TanStack">
    <Steps>
      <Step>
        **Create a Client Component**

        Create a new component file `components/EncatchComponent.tsx`:

        ```javascript
        'use client';
        import { Encatch } from '@encatch/web-sdk';
        import { useEffect } from 'react';

        export default function EncatchComponent() {
          useEffect(() => {
            const encatch = new Encatch();
            encatch.init('<YOUR_PROJECT_API_KEY>');
          }, []);

          return null;
        }
        ```
      </Step>

      <Step>
        **Include in Layout**

        Add the component to your layout file:

        ```javascript
        import EncatchComponent from '@/components/EncatchComponent';

        export default function Layout({ children }) {
          return (
            <>
              <Navbar />
              <EncatchComponent/>
              <main>
                {children}
              </main>
              <Footer />
            </>
          )
        }
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

#### For enterprise version

```ts
encatch.init('<YOUR_PROJECT_API_KEY>', {
  host: 'https://your-encatch-instance'
});
```

## How to use

### Session Management

Control user session lifecycle for accurate analytics and user journey tracking.

<Tabs items={['startSession()','updateSession()','stopSession()','resetSession()']}>
  <Tab value="startSession()">
    <Callout type="warn">
      For best practices, username field should be difficult to guess or not easily reproducible. Don't use fields like email, mobile or system numeric ids.
    </Callout>

    Explicitly starts a new user session. Useful when you want manual control over session creation.

    ```javascript
    // Start a new session as a visitor
    encatch.startSession();

    // Start a new session with known user
    encatch.startSession({
      user_name: 'UUID_OF_USER',
      '$set': {
        email: 'user@example.com',
        name: 'John Doe',
        plan: 'enterprise'
      },
      '$set_once': {
        signup_date: '2025-01-15',
        initial_referrer: 'google.com'
      }
    });
    ```

    **Use Cases:**

    * Manual session control
    * Explicit session initialization
    * Custom session management workflows
    * Starting sessions with user context
  </Tab>

  <Tab value="updateSession()">
    Updates the current session with new user properties or session data. Works like an upsert operation - creates a session if one doesn't exist, or updates the existing session if it does. Primarily used when a user logs in after a session has already been started on the website.

    ```javascript
    // Update session when user logs in (after anonymous session was started)
    encatch.updateSession({
      user_name: 'UUID_OF_USER',
      '$set': {
        email: 'user@example.com',
        name: 'John Doe',
        plan: 'premium',
        last_login: '2025-01-20'
      },
      '$set_once': {
        first_login: '2025-01-15'
      }
    });

    // Update user properties during an active session
    encatch.updateSession({
      '$set': {
        plan: 'enterprise',
        role: 'admin',
        last_activity: '2025-01-20T10:30:00Z'
      },
      '$unset': ['trial_status']
    });
    ```

    **Use Cases:**

    * Updating anonymous session with user info after login
    * Changing user properties during active session
  </Tab>

  <Tab value="stopSession()">
    Terminates the current user session and clears all downloaded feedback configurations. If you want to switch to visitor mode after stopping a session, you need to explicitly start a new session.

    ```javascript
    // End current session (clears feedback configurations)
    encatch.stopSession();

    // To switch to visitor mode, start a new session
    encatch.startSession();
    ```

    **Use Cases:**

    * User logout (best use case - completely stops session and clears feedback configs)
    * Complete session termination
    * Clearing all user data and feedback configurations
  </Tab>

  <Tab value="resetSession()">
    Creates a new session while maintaining user identity. Useful for session refresh scenarios. Accepts a `type` parameter to control the reset behavior.

    ```javascript
    // Soft reset (default) - only resets session ID
    encatch.resetSession();
    encatch.resetSession({ type: 'soft' });

    // Hard reset - logs user out and switches to visitor mode
    encatch.resetSession({ type: 'hard' });
    ```

    **Reset Types:**

    * **`soft`** (default): Only resets the session ID. User identity and feedback configurations are maintained. Useful for applications with long session durations where you want to tag user actions during inactivity periods.
    * **`hard`**: Logs the user out and switches to visitor mode. Clears user identity and applies visitor-specific feedback configurations if configured.

    **Use Cases:**

    * Soft reset: Session renewal without re-authentication
    * Hard reset: Complete user logout and visitor mode switch
    * Maintaining user identity across session boundaries
  </Tab>
</Tabs>

### User Property Management

The SDK supports advanced property operations for user identification and session management. These operations allow you to set, update, and remove user properties with different behaviors.

<Tabs items={['Examples','Common Patterns','$set','$set_once','$counter','$unset']}>
  <Tab value="Examples">
    **Property Operations Overview**: Complete examples showing how all operations work together in real-world scenarios.

    ```javascript
    // 1. Start session with initial user data
    encatch.startSession({
      user_name: 'UUID_OF_USER',
      '$set': {
        email: 'john@example.com',
        name: 'John Doe',
        plan: 'free'
      },
      '$set_once': {
        signup_date: '2025-01-15',
        initial_referrer: 'google.com',
        original_plan: 'free'
      }
    });

    // 2. Update session when user logs in
    encatch.updateSession({
      '$set': {
        email: 'john.doe@company.com', // Updated email
        plan: 'premium',               // Upgraded plan
        last_login: '2025-01-20',
        company: 'Tech Corp'
      },
      '$set_once': {
        first_login: '2025-01-15',
        work_email_verified: true
      }
    });

    // 3. Track user engagement and metrics
    encatch.updateSession({
      '$counter': {
        login_count: 1,
        session_duration: 25, // minutes
        page_views: 8,
        features_used: 3
      }
    });

    // 4. Clean up deprecated properties
    encatch.updateSession({
      '$set': {
        plan: 'enterprise',
        status: 'active'
      },
      '$unset': ['trial_status', 'beta_features', 'deprecated_preferences']
    });
    ```
  </Tab>

  <Tab value="Common Patterns">
    **Common Workflow Patterns**: Real-world examples showing how property operations work together in typical application scenarios.

    ```javascript
    // Pattern 1: Anonymous → Authenticated User
    encatch.startSession(); // Start anonymous session
    // ... user browses ...
    encatch.updateSession({ user_name: 'user123', '$set': { email: 'user@example.com' } });

    // Pattern 2: User Profile Updates with Metrics
    encatch.updateSession({
      '$set': { name: 'New Name', preferences: { theme: 'dark' } },
      '$set_once': { name_change_count: 1 },
      '$counter': { profile_updates: 1, theme_changes: 1 }
    });

    // Pattern 3: Account Cleanup
    encatch.updateSession({
      '$set': { status: 'active' },
      '$unset': ['suspended_reason', 'old_email']
    });

    // Pattern 4: Session Reset during logout
    encatch.resetSession({ type: 'hard' });
    ```
  </Tab>

  <Tab value="$set">
    **Set Operation**: Overwrites existing property values or creates new ones. Used for mutable user data.

    ```javascript
    // Basic $set usage in updateSession
    encatch.updateSession({
      user_name: 'UUID_OF_USER',
      '$set': {
        email: 'user@example.com',
        name: 'John Doe',
        plan: 'premium',
        last_login: '2025-01-20',
        preferences: { theme: 'dark', notifications: true }
      }
    });

    // $set in startSession
    encatch.startSession({
      user_name: 'UUID_OF_USER',
      '$set': {
        email: 'user@example.com',
        signup_date: '2025-01-15'
      }
    });
    ```

    **Use Cases:**

    * Updating user profile information
    * Changing user preferences or settings
    * Modifying subscription plans or roles
    * Tracking last activity timestamps
  </Tab>

  <Tab value="$set_once">
    **Set Once Operation**: Sets a property value only if it doesn't already exist. Perfect for immutable data.

    ```javascript
    // Basic $set_once usage
    encatch.updateSession({
      '$set_once': {
        initial_referrer: 'google.com',
        signup_date: '2025-01-15',
        first_device: 'Chrome on MacOS',
        original_plan: 'free'
      }
    });

    // $set_once with $set
    encatch.updateSession({
      user_name: 'UUID_OF_USER',
      '$set': {
        email: 'newemail@example.com',
        plan: 'premium'
      },
      '$set_once': {
        first_login: '2025-01-15',
        referral_source: 'direct'
      }
    });
    ```

    **Use Cases:**

    * Tracking first-time user attributes
    * Recording signup information
    * Capturing initial referral sources
    * Storing original user state data
  </Tab>

  <Tab value="$counter">
    **Counter Operation**: Increments or decrements numeric property values with the value provided. Perfect for tracking usage metrics and counters.

    ```javascript
    // Basic $counter usage
    encatch.updateSession({
      '$counter': {
        login_count: 1, //incrementing login count
        happy_metric: -1, // an example where the user has been facing non 2xxx http status from the API
        purchase_total: 29.99,
        support_tickets: -1 // Can decrement too
      }
    });

    // $counter with other operations
    encatch.updateSession({
      user_name: 'UUID_OF_USER',
      '$set': {
        last_login: '2025-01-20',
        status: 'active'
      },
      '$set_once': {
        account_created: '2025-01-15'
      },
      '$counter': {
        total_logins: 1,
        session_count: 1,
      }
    });

    // Tracking user engagement
    encatch.updateSession({
      '$counter': {
        articles_read: 1,
        videos_watched: 2,
        downloads: 3,
        time_spent_minutes: 15
      }
    });
    ```

    **Use Cases:**

    * Tracking user engagement metrics (page views, logins, etc.)
    * Counting user actions and interactions
    * Managing usage quotas and limits
    * Decrementing counters (like remaining credits)

    **Notes:**

    * Counter operations on non-existent properties initialize them to the provided value
    * Supports both positive (increment) and negative (decrement) values
    * Works with integers and decimal numbers
  </Tab>

  <Tab value="$unset">
    **Unset Operation**: Removes properties from user profile. Useful for cleaning up deprecated data.

    ```javascript
    // Basic $unset usage
    encatch.updateSession({
      '$unset': ['old_property', 'deprecated_field', 'temporary_data']
    });

    // $unset with $set
    encatch.updateSession({
      '$set': {
        plan: 'enterprise',
        status: 'active'
      },
      '$unset': ['trial_status', 'beta_features', 'deprecated_preferences']
    });
    ```

    **Use Cases:**

    * Removing deprecated properties
    * Cleaning up temporary data
    * Clearing old user states
    * Removing obsolete user attributes
  </Tab>
</Tabs>

<Accordions type="single">
  <Accordion title="Property Operations Reference">
    | Operation  | Behavior                                  | Use Case                        |
    | ---------- | ----------------------------------------- | ------------------------------- |
    | `set`      | Overwrites existing property values       | Update user profile information |
    | `set_once` | Sets value only if property doesn't exist | Track initial user attributes   |
    | `counter`  | Adds to existing numeric values           | Increment usage counters        |
    | `unset`    | Removes properties from profile           | Clean up deprecated data        |

    **Important Notes:**

    * Property operations are processed in order: `set_once`, `set`, `counter`, `unset`
    * Counter operations on non-existent properties initialize them to the provided value
    * Use `set_once` for immutable historical data like signup date or initial referrer
  </Accordion>
</Accordions>

### Triggers

The e-Ncatch SDK provides comprehensive event tracking capabilities with four distinct approaches: automatic event capture for common interactions, custom event tracking for business-specific metrics, scroll event tracking for engagement analysis, and manual feedback control for programmatic trigger management.

<Tabs items={['Manual','Automatic','Custom Event','Scroll Event']}>
  <Tab value="Manual">
    ### Programmatic Feedback Display

    Override automatic triggering with manual control over feedback form presentation.

    <Tabs items={['openFeedbackById()','openFeedbackByName()']}>
      <Tab value="openFeedbackById()">
        Display a specific feedback form by its unique identifier.

        **Example Usage:**

        ```javascript
        // Basic usage
        encatch.openFeedbackById('feedback_config_123');

        // With theme and language overrides
        encatch.openFeedbackById('feedback_config_123', 'dark', 'es');

        // With event context for tracking
        encatch.openFeedbackById('feedback_config_123', 'light', 'en', 'button_click');
        ```

        **Use Cases:**

        * Programmatic feedback form display
        * Integration with existing UI components
        * Custom feedback triggers
        * A/B testing specific feedback forms

        **Parameters:**

        <TypeTable
          type={{
      feedbackId: {
        description: 'Unique feedback configuration ID',
        type: 'string',
        required: true
      },
      theme: {
        description: 'Override default theme for the feedback form',
        type: '"light" | "dark"',
        default: 'Current theme setting',
        required: false
      },
      language: {
        description: 'Override default language for the feedback form',
        type: 'string',
        default: 'Current language setting',
        required: false
      },
      eventContext: {
        description: 'Event context for analytics and tracking',
        type: 'string',
        default: 'undefined',
        required: false
      }
    }}
        />
      </Tab>

      <Tab value="openFeedbackByName()">
        Display a feedback form by its configured title/name.

        **Example Usage:**

        ```javascript
        // Open by form title
        encatch.openFeedbackByName('Product Satisfaction Survey');

        // With customization options
        encatch.openFeedbackByName('Feature Feedback', 'dark', 'fr', 'feature_usage');
        ```

        **Use Cases:**

        * Content-driven feedback display
        * User-friendly feedback triggers
        * CMS integration scenarios
        * Non-technical implementation

        **Parameters:**

        <TypeTable
          type={{
      feedbackTitle: {
        description: 'Display name of the feedback form',
        type: 'string',
        required: true
      },
      theme: {
        description: 'Override default theme for the feedback form',
        type: '"light" | "dark"',
        default: 'Current theme setting',
        required: false
      },
      language: {
        description: 'Override default language for the feedback form',
        type: 'string',
        default: 'Current language setting',
        required: false
      },
      eventContext: {
        description: 'Event context for analytics and tracking',
        type: 'string',
        default: 'undefined',
        required: false
      }
    }}
        />
      </Tab>
    </Tabs>

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

  <Tab value="Automatic">
    **Auto-captured Events**: The SDK automatically tracks common user interactions and page events without any manual implementation required.

    <Accordions type="single">
      <Accordion title="Properties">
        | Event              | Description                             | Properties                                               |
        | ------------------ | --------------------------------------- | -------------------------------------------------------- |
        | `page_view`        | Page navigation and route changes       | `path`, `title`, `referrer`, `timestamp`                 |
        | `session_start`    | User session initialization             | `session_id`, `user_agent`, `device_info`                |
        | `click`            | User clicks on interactive elements     | `element_id`, `element_type`, `location`, `text_content` |
        | `form_interaction` | Form field focus, input, and validation | `field_name`, `field_type`, `interaction_type`           |
        | `error`            | JavaScript errors and exceptions        | `message`, `stack_trace`, `line_number`, `column_number` |
        | `performance`      | Page load and performance metrics       | `load_time`, `dom_content_loaded`, `first_paint`         |
      </Accordion>
    </Accordions>

    **Configuration:**

    ```javascript
    // Disable automatic event tracking
    encatch.init('<YOUR_PROJECT_API_KEY>', {
      isAutoCaptureEnabled: false
    });

    // Enable specific auto-events only
    encatch.init('<YOUR_PROJECT_API_KEY>', {
      isAutoCaptureEnabled: true,
      autoCaptureConfig: {
        pageViews: true,
        clicks: true,
        errors: true,
        performance: false,
        forms: true
      }
    });
    ```

    **Use Cases:**

    * Basic user behavior analytics without custom implementation
    * Page engagement and navigation tracking
    * Error monitoring and debugging
    * Performance analysis
    * Form abandonment analysis

    **Automatic Context Enrichment:**
    All auto-captured events are automatically enhanced with:

    * Current page path and title
    * Session information and user identity
    * Device and browser metadata
    * Timestamp and user agent
    * Geographic location (if available)
  </Tab>

  <Tab value="Custom Event">
    **Custom Events**: Track specific events that are unique to your application's needs and business logic using the `trackEvent` method.

    **`trackEvent(eventName, properties?)`**

    **Use Cases:**

    * User behavior analytics
    * Feature usage tracking
    * Conversion funnel analysis
    * Custom business metrics
    * Application-specific interactions
    * A/B test tracking
    * User journey mapping

    **Parameters:**

    <TypeTable
      type={{
    eventName: {
      description: 'Unique identifier for the event',
      type: 'string',
      required: true
    },
    properties: {
      description: 'Additional event metadata and context',
      type: 'object',
      default: 'undefined',
      required: false
    }
  }}
    />

    **Example Usage:**

    ```javascript
    // Basic event tracking
    encatch.trackEvent('page_view');

    // E-commerce events
    encatch.trackEvent('purchase_completed', {
      productId: 'prod_123',
      amount: 99.99,
      currency: 'USD',
      category: 'electronics',
      quantity: 2,
      payment_method: 'credit_card'
    });

    // User interaction tracking
    encatch.trackEvent('button_click', {
      buttonId: 'cta-subscribe',
      location: 'hero-section',
      action: 'newsletter_signup',
      timestamp: Date.now()
    });

    // Feature usage tracking
    encatch.trackEvent('feature_used', {
      feature: 'advanced_search',
      filters_applied: ['price', 'category', 'rating'],
      results_count: 25,
      search_time: 1.2
    });

    // Video engagement
    encatch.trackEvent('video_interaction', {
      video_id: 'tutorial_101',
      action: 'play',
      current_time: 45,
      total_duration: 180,
      quality: '720p'
    });

    // Form analytics
    encatch.trackEvent('form_step_completed', {
      form_name: 'onboarding',
      step: 2,
      step_name: 'personal_info',
      time_spent: 120,
      completion_rate: 0.75
    });
    ```

    **Event Enhancement:**
    The SDK automatically enriches tracked events with:

    * Current page path and title
    * Session information and user identity
    * Device and browser metadata
    * Timestamp and user agent
    * Geographic location (if available)

    <Accordions type="single">
      <Accordion title="Enhanced Event Tracking">
        **Automatic Context Enrichment**

        All tracked events are automatically enhanced with contextual information:

        ```javascript
        // Basic event call
        encatch.trackEvent('purchase_completed', {
          product_id: 'item_123',
          amount: 99.99
        });

        // Automatically enhanced with:
        // {
        //   product_id: 'item_123',
        //   amount: 99.99,
        //   path: '/checkout/success',        // Current page path
        //   event: 'purchase_completed',      // Event name
        //   timestamp: 1642694400000,         // Unix timestamp
        //   session_id: 'sess_abc123',        // Session identifier
        //   user_agent: 'Mozilla/5.0...',     // Browser information
        //   referrer: 'https://google.com',   // Page referrer
        //   viewport: '1920x1080'             // Screen resolution
        // }
        ```

        **Event-Driven Feedback Triggers**

        Events can automatically trigger relevant feedback forms based on your configuration:

        ```javascript
        // E-commerce example
        encatch.trackEvent('purchase_completed', {
          order_id: 'order_123',
          total: 149.99,
          items_count: 3
        });
        // May trigger post-purchase satisfaction survey

        // Feature usage example
        encatch.trackEvent('feature_used', {
          feature: 'advanced_search',
          user_type: 'premium',
          success: true
        });
        // May trigger feature-specific feedback form

        // Support interaction example
        encatch.trackEvent('support_chat_ended', {
          duration: 180, // seconds
          resolved: true,
          agent_id: 'agent_456'
        });
        // May trigger support experience survey
        ```
      </Accordion>
    </Accordions>
  </Tab>

  <Tab value="Scroll Event">
    **Scroll Events**: Track user engagement and reading behavior through scroll depth analytics, perfect for content optimization and user experience insights.

    **`captureScrollEvent(scrollPercent)`**

    **Use Cases:**

    * Content engagement analysis
    * Reading behavior tracking
    * Page performance optimization
    * A/B testing scroll depth
    * Content length optimization
    * User experience research
    * Conversion funnel analysis

    **Parameters:**

    <TypeTable
      type={{
    scrollPercent: {
      description: 'Percentage scrolled (0-100)',
      type: 'number',
      required: true
    }
  }}
    />

    **Example Usage:**

    ```javascript
    // Basic page scroll tracking
    window.addEventListener('scroll', () => {
      const scrollPercent = Math.round(
        (window.scrollY / (document.documentElement.scrollHeight - window.innerHeight)) * 100
      );
      encatch.captureScrollEvent(scrollPercent);
    });

    // Article reading progress
    const articleElement = document.getElementById('article-content');
    articleElement.addEventListener('scroll', () => {
      const scrollPercent = Math.round(
        (articleElement.scrollTop / (articleElement.scrollHeight - articleElement.clientHeight)) * 100
      );
      encatch.captureScrollEvent(scrollPercent);
    });

    // Custom container scroll tracking
    const scrollableDiv = document.getElementById('product-list');
    scrollableDiv.addEventListener('scroll', () => {
      const scrollPercent = Math.round(
        (scrollableDiv.scrollTop / (scrollableDiv.scrollHeight - scrollableDiv.clientHeight)) * 100
      );
      encatch.captureScrollEvent(scrollPercent);
    });

    // Manual scroll capture
    encatch.captureScrollEvent(25);  // 25% scrolled
    encatch.captureScrollEvent(50);  // 50% scrolled
    encatch.captureScrollEvent(75);  // 75% scrolled
    encatch.captureScrollEvent(100); // 100% scrolled
    ```

    **Scroll Milestones:**

    ```javascript
    // Track common scroll milestones
    const milestones = [25, 50, 75, 100];
    let trackedMilestones = new Set();

    window.addEventListener('scroll', () => {
      const scrollPercent = Math.round(
        (window.scrollY / (document.documentElement.scrollHeight - window.innerHeight)) * 100
      );

      milestones.forEach(milestone => {
        if (scrollPercent >= milestone && !trackedMilestones.has(milestone)) {
          encatch.captureScrollEvent(milestone);
          trackedMilestones.add(milestone);

          // Optional: Track milestone achievement
          encatch.trackEvent('scroll_milestone_reached', {
            milestone: milestone,
            page: window.location.pathname,
            time_to_reach: Date.now() - pageLoadTime
          });
        }
      });
    });
    ```

    > **Note:** This method accepts a single number representing the scroll percentage (0-100). Your application must calculate the scroll percentage from any scrollable element before passing it to the method.

    **Best Practices:**

    * Use throttling/debouncing for scroll event listeners to avoid performance issues
    * Track scroll milestones (25%, 50%, 75%, 100%) for content engagement analysis
    * Combine scroll tracking with custom events for comprehensive user journey analysis
    * Consider privacy implications and implement appropriate user consent
  </Tab>
</Tabs>

### UI Customization

Dynamically control the appearance and localization of feedback forms and interfaces.

<Tabs items={['Theme','Language']}>
  <Tab value="Theme">
    **`setThemeMode(theme)`**

    <TypeTable
      type={{
  theme: {
    description: 'Theme mode for the interface',
    type: '"light" | "dark"',
    required: true
  }
}}
    />

    **Example Usage:**

    ```javascript
    // Basic theme switching
    encatch.setThemeMode('dark');   // Switch to dark theme
    encatch.setThemeMode('light');  // Switch to light theme

    ```

    **Use Cases:**

    * Dark mode toggle implementation
    * System theme synchronization
    * User preference persistence
    * Accessibility compliance
  </Tab>

  <Tab value="Language">
    **`setLanguage(languageCode)`**

    <TypeTable
      type={{
  languageCode: {
    description: 'ISO 639-1 language code for UI localization',
    type: 'string',
    required: true
  }
}}
    />

    **Example Usage:**

    ```javascript
    // Language localization
    encatch.setLanguage('es');      // Spanish
    encatch.setLanguage('fr');      // French
    encatch.setLanguage('de');      // German
    encatch.setLanguage('YOUR_ADMIN_CONFIG_LANGUAGE_CODE');
    ```

    **Use Cases:**

    * Internationalization (i18n) implementation
    * Multi-language application support
    * User language preference persistence
    * Browser language detection and fallback

    > **Note:** Language changes affect all subsequent feedback forms. You may ideally call this when user switches languages in your application.
  </Tab>
</Tabs>

### Advanced SDK Methods

<Accordions type="single">
  <Accordion title="Advanced SDK Methods">
    <Tabs items={['Refresh Feedbacks','Validate Feedback Ids']}>
      <Tab value="Refresh Feedbacks">
        Force refresh of available feedback configurations from the server.

        **Use Cases:**

        * After user role changes that affect feedback eligibility
        * When user properties are updated that impact targeting
        * To ensure the latest feedback configurations are available
        * During application state transitions

        **Example Usage:**

        ```javascript
        // Refresh feedback configurations
        encatch.forceFetchEligibleFeedbacks();

        // Typical usage after user identification
        encatch.identify('user_123', { role: 'premium' });
        encatch.forceFetchEligibleFeedbacks(); // Fetch premium-specific feedback
        ```

        > **Performance Note:** This method triggers an immediate API call. Use sparingly and only when necessary to avoid unnecessary server load.
      </Tab>

      <Tab value="Validate Feedback Ids">
        Validate which feedback configuration IDs are currently available and eligible for the user.

        <TypeTable
          type={{
          feedbackIds: {
            description: 'Array of feedback configuration IDs to validate',
            type: 'string[]',
            required: true
          }
        }}
        />

        **Returns:** `string[]` - Array of valid, eligible feedback IDs

        **Example Usage:**

        ```javascript
        const feedbackIds = ['config_123', 'config_456', 'config_789'];
        const validIds = encatch.verifyFeedbackIds(feedbackIds);


        // Output: ['config_123', 'config_789']

        // Use valid IDs for conditional display
        if (validIds.includes('config_123')) {
          // Show feedback trigger button
          document.getElementById('feedback-btn').style.display = 'block';
        }
        ```
      </Tab>
    </Tabs>
  </Accordion>
</Accordions>


# Next.js (/docs/framework-examples/ui-frameworks/nextjs)
# Next.js

## Overview

## Getting started


# React.js (/docs/framework-examples/ui-frameworks/reactjs)
# React.js

## Overview

## Getting started


# Overview (/docs/developer-guide/data-pipelines/destination)
## What are Destinations?

Destinations are external systems and services where Encatch automatically delivers your feedback responses.

### Use cases for destinations

* You want to send feedback responses when you receive a new feedback response to your email inbox
* Report to team members when you receive a new feedback response mentioned as a bug or issue
* Trigger a workflow with Zappier, n8n, MS power automate, etc. or your own custom webhook endpoint on a specific feedback response

### Available Destinations

Below are the list of available destinations:

* **Email**: Send feedback responses to your email inbox
* **Slack**: Send feedback responses to your Slack channel as a message
* **GitLab**: Create an issue in your GitLab repository based on the feedback response
* **Jira**: Create an issue in your Jira project based on the feedback response
* **Webhook**: Send feedback responses to your custom webhook endpoint (that can be used with Zappier, n8n, MS power automate, etc. or your own custom webhook endpoint)

### How to configure a destination?

1. To configure a destination, you need to go to the **Data Pipelines** section of the application and click on the **Destinations**.
2. Then, you need to click on the **Add Destination** button.
3. Then, you need to select the destination type, choose the feedback form and configure the destination details.
4. Then, you need to click on the **Save** button.

### Destination Filters

You can choose to filter unwanted feedback responses before they are sent to the destination. Use the AI filter to filter unwanted feedback responses based on the feedback response content, rating, etc.

### Other options

* Before you enable the destination, you can test the destination by clicking on the **Test** button.
* You can temporarily disable the destination to stop it from processing any feedback responses