Understanding customers

What is a customer

In Composer, a Customer represents a real-world user within your application.

There are two kinds of users represented by the Customer entity: anonymous and identified.

Anonymous users are ones who have yet to register or log in to your application (i.e. your application may not have a unique identifier representing them in your database).
Identified users are ones who have created an account with your system or have logged in to an account.

Most users will start as anonymous and transition to identified as they use your application. Composer combines this activity into a single Customer view to help identify suspicious behavior.

Anonymous customers

An anonymous Customer is created whenever a checkpoint is called with a previously unobserved session and associated user account.

Here's an example:

const checkpointResponse = await composer.checkpoint({
  checkpointName: 'MY_CHECKPOINT',
  event: {
    ip: '127.0.0.1',
    data: { /* ... */ }
  },
  sessionId: 'session-1', // stays the same after the user authenticates
  userId: null, // set once the user is known
  sourceToken: 'sourceToken-1' // from the Client SDK
})

Developer notes

While you can submit any string as the sessionId and userId, in practice, you should use a UUID for your sessionId and either a username, email address, or UUID for your userId (whichever represents the primary identifier for a user within your application).

If you do not provide a valid sourceToken (obtained from a Composer Client SDK) when calling a checkpoint, device history will not be available.

The above snippet calls a checkpoint called MY_CHECKPOINT with a sessionId of session-1 and no userId. When Composer receives this request, a few things happen:

We check for any previously seen Session that the passed sessionId represents.
1. If we don't find one, Composer creates a new Customer record which stores the history of this user.
2. If we do find one, Composer links this activity to the found Customer record.
Then we run the specified checkpoint on the aforementioned Customer record.

This screenshot illustrates how an anonymous Customer would appear in Composer:

Composer automatically generates a unique identifier prefixed with CUS- to represent all Customers. This helps to quickly reference a Customer regardless of whether they are anonymous or identified.

Identified customers

A Customer becomes identified whenever a userId is passed to a checkpoint.

Here's an example:

const checkpointResponse = composer.checkpoint({
  checkpointName: "MY_CHECKPOINT",
  event: {
    ip: "127.0.0.1", // The IP address of the device where the request originated
    data: {
      // Arbitrary data to send in to the checkpoint...
    },
  },
  sessionId: "session-1", // A unique identifier representing this user's activity. This sessionId should remain the same after the user authenticates
  userId: "user-1", // (Optional) A unique identifier representing the account this user is attempting to or has already logged-in to
  sourceToken: "sourceToken-1", // (Optional) Obtained from the Composer Client SDK, represents the device making the request
  // other optional properties omitted
});

Developer notes

If you do not provide a valid sourceToken (obtained from a Composer Client SDK) when calling a checkpoint, device history will not be available.

The above snippet calls a checkpoint called MY_CHECKPOINT with a sessionId of session-1 and a userId of user-1. When Composer receives this request, a few things happen:

We check for any previously seen Customer that the passed userId represents.

This screenshot illustrates how this Customer would appear in Composer:

Composer automatically generates a unique identifier prefixed with CUS- to represent all Customers. This helps to quickly reference a Customer regardless of whether they are anonymous or identified. Below that, we include the External ID, which represents the unique identifier your application provided to identify this Customer.

If we do not find a Customer based on the userId, we check for any previously seen Session that the passed sessionId represents.
1. If we don't find one, Composer creates a new identified Customer record which stores the history of this user.
2. If we do find one, we check if the found Customer is identified or anonymous.
3. If the found Customer is anonymous, we convert them to an identified Customer.
4. Otherwise, the found Customer was previously identified using a different userId. In this scenario, Composer will reject the request as a single sessionId is being shared between two identified customers, which indicates abuse or application misconfiguration.
Then we run the specified checkpoint on the aforementioned Customer record.