Identity Claims & Resolution

Gurulu resolves every visitor into a single canonical person by collecting and merging identity claims across sessions, devices, and browsers.

How Identity Resolution Works

  • Gurulu uses a claim-based identity model. Each user interaction generates claims -- pieces of identity evidence.
  • Claims are linked to a CanonicalPerson -- one record representing a single real human.
  • When multiple claims share a common identifier (email, phone, etc.), the associated persons are merged automatically.

Claim Types

Each claim has a type, a confidence score, and a stability rating that determines how long it remains valid.

TypeExampleConfidenceStability
emailuser@example.com1.0 (deterministic)Very stable (~693d half-life)
phone+905321234567 (E.164)1.0 (deterministic)Stable (~347d)
oauth_idgoogle:1182345678901.0 (deterministic)Very stable (~693d half-life)
external_idusr_abc1231.0 (deterministic)Very stable (~693d half-life)
device_ida1b2c3d4 (FNV-1a)0.6 (probabilistic)Medium (~139d)
anonymous_idUUID per browser1.0 (within browser)Short (~69d)

Deterministic vs Probabilistic Merge

  • Deterministic: Same email, phone, or OAuth ID across sessions triggers an instant merge. No scoring needed.
  • Probabilistic: Device overlap, temporal patterns, IP, and user-agent similarity produce a merge suggestion with a score. Merges require a score of 0.55 or higher.

Cross-Browser Merge Example

  1. User visits on Chrome with anonymous_id: aaa, then identifies with email: x@y.com. Gurulu creates Person A.
  2. Same user visits on Safari with anonymous_id: bbb, then identifies with email: x@y.com. Gurulu matches the email claim and merges into Person A.
  3. Result: both sessions now belong to Person A.

Confidence Decay

  • Claims lose confidence over time if the user is not re-seen with that identifier.
  • Re-identification resets confidence back to 1.0.
  • When confidence drops below 0.1 the claim is retired (soft-deleted) and no longer participates in merges.

Consent Integration

Identity processing respects the visitor's consent level:

  • none — No identity processing at all
  • analytics — Only anonymous_id is used, no PII is stored
  • marketing / full — All claim types are processed and merged

SDK identify() API

Call identify() to attach known identity claims to the current visitor. This works across all Gurulu SDKs.

Web (JavaScript)

gurulu.identify('user123', {
  email: 'user@example.com',
  phone: '+905321234567',
  oauth_provider: 'google',
  oauth_id: '118234567890'
});

iOS (Swift)

Gurulu.identify("user123", traits: [
  "email": "user@example.com",
  "phone": "+905321234567",
  "oauth_provider": "google",
  "oauth_id": "118234567890"
])

Android (Kotlin)

Gurulu.identify("user123", mapOf(
  "email" to "user@example.com",
  "phone" to "+905321234567",
  "oauth_provider" to "google",
  "oauth_id" to "118234567890"
))

identify() can be called multiple times. New claims are merged into the existing person. Passing the same user ID is idempotent.

Edit this page