Updating contact attributes

The client.update method is designed for data enrichment. It sends a background request to update the current contact's profile data without interrupting their session history.

Method signature

userengage("client.update", attributesObject);

• attributesObject (Object): A key-value pair of the attributes you wish to update.

Capabilities & scope

Permitted attributes

Not all system attributes can be modified using this method. For example, you cannot manually overwrite certain technical fields like browser_language or ip_address as these are detected automatically.

For a complete list of standard attributes and their mutability, please refer to this article.

Tracking state preservation

The most important characteristic of client.update is that it does not switch the tracking session.

• Use for: Changing a contact's name, email, or custom settings (e.g., newsletter_opt_in: true) while they stay on the same page.

• Do not use for: Logging in a contact or switching from "Anonymous" to "Identified".

Limitations

The user_id limitation

You cannot use client.update to switch between contacts (e.g., during a Login action). Attempting to update the user_id attribute via this method behaves differently than UE.pageHit().

If you include user_id in the update object, one of two things will happen:

1. Overwrite (Success): If the user_id you provide does not exist in your Positive User workspace, the system will assign it to the current contact, overwriting their previous ID.

2. Conflict (Error): If the user_id you provide already belongs to another contact, the request will fail. The system will not switch tracking to that other contact; it will simply reject the update to prevent data corruption.

Requirement: To track logged-in contacts across devices or switch sessions, you must use UE.pageHit(), UE.resetAuth(), or the initial window.civchat configuration.

Not for Form Submissions

Because client.update does not switch the tracking session, it is not recommended for tracking form submissions (like "Sign Up" or "Login" forms).

Read More: For proper form handling, please refer to the Form submissions guide.

Implementation

Basic usage

userengage("client.update", {
    // Standard Attributes
    first_name: "John",
    last_name: "Doe",
    
    // Custom Attributes
    is_dark_mode: true,
    preferences_updated: "2023-10-27"
});

Verification

To verify the update was successful, check the Network activity in your browser's Developer Tools.

1. Success Response: Look for a request to the /api/update-attribute/ endpoint.
   • Status: 200 OK indicates the update was accepted.
   • Payload: The response will confirm the accepted attributes.
2. ID Conflict Error: If you attempt to assign a user_id that is already taken, the API will return a 400-level error with a specific message.

   {
       "errors": {
           "user_id": [
               "Istnieje już użytkownik z tą wartością pola ID użytkownika."
           ]
       }
   }

   (Translation: "A user with this User ID value already exists.")