Track Companies (B2B)

Tell Ripples which company each user works in, so a B2B product can count active companies, not just active users.

In a B2B product the customer is a company, not a person. Five people from one account using you every day is one healthy customer; five people from five accounts who each logged in once is five at risk. Company tracking lets Ripples tell those apart.

You make one call, group(), saying which company a user works in. Ripples remembers it, and the user’s events count for that company from then on.

ripples.group()

Call it after identify(), wherever you know which company the signed-in user works in:

ripples.identify({ id: user.id, email: user.email })

ripples.group(user.companyId, {
  name: 'Acme Corp',      // shown instead of the id
  plan: 'business',
  seats: 25,
})

Every pageview, track() and identify() from this browser now counts for Acme Corp, across page loads, until you change it. Like identify(), it is safe to call on every page load: it is only sent again when something changes, or once per session.

Parameters

Users in several companies

A consultant or an agency may work in several companies. Call group() again when they switch:

// The user opens another client's workspace
ripples.group('globex_7', { name: 'Globex' })

Events already sent keep the company they were sent with, so the switch never rewrites history. Ripples records the user as a member of both.

ripples.resetGroup()

Stops attaching the company to events, for example when the user leaves it or switches to a personal workspace:

ripples.resetGroup()

ripples.reset(), which you call on logout, clears it too.

Server-side and mobile

From your server, pass the user as well. One call is enough: Ripples keeps who works where, so the user’s later events count for their company without passing anything on each call.

// PHP: at signup, when they join or switch company, when the plan changes
$ripples->group($user->id, $team->id, ['name' => $team->name, 'plan' => 'business']);

$ripples->track('created a report', $user->id);   // counts for $team

# Python
ripples.group(user.id, team.id, name=team.name, plan="business")

ripples.track("created a report", user.id)   # counts for team

Pass null / None as the user to update a company’s traits without touching anyone’s membership, for example from a nightly sync of your accounts.

The iOS SDK works like the web one: Ripples.shared.group(team.id, traits: ["name": team.name]) sticks until you change it or call resetGroup(). See the PHP, Python and iOS pages.

HTTP API

Send a group event to POST /v1/ingest/batch:

{
  "events": [
    {
      "$type": "group",
      "$user_id": "user_123",
      "$company_id": "acme_42",
      "$traits": { "name": "Acme Corp", "plan": "business" }
    }
  ]
}

Any other event may carry $company_id to say which company it happened in, overriding the user’s current one. Only the $-prefixed name is read this way: a plain company_id stays one of your custom properties.

How it works

1. group() creates the company if it is new, merges its traits, and records the user as a member.
2. Every event is filed under a company: the one it names (the web and iOS SDKs name the one you set), otherwise the company its user was most recently active in. Events from anonymous visitors who never called group() belong to none.
3. A company that appears on events gets a record even if you never sent traits, with the dates of its first and latest activity.
4. Payments need no company data of their own: a company’s revenue is worked out through the people who paid, so Stripe and Paddle payments count too.

Tips

• Use stable ids, never names or domains that can change.
• Send name in the traits so the dashboard shows “Acme Corp” rather than acme_42.
• Company traits describe the company. Things about the person, like their role, belong in identify().
• Coming from Segment? This is Segment’s group call: the same idea, one argument shorter.