Contact identification

Effectively identifying contacts is the bridge between anonymous web traffic and actionable contact data. This guide details how the JavaScript SDK handles contact identity, attribute synchronization, and secure session management.

Anonymous tracking

By default, the SDK tracks every visitor immediately upon load.

• Mechanism: The SDK generates a unique identifier and stores it in the browser's cookies under the key __ca__chat.
• Persistence: This cookie allows the SDK to recognize returning visitors across sessions, maintaining their chat history and page view timeline even if they have not logged in.
• Linking: In the application database, this anonymous identifier corresponds to the userKey attribute.

Tracking User ID

To identify a specific contact (e.g., after they log in to your application), you can pass their credentials to the window.civchat configuration object.

The user_id priority

The user_id field is the primary key for identification. It takes precedence over all other identification methods.

• If user_id is present: The SDK ignores all email-based lookup logic described in the sections below.
• Behavior:
  • If the ID exists in Positive User: Tracking immediately switches to that contact profile.
  • If the ID does not exist: The ID is assigned to the current anonymous session (the contact currently tracked by the __ca__chat cookie).

Best Practice: We highly recommend using the contact's lowercase email or your internal database ID as the user_id to ensure consistency and uniqueness.

Unified Identification

Unified Identification ensures consistent contact tracking across devices by linking sessions using email, user_id, and widget session data. This feature was introduced to make tracking more consistent and avoid creating duplicate email records.

This feature fundamentally alters how the SDK handles email addresses passed via:

1. The initial window.civchat configuration.
2. The UE.pageHit() method.
3. The UE.resetAuth() method.

Note: Unified Identification and "Authorize by email" are advanced features that must be enabled by Positive User support. Contact support to activate them.

The following rules apply only when an EMAIL is passed and NO user_id is provided.

Scenario A: Default (Unified Identification disabled)

By default, the system prioritizes the current session over data integrity.

• Behavior: Passing an email simply overwrites the email of the current contact (cookie owner).
• Risk: It does not check if that email belongs to another contact in the database. This can lead to multiple contact records sharing the same email or data merging incorrectly.

Scenario B: Unified Identification enabled

When enabled, the system attempts to prevent duplicates by checking for existing contacts. The logic splits further based on the Authorize by email setting.

Method/Context	Authorize by Email: ENABLED	Authorize by Email: DISABLED
window.civchat or UE.pageHit()	Match: If email matches cookie's current contact, session continues normally. Mismatch: If a contact with that email exists, tracking switches to that contact. If not, a new contact is created and tracking switches to that contact.	Has Email: If current contact already has an email, a new contact is created and tracking switches to that contact (prevent overwrite). No Email: Provided email is assigned to current contact. (No duplicate check).
UE.resetAuth()	Match: If a contact with the provided email exists, tracking switches to that contact. Mismatch: If not, a new contact is created and tracking switches to that contact.	A new contact is always created with the provided email, regardless of whether it exists in the workspace or is already tracked.

Additional contact data

Once you understand how the contact is identified, you can enrich their profile by passing attributes.

Passing attributes

Attributes are passed at the root level of the window.civchat object. These values overwrite existing data in Positive User if the attribute already exists (except user_id and/or email as explained above).

window.civchat = {
  apiKey: "YOUR_API_KEY",
  // Core Identification
  user_id: "52bdc3be5145e87076c8",
  email: "johndoe@example.com", // Subject to Unified Identification logic if user_id is missing

  // Standard Attributes
  name: "John Doe",
  gender: 2, // 1=Male, 2=Female, 3=Unknown
  status: 2, // 1=Visitor, 2=User
  phone_number: "+44754123434",
  score: 0,

  // Custom Attributes (Root Level)
  plan_type: "premium",
  newsletter_opt_in: true,

  // Company Data (Nested Object)
  company: {
    company_id: "12345", // Required for linking
    name: "Acme Corp",   // Optional if company exists
    revenue: "$239.9 billion"
  }
};

Attribute formatting rules

When sending custom data, strict formatting ensures values are stored correctly in the dashboard.

Attribute Type	Format Example	Notes
Fixed (String)	{ plan: "pro" }	Standard string values.
Fixed (Multi-choice)	{ tags: ["developer", "admin"] }	Pass as an array of strings.
Date	{ signup_date: "2023-08-03" }	Format: YYYY-MM-DD
DateTime	{ last_login: "2017-07-25T14:14:08.612Z" }	Format: ISO 8601.
Boolean	{ is_vip: true }	Stored as boolean.

Company association

The company object allows you to link the current contact to a company entity.

• Linking: If you provide a company_id that exists in Positive User, the contact is linked to that company.
• Creation: If the company_id does not exist, a new company is created with the provided attributes (e.g., name, revenue).

Reset contact identity

Use UE.resetAuth() to clear the current session or switch contacts dynamically (e.g., on Logout or Login actions in Single Page Applications).

This method accepts new contact data as an argument. Note that if you provide an email address, the Unified Identification logic defined above applies immediately.

// Example: Logout and identifying a new user immediately
UE.resetAuth({
    email: "new.user@example.com",
    first_name: "New User"
});

// Example: Simple logout (resets to anonymous)
UE.resetAuth();