Identity Strategy

Identity is the part of an integration that's easy to get subtly wrong and expensive to fix later. This page explains the model — what each identifier means and how Binoban decides two events belong to the same person — so that one person maps to one profile across web, mobile, and server. It's understanding-oriented; for the exact methods, see the Web SDK reference → Identity.

Resolution is a configured strategy, not a fixed algorithm

Binoban doesn't apply one hardcoded rule ("match on userId, fall back to anonymousId") the same way to every workspace. Instead, each workspace has an identity resolution strategy: an ordered list of identifiers that Binoban trusts as evidence two events belong to the same person, built from whatever your sources actually send. It applies across every source in your workspace, which is why a userId set on web and the same userId set on mobile resolve to one profile (see Web ↔ mobile alignment).

That strategy is built from three kinds of identifiers:

Kind	Examples	Where it comes from
System identifiers	userId, anonymousId, phone, email	Reserved fields every SDK/API call carries or can carry as a trait
Device identifiers	device ID, advertising ID, push token	context.device.*, collected by the SDKs (collectDeviceId, device-token registration)
Custom trait identifiers	any trait you send — a loyalty number, an internal account ID, whatever your business already uses as a key	traits (Identify) or context.traits (Track/Page)

The first two kinds are the identifiers Binoban already understands out of the box. The third — custom traits — means the strategy isn't limited to the fields above: if your business already has a stable identifier (a loyalty card number, an internal CRM key) that isn't userId, it can also be registered as a matching key for your workspace. Talk to your Binoban team to add phone, email, or a custom trait to your workspace's strategy — none of them are wired into matching by default (see What's on by default).

sourceIdentifier is not part of this list — it doesn't identify a person, it identifies where an event came from, and it's what scopes which workspace's strategy applies. The mental model: anonymousId is "this browser/app instance," userId is "this person," a device identifier is "this hardware," and sourceIdentifier is "this origin of data."

How Binoban decides "same person"

When an event arrives, Binoban looks at every identifier the event carries and checks each one, from highest to lowest priority, against identifiers it's already seen:

1. Existing links win. If any identifier on the event — even a low-priority one — is already linked to a profile, that profile is used. Binoban never silently starts a second profile for someone it can already place.
2. Otherwise, the highest-priority identifier present decides. The first identifier in your workspace's priority order that shows up on the event becomes the profile. If nothing about this person has been seen before, this is what starts a brand-new profile.
3. Lower-priority identifiers get linked to that profile too, so the next event carrying only one of them (say, just a deviceId, with no userId yet) can still resolve back to the right person.

If two identifiers turn out to belong to the same person — most commonly, an anonymousId that already has history signs in with a userId that also has its own history — Binoban merges the two profiles: the older profile's events are re-attached to the surviving one, and the surviving profile gets a system-generated $system_merge event marking that it happened. You don't have to do anything to trigger this; it falls out of the priority order above.

Older, low-priority signals also age out: Binoban only retains a limited number of recent values (over a rolling window) for lower-priority identifiers like rotating anonymous IDs or ad IDs, so a device ID from a year ago won't resurrect a stale match. Ask your Binoban team what retention is configured for your workspace if this matters for your integration.

What's on by default

Out of the box, a new workspace's strategy resolves identity from userId first, then anonymousId, then the device identifiers the SDKs collect automatically. Phone, email, and custom-trait matching are not enabled by default — sending traits.email on every call doesn't merge profiles across devices unless email has been explicitly added to your workspace's strategy. If your integration depends on matching people by phone or email (for example, because you can't rely on a shared userId between two surfaces), ask your Binoban team to add it.

The one structural rule that always holds regardless of configuration: your top-priority identifier (userId, in the default setup) can only ever be linked to one profile at a time. That's what guarantees identify(userId, ...) always lands on the same person, no matter how many devices or sessions sent events in between.

Anonymous, then known

Binoban starts tracking before sign-in. On first contact the SDK mints an anonymousId and persists it (in the browser as a first-party cookie / localStorage entry — see the Web SDK reference → Identity for the exact key; on mobile in local storage). Every track/page call carries it.

When the person signs in, you call identify(userId, traits). Binoban links the prior anonymous activity to that userId, so the pre-login browsing and the post-login actions become one continuous profile. This is the single most important call to get right.

When to call identify

• Call it when identity becomes known or changes — after sign-up, after login, and whenever durable traits change.
• You don't need to call it for anonymous users. The anonymousId already covers them; calling identify with no userId only updates traits.
• Don't call it on every page load with stale data. Re-identifying the same user is fine, but avoid overwriting good traits with empty ones.

Logout and reset

On logout, call reset. This clears the current userId and traits and starts a new anonymousId, so the next person on the same device isn't merged into the previous user's profile.

Binoban.reset();   // Web

binoban.reset()   // Native

Skipping reset on a shared device is a common cause of two people collapsing into one profile.

Multi-device behavior

A person on a phone and a laptop has two anonymousIds but one userId. As long as you identify with the same userId on each device, Binoban resolves them to a single profile — because, per the rule above, that top-priority identifier can only ever point at one profile. The userId is the thread that ties devices together — which is why it must be stable and come from your own system of record, not a per-device value.

Webview behavior

A native app that renders web content in a webview has two SDKs in play — the Native SDK in the app and the Web SDK in the page — each with its own anonymousId. To keep them from splitting into two profiles, pass identity into the webview so both sides share the same anonymousId/userId. The Web SDK's advanced options cover the webview handoff.

Web ↔ mobile alignment

The same rules unify web and mobile: use one userId namespace across every source in your workspace. If your website and your app both identify a customer as user_123, their web and mobile activity merge automatically — resolution runs at the workspace level, not per source. If they use different schemes (say, an email on web and an internal ID on mobile), you'll get duplicates unless email matching has also been enabled for your workspace.

Avoiding duplicate users

Duplicates almost always trace back to one of these:

• Inconsistent userIds — different ID schemes per platform. Fix: one namespace everywhere.
• Identifying too late — letting a user act while still anonymous on a device where they're actually known. Fix: identify as soon as identity is known.
• Not calling reset on logout — merging the next user into the last one.
• Webview split — the app and its webview tracking as separate anonymous users. Fix: share identity into the webview.
• Assuming phone/email matching is on — if it isn't part of your workspace's configured strategy, sending the same email from two surfaces with no shared userId/anonymousId still produces two profiles. Fix: ask Binoban to add it, or bridge devices with a shared userId instead.

Get the userId discipline right and the rest of the model takes care of itself.

Where to go next

• Web SDK reference → Identity — the exact methods and keys.
• Native SDK — Android · iOS — deviceId and mobile setup.
• Identify spec — the identify call's full shape.