Milana

Session recording and analytics SDK for web applications. Milana captures user sessions using rrweb and sends them to the Milana ingest API for replay and analysis.

Installation

npm install milana-js

React (Recommended)

Wrap your application with MilanaProvider near the root of the component tree:

import { MilanaProvider } from "milana-js/react";

function App() {
  return (
    <MilanaProvider
      productId="prd_YOUR_PRODUCT_ID"
      clientKey="key_YOUR_CLIENT_KEY"
      sessionInfo={{
        environment: "production",
        version: "1.2.0",
      }}
    >
      <YourApp />
    </MilanaProvider>
  );
}

Use the useMilana() hook to access the SDK from any component. Call update to identify the user — typically after login or when auth state resolves:

import { useMilana } from "milana-js/react";

function Dashboard() {
  const { user } = useAuth(); // Clerk, Better Auth, Auth0, etc.
  const { update, trackEvent } = useMilana();

  useEffect(() => {
    if (user) {
      void update({
        user: { userId: user.id, email: user.email, name: user.name },
      });
    }
  }, [user, update]);

  return (
    <button onClick={() => trackEvent("export_clicked", { format: "csv" })}>
      Export
    </button>
  );
}

useMilana

| Property | Type | Description | |---|---|---| | update | (input: UpdateInput) => Promise<{ success: boolean }> | Update session metadata or user identity. See UpdateInput. | | trackEvent | (eventName: string, attributes?: TrackEventAttributes) => void | Track a custom event. Calls are queued until initialization completes. See TrackEventAttributes. | | isInitialized | boolean | true after init() has completed successfully |

Vanilla JS (ESM)

import { init, update, trackEvent } from "milana-js";

await init("prd_YOUR_PRODUCT_ID", "key_YOUR_CLIENT_KEY", {
  environment: "production",
  version: "1.2.0",
});

await update({
  user: { userId: "usr_12345", email: "[email protected]" },
});

trackEvent("feature_used", { featureName: "export", format: "csv" });

Script Tag / CDN

For applications that do not use a bundler:

<script>
  window._milanaQueue = window._milanaQueue || [];
  function Milana() { window._milanaQueue.push([].slice.call(arguments)); }
</script>
<script async src="https://cdn.getmilana.ai/milana.js"></script>

<script>
  Milana("init", "prd_YOUR_PRODUCT_ID", "key_YOUR_CLIENT_KEY", {
    environment: "production",
    version: "1.2.0",
  });
</script>

After the SDK loads, call the API via the queue syntax or the direct API:

Milana("update", { user: { userId: "usr_12345", email: "[email protected]" } });
Milana("trackEvent", "button_clicked", { buttonId: "signup" });

User Identity

Call update() with user information as soon as authentication resolves:

await update({
  user: {
    userId: "usr_12345",           // Required: stable unique identifier
    email: "[email protected]",     // Strongly recommended
    name: "Jane Smith",            // Optional
    metadata: {
      plan: "enterprise",          // Optional
      createdAt: "2024-01-15",     // Strongly recommended
    },
  },
});

Event Tracking

trackEvent("signup_completed");
trackEvent("item_purchased", { itemId: "sku_789", price: 29.99 });

Attribute values can be string, number, boolean, or null.

Privacy

CSS class-based privacy controls:

| Class | Effect | |---|---| | milana-block | Element and children replaced with a placeholder | | milana-mask | Text and input values replaced with asterisks | | milana-ignore | User interactions not recorded (visual appearance still captured) |

password and tel inputs are always masked. Override class names via options.privacy.

Debug Mode

Enable debug mode to log init, update, identify, and trackEvent calls to the browser console. Open the browser console and run:

Milana.setDebugMode(true)

Then reload the page. API calls will be logged as Milana [debug]: ... messages in the console. The setting persists in localStorage across page reloads.

To disable:

Milana.setDebugMode(false)

For ESM users without window.Milana, you can set it directly in the browser console:

localStorage.setItem("milana_debug_mode", "true")

Configuration Reference

init(productId, clientKey, sessionInfo, options?)

| Parameter | Type | Description | |---|---|---| | productId | string | Your Milana product ID (format: prd_...) | | clientKey | string | Your Milana client key (format: key_...) | | sessionInfo | SessionInfo | Session context — see SessionInfo | | options | PublicInitOptions | Optional SDK configuration |

PublicInitOptions

| Option | Type | Default | Description | |---|---|---|---| | endpoint | string | "https://in.getmilana.ai" | Ingest API base URL | | shouldRecordCanvas | boolean | false | Record canvas element contents | | shouldRecordCrossOriginIframes | boolean | false | Record cross-origin iframe contents | | privacy | Partial<InitPrivacyOptions> | See source | Privacy controls |

SessionInfo

| Field | Type | Description | |---|---|---| | environment | string | Deployment environment (e.g. "production", "staging") | | version | string | Application version | | metadata | Record<string, unknown> | Arbitrary key-value pairs (optional) |

UpdateInput

| Field | Type | Description | |---|---|---| | session | object | Session metadata to merge (optional) | | session.metadata | Record<string, unknown> | Arbitrary key-value pairs attached to the session | | user | object | User identity (optional) | | user.userId | string | Stable unique identifier (required when user is provided) | | user.email | string | User email (optional) | | user.name | string | Display name (optional) | | user.metadata | Record<string, unknown> | Arbitrary key-value pairs attached to the user (optional) |

TrackEventAttributes

Record<string, string | number | boolean | null>

A flat object of attribute values to attach to a custom event. Keys are strings; values can be string, number, boolean, or null.

License

MIT