Data collection

This guide provides practical examples of using the JavaScript SDK to enrich user profiles and sessions with information relevant to your business.

User data

You can persist user-related information in one of the two ways described below depending on whether it is related to the user's profile or their current session.

Profile data

You can enrich user profiles with details collected via forms, surveys, or other means.

These pieces of information, called attributes, are categorized as standard or custom depending on whether it is generic or specific to your organization.

Standard attributes

These are predefined attributes that are common most businesses, such as the user's name, email, and interests.

You can set standard attributes using the user.edit method:

import croct from '@croct/plug';

async function onSignup(name, email) {
  await croct.user.edit()
    .set('name', name)
    .set('email', email)
    .save();

    alert('User profile updated!');
}

onSignup('John Doe', 'john@croct.com');

The user.edit method returns a Patch instance that allows you to chain multiple operations together.

You could alternatively write:

import croct from '@croct/plug';

async function onSignup(name, email) {
  const patch = croct.user.edit();

  patch.set('name', name);
  patch.set('email', email);

  await patch.save();

  alert('User profile updated!');
}

onSignup('John Doe', 'john@croct.com');

When you call save, it saves changes to the user profile and returns a promise that confirms the operation.

You can then access standard attributes in your queries using the user variable:

user's email ends with "@croct.com"

For a complete list of attributes, see User profile reference.

Custom attributes

In addition to the standard attributes, you can add custom attributes to enrich user profiles with information relevant to your business.

For example, let's say you have a SaaS application and you want to ask your users about their area of expertise so you can personalize the onboarding experience.

This is what it would look like:

import croct from '@croct/plug';

async function onExpertiseInformed(area) {
  await croct.user.edit()
    .set('custom.expertise', area)
    .save();

    alert('User profile updated!');
}

onExpertiseInformed('Engineering');

Note that custom attributes are prefixed with custom to avoid conflicts with standard attributes. However, you do not need to include the prefix in your queries:

user's expertise is "Engineering"

Session data

Besides user profiles, you can also store information relevant to the user's current session.

Storing session information can help you keep track of important the user's current session that may not be relevant to their profile. For example, you can store the plan the user selected on the pricing page, or any other information you want to record during the user's visit.

To store session information, use the session.edit method:

import croct from '@croct/plug';

async function onPlanSelected(plan) {
  await croct.session.edit()
    .set('plan', plan)
    .save();

  alert('Session updated!');
}

onPlanSelected('premium');

In the same way as with user profiles, the session.edit method returns a Patch instance that allows you to chain multiple operations together.

import croct from '@croct/plug';

async function onPlanSelected(plan) {
  const patch = croct.session.edit();

  patch.set('plan', plan);

  await patch.save();

  alert('Session updated!');
}

onPlanSelected('premium');

When you call save, it saves changes to the session and returns a promise that confirms the operation. You can then access session information in your queries using the session variable:

session's plan is "premium"

For a complete list of attributes, see Session reference.

User identity

When a user registers or logs in, you may want to associate their profile with an identifier that is meaningful to your business, so that you can recognize them when they return.

You can use any identifier that is meaningful to your business, such as an email address, a username, or a customer ID provided it is unique.

To associate a user profile with an identifier, use the identify method:

croct.identify('0e8f3b9e-8b5a-4f5c-9b8a-0e8f3b9e8b5a');

You usually call identify when the user logs in or registers. In the same way, you can call anonymize when the user logs out:

croct.anonymize();

During the initialization of the SDK, it is important to specify whether the user is anonymous or identified:

croct.plug({
  // ...
  userId: 'john-doe', // or null if the user is anonymous
});

This will prevent the SDK from sending anonymous events before you call identify or anonymize resulting in two sessions — one anonymous and one identified. For more information, see the userId documentation.