Understanding Customers

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

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

• Anonymous users are ones who have yet to register or login to your application (ie. 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. Dodgeball 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 = dodgeball.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: null, // (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 Dodgeball Client SDK, represents the device making the request
  // other optional properties omitted
});

Dev 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 Dodgeball 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 the Dodgeball API receives this request, a few things happen:

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

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

Dodgeball 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 = dodgeball.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 Dodgeball Client SDK, represents the device making the request
  // other optional properties omitted
});

Dev 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 Dodgeball 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 the Dodgeball API receives this request, a few things happen:

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

   This screenshot illustrates how this Customer would appear in Dodgeball:

   

   Dodgeball 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.

2. If we do not find a Customer based on the userId, we check for any previously seen Session that the passed sessionId represents.

   • If we don't find one, Dodgeball creates a new identified Customer record which stores the history of this user.
   • If we do find one, we check if the found Customer is identified or anonymous:
     • If the found Customer is anonymous, we convert them to an identified Customer.
     • Otherwise, the found Customer was previously identified using a different userId. In this scenario, Dodgeball will reject the request as a single sessionId is being shared between two identified customers, which indicates abuse or application misconfiguration.

3. Then we run the specified Checkpoint on the aforementioned Customer record.