Skip to main content

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.

update() is deprecated. Prefer the granular entry points: identify for initial user identification, updateUser for partial user updates, and updateSession for session-level metadata. update() remains available for backward compatibility.
Call update() to attach or refresh user identity and metadata on the current session. Common use cases:
  • Identify a user — when user information becomes available, pass it to associate the session with a real user identity. This unlocks user-level filtering in the dashboard and allows AI queries to reason about specific users.
  • Add session context — attach metadata like the current workflow, experiment variant, or feature flags at any point during a session.
  • Refresh user details — update user metadata (e.g. plan changes, new roles) as it changes during the session.
Call update() as soon as user information is available. The SDK queues the call automatically if initialization hasn’t completed yet.
Use the useMilana() hook:
import { useMilana } from "milana-js/react";

function Dashboard() {
  const { user } = useAuth();
  const { update } = useMilana();

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

  return <>{/* ... */}</>;
}

​
With user metadata

const { update } = useMilana();

update({
  user: {
    userId: "usr_12345",
    email: "jane@example.com",
    name: "Jane",
    metadata: {
      createdAt: "2024-03-15T00:00:00Z",
      plan: "pro",
      orgId: "org_42",
      role: "admin",
    },
  },
});

​
Update session metadata separately

const { update } = useMilana();

update({
  session: {
    metadata: {
      currentFlow: "onboarding",
      experimentVariant: "v2",
    },
  },
});

​
Both at once

const { update } = useMilana();

update({
  user: {
    userId: "usr_12345",
    email: "jane@example.com",
  },
  session: {
    metadata: {
      entryPoint: "email-invite",
    },
  },
});

​
UpdatePayload

update() accepts an UpdatePayload — an object with an optional user field, an optional session field, or both. You must provide at least one.

​
UserUpdate

Information about the user that persists across all of their sessions — things like their plan, team, country, or role. User metadata has upsert semantics across the user’s lifetime: any fields you provide are merged with previously set values, so you only need to send what has changed.
​
userId
string
required
A stable, unique identifier for the user in your system. This is the primary key Milana uses to link sessions to a user. Use your database user ID or a similar permanent identifier — do not use an email address as the primary ID.
​
email
string
The user’s email address. Used to connect user identity across your systems (e.g. support tools, CRM, data warehouse) and displayed in the dashboard.
​
name
string
The user’s display name.
​
metadata
object
Arbitrary key-value pairs to attach to the user. Keys are strings, values can be string, number, boolean, null, or nested objects/arrays of the same types. e.g. plan, team, country, role, accountType.We strongly recommend including a createdAt key (ISO 8601 timestamp, e.g. "2024-03-15T00:00:00Z") so Milana can distinguish new users from returning users and support cohort analysis.

​
SessionUpdate

Context that is specific to the current session — things like feature flags, traffic origin, experiment variant, or the current workflow. Session metadata has upsert semantics within the session: any fields you provide are merged with previously set values, so you can enrich the session progressively as context becomes available.
​
metadata
object
Arbitrary key-value pairs to attach to the current session. Keys are strings, values can be string, number, boolean, null, or nested objects/arrays of the same types. e.g. origin (e.g. "email-notification", "marketing-site"), featureFlags, experimentVariant, currentFlow.

​
Return value

​
success
boolean
true if the update was applied to the session. false if the session was not active, the network request failed, or the session was not sampled.