# Configuration (/docs/getting-started/configuration)





# Configuration [#configuration]

In this section, we will explore the various configuration options available in Ucoder Insight. Proper configuration is essential to ensure that you get the most out of the tool and that it fits seamlessly into your development workflow.

## General Settings [#general-settings]

The general settings allow you to customize the overall behavior of Ucoder Insight. This includes options for data collection, performance optimization, and user interface preferences.

### API Keys [#api-keys]

To use Ucoder Insight, you need your project's keys from the Ucoder Dashboard (`Settings` > `General`). There are three types of identifiers:

#### Public Tracking ID [#public-tracking-id]

The Public Tracking ID is used for client-side tracking and should be included in your frontend code. It is safe to expose publicly.

#### Secret Key [#secret-key]

This key is used for server-side applications and has full permissions. It should be kept secure and never exposed in client-side code. It is needed for features that require access to sensitive data or actions, such as managing projects or accessing detailed analytics.

#### Domain Ownership ID [#domain-ownership-id]

This key is used to identify the owner of the project. It is used for features that require ownership verification, such as transferring project ownership or accessing certain administrative features.

<Image src="/docs_img/keys.png" alt="Ucoder Insight API Keys" width="1200" height="675" className="w-full h-auto mt-6 mb-8 border rounded-lg object-cover" />

<Callout type="info" title="Note">
  Your Public Tracking ID is safe to expose in client-side code — you do not need to hide it behind a server. Your Secret Key is different and must never be exposed publicly.
</Callout>

### Options Reference [#options-reference]

Here is a reference of the available configuration options in Ucoder Insight:

| Option Name        | Type                   | Default Value  | Description                                                                    |
| :----------------- | :--------------------- | :------------- | :----------------------------------------------------------------------------- |
| `notFoundPath`     | `string` \| `string[]` | `"autodetect"` | Path(s) treated as a 404. Auto-detected by default; not tracked as a pageview. |
| `notTrackPath`     | `string` \| `string[]` | `[]`           | The paths to exclude from tracking.                                            |
| `debug`            | `boolean`              | `false`        | Enable debug mode for detailed logging.                                        |
| `apiUrl`           | `string`               | `undefined`    | Your custom backend URL.                                                       |
| `trackScroll`      | `false`                | `false`        | Pro plan opt-out only. See note below.                                         |
| `trackPerformance` | `false`                | `false`        | Pro plan opt-out only. See note below.                                         |

<Callout type="info" title="About trackScroll and trackPerformance">
  These two options are Pro-plan-only local opt-outs. Their type is intentionally
  `false` (not `boolean`) — passing `true` is a compile-time error, since "forcing
  on" is never a valid local override. Free plan users cannot set these options at all.
</Callout>

### `notFoundPath` [#notfoundpath]

By default, Ucoder Insight **automatically detects 404 / not-found pages** — for
example, when a user hits a broken or non-existent route in a Next.js app.
These pages are excluded from your page analytics automatically, so random or
invalid URLs don't pollute your dashboard with noisy, one-off page entries.

If your app uses a custom 404 route (not the framework default), or you want
to explicitly mark additional paths as "not found," you can override the
autodetected behavior by passing your own path(s):

```javascript
initUcoderInsight("YOUR_PUBLIC_TRACKING_ID", {
  notFoundPath: '/my-custom-404',
  // or an array:
  // notFoundPath: ['/my-custom-404', '/gone'],
});
```

Supports wildcards, e.g. `'/notfound/*'`.

<Callout type="info" title="Note">
  In most cases, you don't need to set this option manually — autodetection
  handles standard 404 pages out of the box. Only override it if your app uses
  a non-standard not-found route.
</Callout>

### `notTrackPath` [#nottrackpath]

This option allows you to specify a path or an array of paths that should be
excluded from tracking. By default, it is set to `[]`, meaning all paths are
tracked. Use this if you have pages you don't want analytics on — for example,
internal admin routes or legal pages.

