> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmilana.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> A reference for the Milana SDK — available as an npm package with React bindings and as a CDN script tag.

The Milana SDK records user sessions and provides methods to initialize recording, identify users, update session metadata, track custom events, and stop recording.

## Installation

<Tabs>
  <Tab title="React">
    ```bash theme={null}
    npm install milana-js
    ```

    Import from `milana-js/react` for React bindings — `MilanaProvider`, `useMilana`, `useMilanaOptional`.

    See [React Setup](/quickstart/react) for the full setup guide.
  </Tab>

  <Tab title="JavaScript">
    ```bash theme={null}
    npm install milana-js
    ```

    Import from `milana-js` for the core SDK — `init`, `identify`, `updateUser`, `updateSession`, `trackEvent`, `stopRecording`.

    See [JavaScript Setup](/quickstart/js-package) for the full setup guide.
  </Tab>

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

    See [Script Tag Setup](/quickstart/script-tag) for the full setup guide.
  </Tab>
</Tabs>

## API surface

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    import { MilanaProvider, useMilana, useMilanaOptional } from "milana-js/react";

    // Wrap your app to auto-initialize recording
    <MilanaProvider
      productId="prd_..."
      clientKey="key_..."
      sessionInfo={{ environment: "production", version: "1.0.0" }}
    >
      <App />
    </MilanaProvider>

    // Access SDK methods from any component
    const {
      initialize,
      isInitialized,
      identify,
      updateUser,
      updateSession,
      trackEvent,
      stopRecording,
    } = useMilana();
    ```

    | Property        | Type                                                             | Description                                                            |
    | --------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
    | `initialize`    | `() => Promise<{ success: boolean }>`                            | Trigger initialization manually (for deferred init).                   |
    | `isInitialized` | `boolean`                                                        | `true` after init has completed successfully.                          |
    | `identify`      | `(input: IdentifyInput) => Promise<{ success: boolean }>`        | Associate the session with a known user (requires `userId` + `email`). |
    | `updateUser`    | `(user: UserUpdate) => Promise<{ success: boolean }>`            | Refresh user identity (`email` optional).                              |
    | `updateSession` | `(session: SessionUpdate) => Promise<{ success: boolean }>`      | Update session metadata.                                               |
    | `trackEvent`    | `(eventName: string, attributes?: TrackEventAttributes) => void` | Track a custom event.                                                  |
    | `stopRecording` | `() => Promise<{ success: boolean }>`                            | End the current session; next `init()` starts a fresh one.             |
    | `update`        | `(payload: UpdatePayload) => Promise<{ success: boolean }>`      | **Deprecated** — prefer `identify` / `updateUser` / `updateSession`.   |
  </Tab>

  <Tab title="JavaScript">
    ```typescript theme={null}
    import {
      init,
      identify,
      updateUser,
      updateSession,
      trackEvent,
      stopRecording,
    } from "milana-js";

    await init("prd_...", "key_...", { environment: "production", version: "1.0.0" });
    await identify({ userId: "usr_123", email: "jane@example.com" });
    await updateUser({ userId: "usr_123", metadata: { plan: "pro" } });
    await updateSession({ metadata: { flow: "onboarding" } });
    trackEvent("button_clicked", { buttonId: "signup" });
    await stopRecording();
    ```
  </Tab>

  <Tab title="Script Tag">
    Call methods via the `Milana()` queue function:

    ```javascript theme={null}
    Milana("init", "prd_...", "key_...", { environment: "production", version: "1.0.0" });
    Milana("identify", { userId: "usr_123", email: "jane@example.com" });
    Milana("updateUser", { userId: "usr_123", metadata: { plan: "pro" } });
    Milana("updateSession", { metadata: { flow: "onboarding" } });
    Milana("trackEvent", "button_clicked", { buttonId: "signup" });
    Milana("stopRecording");
    Milana("initCrossOriginIframe");
    ```
  </Tab>
</Tabs>

## Method pages

<CardGroup cols={2}>
  <Card title="Initialize" icon="play" href="/sdk/init">
    Start recording with your product ID, client key, and session info.
  </Card>

  <Card title="Identify" icon="user" href="/sdk/identify">
    Associate sessions with known users using `identify()`.
  </Card>

  <Card title="Update User" icon="user-pen" href="/sdk/update-user">
    Refresh user identity mid-session with `updateUser()`.
  </Card>

  <Card title="Update Session" icon="layer-group" href="/sdk/update-session">
    Attach session-level context with `updateSession()`.
  </Card>

  <Card title="Track events" icon="bolt" href="/sdk/track-events">
    Mark important user actions with named events and attributes.
  </Card>

  <Card title="Stop Recording" icon="stop" href="/sdk/stop-recording">
    End the current session immediately with `stopRecording()`.
  </Card>

  <Card title="Privacy controls" icon="shield" href="/sdk/privacy">
    Block, mask, or ignore sensitive elements before they are recorded.
  </Card>

  <Card title="Update (deprecated)" icon="pen" href="/sdk/update">
    Legacy entry point — kept for backward compatibility.
  </Card>
</CardGroup>