Identify Users

Associate anonymous visitors with authenticated users using ripples.identify().

Note: Identifying users stores the user ID in localStorage. Once identified, all subsequent events (including pageviews) will include the user ID until the storage is cleared.

ripples.identify()

Call this method after a user logs in or signs up:

ripples.identify({
  id: "user_123",                  // required
  email: "[email protected]",          // optional
  name: "Jane Doe",                // optional
  avatar_url: "https://...",       // optional
  signed_up_at: "2026-01-15T...",  // optional — ISO 8601 date string
  plan: "pro",                     // optional
})

Call on every authenticated page load — not just on login. It's safe to call multiple times and ensures the user stays linked across page navigations and sessions.

Parameters

Parameter Type Description
props required object User properties object. Must include id.

Properties object

Key Type Description
id required string Your internal user ID. This links anonymous sessions to the user.
email optional string User's email address. Shown in the visitor profile.
name optional string Display name. Shown in the visitor profile instead of the anonymous name.
avatar_url optional string URL to the user's avatar image. Also accepts avatar as an alias. Shown in the visitor profile.
signed_up_at optional string ISO 8601 date string of when the user signed up. Enables cohort-based retention and activation analysis. If omitted, Ripples sets it to the time of the first identify() call.
plan optional string The user's current plan (e.g. "free", "pro"). Stored on the visitor profile and used for plan-based segmentation.
[custom] optional string | number Any additional properties you want to attach to the user (e.g. company, role).

Examples

After login

// After successful authentication
async function onLoginSuccess(user) {
  ripples.identify({
    id: user.id,
    email: user.email,
    name: user.name,
    avatar_url: user.profile_avatar_url,
    signed_up_at: user.created_at, // ISO 8601
    plan: user.plan,
  })
}

React example

function useIdentify(user) {
  useEffect(() => {
    if (user) {
      ripples.identify({
        id: user.id,
        email: user.email,
        name: user.displayName,
        avatar_url: user.avatarUrl,
        signed_up_at: user.createdAt,
      })
    }
  }, [user])
}

Alternative syntax

You can also pass the user ID as a string with properties as a second argument:

// Object style (recommended)
ripples.identify({ id: "user_123", name: "Jane" })

// Queue style
ripples("identify", { id: "user_123", name: "Jane" })

// String ID style (legacy)
ripples("identify", "user_123", { name: "Jane" })

ripples.getVisitorId()

Returns the current visitor's unique ID. Use this to link client-side activity with your backend — for example, to send server-to-server events.

const visitorId = ripples.getVisitorId()
// "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

A common pattern is to pass the visitor ID to your backend on signup or checkout, so you can attribute server-side events (like Stripe payments) back to the visitor:

// Send visitor ID with your API call
await fetch('/api/signup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: email,
    plan: plan,
    ripples_visitor_id: ripples.getVisitorId(),
  }),
})

// Store the visitor ID alongside the user record
// Later, use it to send server-side events via the API
$user->ripples_visitor_id = $request->ripples_visitor_id;

Visitor ID persistence: The visitor ID is stored in a cross-subdomain cookie (_rpl_vid) with a 2-year expiry, and also in localStorage as a fallback. This means app.yoursite.com and www.yoursite.com share the same visitor ID.

How it works

  1. When you call ripples.identify(), the user ID is saved to localStorage under the key _rpl_uid, and the avatar URL under _rpl_uav.
  2. An identify event is sent to the collection endpoint with the user properties.
  3. All future events (pageviews, tracks) will include this user ID automatically.
  4. The visitor profile in your dashboard will show the user's name, email, and avatar instead of the anonymous identifier.
  5. The first identify() call also sets signed_up_at on the profile (if not already set or if you pass an earlier date), which powers cohort and activation analytics.

Cross-device tracking: Once a user is identified on one device, their activity will be linked across all devices where they log in.