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

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.
[custom] optional string | number Any additional properties you want to attach to the user (e.g. plan, company).

Examples

After login

// After successful authentication
async function onLoginSuccess(user) {
  ripples.identify({
    id: user.id,
    email: user.email,
    name: user.name,
    plan: user.plan,
  })
}

React example

function useIdentify(user) {
  useEffect(() => {
    if (user) {
      ripples.identify({
        id: user.id,
        email: user.email,
        name: user.displayName,
      })
    }
  }, [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.

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