```javascript
notTrackPath: ['/privacy', '/terms', '/admin/*']
```

### `debug` [#debug]

This option enables debug mode, which provides detailed logging of Ucoder
Insight's operations in the browser console. By default, it is set to `false`.

<Callout type="warn" title="Note">
  When debug mode is enabled, no data is sent to our servers — all events are
  logged to the console only. This is useful for development and troubleshooting,
  but it will not produce real analytics data. Only use this in development.
</Callout>

### `trackScroll` [#trackscroll]

Controls scroll-depth tracking. This is a **Pro plan** local opt-out — it lets
Pro users disable a feature they don't need. Free plan users do not have
scroll tracking enabled by default and cannot toggle this option.

### `trackPerformance` [#trackperformance]

Controls performance metric tracking (page load times, resource usage, Core
Web Vitals). This is a **Pro plan** local opt-out — it lets Pro users disable
a feature they don't need. Free plan users do not have performance tracking
enabled by default and cannot toggle this option.

### `apiUrl` [#apiurl]

Optional custom API URL for sending tracking data. If not provided, the
default API endpoint is used. This can be useful for testing or if you have a
custom backend setup.

<Callout type="info" title="Note">
  Project verification and tracking configuration are always handled through
  the default backend, regardless of a custom `apiUrl`. This keeps sensitive
  configuration data isolated from custom backend URLs, preserving the security
  and integrity of your tracking setup.
</Callout>

### Example Usage [#example-usage]

Here is a complete example configuring Ucoder Insight with all available options:

<Tabs items="['npm', 'pnpm']" groupId="package-manager">
  <Tab value="npm">
    ```bash
    npm install ucoder-insight
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add ucoder-insight
    ```
  </Tab>
</Tabs>

<Tabs items="['Next.js', 'React', 'Vanilla JS']">
  <Tab value="Next.js">
    <div className="flex items-center gap-2 mb-4 text-primary font-semibold">
      <Code2 className="h-5 w-5" />

      <span>
        Next.js Configuration
      </span>
    </div>

    <p className="text-sm text-muted-foreground mb-4">
      Pass options as the second argument to 

      `initUcoderInsight`

      .
    </p>

    ```tsx title="app/analytics.tsx"
    "use client";
    import { useEffect } from "react";
    import { initUcoderInsight } from "ucoder-insight";

    export default function Analytics() {
      useEffect(() => {
        initUcoderInsight("YOUR_PUBLIC_TRACKING_ID", {
          notFoundPath: '/404',
          notTrackPath: ['/privacy', '/terms', '/admin/*'],
          debug: true, // logs events to console instead of sending to API
          apiUrl: 'https://custom-api.yourdomain.com/track', // optional custom backend
          trackPerformance: false, // Pro plan opt-out only
          trackScroll: false, // Pro plan opt-out only
        });
      }, []);

      return null;
    }
    ```
  </Tab>

  <Tab value="React">
    <div className="flex items-center gap-2 mb-4 text-primary font-semibold">
      <Code2 className="h-5 w-5" />

      <span>
        React Configuration
      </span>
    </div>

    <p className="text-sm text-muted-foreground mb-4">
      Set up Ucoder Insight in your React application.
    </p>

    ```tsx title="src/Analytics.tsx"
    import { useEffect } from "react";
    import { initUcoderInsight } from "ucoder-insight";

    export default function Analytics() {
      useEffect(() => {
        initUcoderInsight("YOUR_PUBLIC_TRACKING_ID", {
          notFoundPath: '/404',
          notTrackPath: ['/privacy', '/terms', '/admin/*'],
          debug: true, // logs events to console instead of sending to API
          apiUrl: 'https://custom-api.yourdomain.com/track', // optional custom backend
          trackPerformance: false, // Pro plan opt-out only
          trackScroll: false, // Pro plan opt-out only
        });
      }, []);

      return null;
    }
    ```
  </Tab>

  <Tab value="Vanilla JS">
    <div className="flex items-center gap-2 mb-4 text-primary font-semibold">
      <Code2 className="h-5 w-5" />

      <span>
        Vanilla JavaScript Configuration
      </span>
    </div>

    <p className="text-sm text-muted-foreground mb-4">
      Initialize Ucoder Insight directly in your HTML.
    </p>

    ```html title="index.html"
    <script defer src="https://cdn.jsdelivr.net/npm/ucoder-insight"></script>
    <script>
      window.addEventListener('ucoderInsightReady', () => {
        ucoderInsight.init("YOUR_PUBLIC_TRACKING_ID", {
          // Optional: override auto-detected 404 path. Supports wildcards e.g. '/notfound/*'
          // Default: autodetect
          notFoundPath: '/my-custom-404',

          notTrackPath: ['/privacy', '/terms', '/admin/*'],
          trackPerformance: false, // Pro plan opt-out only
          trackScroll: false, // Pro plan opt-out only
        });
      });
    </script>
    ```

    Be sure to include the initialization script after the Ucoder Insight CDN script tag in your HTML file.
  </Tab>
