User Identification

By default, Ovyxa tracks anonymous visitor sessions. With user identification, you can attach a name, email, or customer ID to a visitor — turning anonymous data points into recognizable profiles in your dashboard.

Overview

User identification is available on Starter plans and above. It works in both cookie and cookieless modes, though cookie mode provides more reliable cross-session matching.

When you identify a visitor, Ovyxa:

1. Links their current session to the identity you provide.
2. Merges past anonymous sessions (cookie mode only) into their profile.
3. Shows the visitor's name and metadata in the People section.

---

The identify() API

Call ovyxa("identify", ...) after the tracking script has loaded. Typically you call this on login, signup, or when a user's identity becomes known:

<script>
  // Basic identification
  ovyxa('identify', {
    id: 'usr_12345',
    name: 'Alice Chen',
    email: 'alice@example.com'
  });
</script>

Parameters

Field	Type	Required	Description
id	string	Yes	A unique, stable identifier for this user (your internal user ID)
name	string	No	Display name shown in the People dashboard
email	string	No	Email address — used for Gravatar avatar
properties	object	No	Custom key-value pairs (plan, company, role, etc.)

Full example with custom properties

<script>
  ovyxa('identify', {
    id: 'usr_12345',
    name: 'Alice Chen',
    email: 'alice@example.com',
    properties: {
      plan: 'growth',
      company: 'Acme Inc',
      role: 'founder',
      mrr: 49
    }
  });
</script>

Server-side identification

You can also identify visitors via the API:

curl -X POST https://api.ovyxa.com/api/v1/stats/identify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "example.com",
    "visitor_id": "abc-123-def",
    "id": "usr_12345",
    "name": "Alice Chen",
    "email": "alice@example.com",
    "properties": { "plan": "growth" }
  }'

The visitor_id is the anonymous Ovyxa visitor ID (from the ovyxa_vid cookie or localStorage).

---

Visitor Profiles

Once identified, visitors appear in the People section of your dashboard (Settings → People). Each profile shows:

• Name and avatar (Gravatar via email hash)
• First seen / Last seen timestamps
• Total sessions, pageviews, and events
• Revenue attributed to this visitor
• Full event timeline — every pageview, custom event, and payment in chronological order
• Custom properties you passed during identification

Searching visitors

Use the search bar in the People section to find visitors by name, email, or custom ID. You can also filter by custom properties (e.g., plan:growth).

---

Named Visitors in the Dashboard

Identified visitors surface in several places:

• Realtime view — active visitors show names instead of anonymous IDs.
• Visitor Journey — click any visitor row to see their full timeline.
• Revenue attribution — payment records link to the named profile.
• Goal conversions — see which identified users completed goals.

---

Resetting Identity

If a user logs out and another person uses the same browser, call:

<script>
  ovyxa('identify', { reset: true });
</script>

This clears the current identity and generates a new anonymous visitor ID.

---

Privacy Considerations

User identification stores personally identifiable information (PII). Keep these points in mind:

• Consent: identification implies the user has an account with you. Ensure your privacy policy covers analytics with PII.
• Cookieless mode: identification still works but cross-session merging is less reliable since visitor IDs are localStorage-based.
• Data deletion: you can delete a visitor's profile and all associated data via Settings → People → Delete, or via the API. This is irreversible.
• GDPR Article 17: Ovyxa supports right-to-erasure requests. Deleting a profile removes the identity link; underlying anonymous event data is retained in aggregate.
• No third-party sharing: identified visitor data is never shared with third parties or used for advertising.
• Data retention: visitor profiles follow your plan's data retention period. After expiry, PII is automatically purged.

caution

Never pass sensitive data (passwords, payment card numbers, health data) in identification properties. Only include information you would be comfortable displaying in your dashboard.