StartupKitstartupkit
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>)
ParameterTypeDescription
userIdstringUnique identifier for the user
traitsobjectOptional user properties

When to Identify

Call identify() when:

  1. User signs in - After successful authentication
  2. User signs up - When a new account is created
  3. 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:

app/providers.tsx
"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 ().()
})
TraitDescription
emailUser's email address
nameDisplay name
planSubscription tier
createdAtAccount creation date
roleUser role (admin, member)
companyOrganization 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

On this page