</Tabs>

***

## Element-Level Tracking Control [#element-level-tracking-control]

To exclude a specific element from tracking, add the `data-uca-track="false"` attribute to any HTML element. This is useful for sensitive information or elements that don't need analytics.

```html
<button data-uca-track="false" class="px-4 py-2 bg-red-500 text-white rounded">
  This content will not be tracked by Ucoder Insight.
</button>
```

You can also use `data-uca-track="true"` to force tracking on a specific element even if it falls within a `notTrackPath`.

***

### Input Tracking Policy [#input-tracking-policy]

<div className="grid grid-cols-1 sm:grid-cols-2 gap-4 my-6">
  <div className="border rounded-lg p-4 bg-red-50/50 border-red-200 dark:bg-red-950/10 dark:border-red-900/30">
    <div className="flex items-center gap-2 font-semibold text-red-600 dark:text-red-400 mb-3">
      <Lock className="w-4 h-4" />

      Automatically Blocked Inputs
    </div>

    <ul className="space-y-2 text-sm text-muted-foreground">
      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="password"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="email"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="tel"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="text"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="number"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="search"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="url"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="date"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="time"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="datetime-local"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="month"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="week"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="color"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="range"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="file"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-red-400" />

        <code className="text-xs">type="hidden"</code>
      </li>
    </ul>
  </div>

  <div className="border rounded-lg p-4 bg-emerald-50/50 border-emerald-200 dark:bg-emerald-950/10 dark:border-emerald-900/30">
    <div className="flex items-center gap-2 font-semibold text-emerald-600 dark:text-emerald-400 mb-3">
      <CheckCircle2 className="w-4 h-4" />

      Tracked Input Types
    </div>

    <ul className="space-y-2 text-sm text-muted-foreground">
      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-emerald-400" />

        <code className="text-xs">type="checkbox"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-emerald-400" />

        <code className="text-xs">type="radio"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-emerald-400" />

        <code className="text-xs">type="submit"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-emerald-400" />

        <code className="text-xs">type="button"</code>
      </li>

      <li className="flex items-center gap-2">
        <span className="w-1.5 h-1.5 rounded-full bg-emerald-400" />

        <code className="text-xs">type="reset"</code>
      </li>
    </ul>

    <div className="mt-4 pt-4 border-t border-emerald-200 dark:border-emerald-900/30">
      <div className="text-xs text-muted-foreground">
        These input types are safe to track as they don't contain sensitive user data.
      </div>
    </div>
  </div>
</div>

<Callout type="info" title="Privacy Assurance" icon="<Shield className=&#x22;h-4 w-4&#x22; />">
  Our "Privacy by Default" engine ensures that sensitive user data remains on
  the client device and is never sent to our servers. You only need to use
  `data-uca-track="false"` for non-sensitive UI elements you wish to exclude.
</Callout>