Analytics
Identifying Users
How to associate analytics events with specific users
Connect analytics events to specific users with the identify function. This enables user-level analytics, cohort analysis, and personalized experiences.
Basic Usage
"use client"
import { } from "@repo/analytics"
import { } from "react"
export function ({ }) {
const { } = ()
(() => {
if () {
(.id, {
: .email,
: .name,
: .plan
})
}
}, [, ])
return null
}The identify() Function
identify(userId: string, traits?: Record<string, unknown>)| Parameter | Type | Description |
|---|---|---|
userId | string | Unique identifier for the user |
traits | object | Optional user properties |
When to Identify
Call identify() when:
- User signs in - After successful authentication
- User signs up - When a new account is created
- Profile updates - When user properties change
After Sign In
"use client"
import { } from "@startupkit/auth"
import { } from "@repo/analytics"
import { } from "react"
export function () {
const { , } = ()
const { } = ()
(() => {
if ( && ) {
(., {
: .,
: .,
: .
})
}
}, [, , ])
return null
}In Your Root Layout
A common pattern is to identify users in your providers:
"use client"
import type { } from "react"
import { } from "@startupkit/auth"
import { } from "@repo/analytics"
import { } from "@/lib/analytics"
import { } from "@/lib/auth"
interface ProvidersProps {
:
?: { : string; : string; ?: string }
?: <string, boolean | string>
}
export function ({ , , }: ProvidersProps) {
return (
< ={} ={}>
<
={}
={}
={() => {
// This is called when user signs in
// The AnalyticsProvider handles the identify call
}}
>
{}
</>
</>
)
}User Traits
Include properties that help segment your users:
(., {
// Core info
: .,
: .,
// Account info
: "pro",
: "admin",
: .,
// Lifecycle
: .,
: "google",
// Usage
: 5,
: new ().()
})Recommended Traits
| Trait | Description |
|---|---|
email | User's email address |
name | Display name |
plan | Subscription tier |
createdAt | Account creation date |
role | User role (admin, member) |
company | Organization name |
Updating Traits
Call identify() again when user properties change:
function ({ }) {
const { } = ()
const { } = ()
const = async () => {
await ()
// Update analytics with new plan
(.id, {
: ,
: new ().()
})
}
return < ={}>Upgrade to {}</>
}Reset on Logout
Clear the user identity when they sign out:
"use client"
import { } from "@repo/analytics"
export function () {
const { } = ()
const = async () => {
await signOut()
() // Clear analytics identity
}
return < ={}>Sign Out</>
}The reset() function:
- Clears the current user identity
- Generates a new anonymous ID
- Ensures subsequent events aren't associated with the previous user
Anonymous Users
Before identify() is called, users are tracked anonymously. Most analytics providers:
- Generate a random anonymous ID
- Store it in a cookie or local storage
- Merge anonymous history when
identify()is called
This means pre-signup activity is preserved and attributed to the user.
Privacy Considerations
Be mindful of what you include in traits:
// Good - necessary for analytics
(., {
: .,
: .,
: .
})
// Avoid - sensitive data
(., {
: ., // Never
: ., // Never
: ., // Never
: . // Usually unnecessary
})Check your privacy policy and ensure compliance with GDPR, CCPA, etc.
Next Steps
- Feature flags - Target features to specific users
- Tracking events - Learn the tracking API