Identify Users

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

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
})

Parameters

Properties object

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"

Pass it to your backend on signup or checkout, store it with the user, and hand it to server-side signup() / identify() calls as visitor_id. That is what links a server-created user back to the browsing session that produced them and keeps the traffic source:

// 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, then pass it to
// server-side calls as 'visitor_id' (or let the PHP SDK read the cookie)
$user->ripples_visitor_id = $request->ripples_visitor_id;
$ripples->signup($user->id, ['email' => $user->email, 'visitor_id' => $user->ripples_visitor_id]);

ripples.reset()

Call it when the user logs out. It forgets the signed-in user and starts the browser over as a new anonymous visitor, so whoever uses it next is not linked to them.

async function logout() {
  await fetch('/logout', { method: 'POST' })
  ripples.reset()
}

reset() also clears the company set with ripples.group().

To stop tracking a browser altogether, or to erase a user who deleted their account, see Delete user data (ripples.optOut() and the deletion API).

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.