Skip to main content

How Dodgeball Works

System Components​

There are three components to Dodgeball:

  1. The Dodgeball Server SDKs: These are responsible for interacting with the Dodgeball API and offer helpers to standardize and simplify whether or not to allow a request to proceed. They allow you to execute Checkpoints.
  2. The Dodgeball Client SDKs: These are responsible for device identification, behavior tracking, executing tracking services from configured integrations, and displaying user friction required by a Dodgeball Checkpoint (e.g. MFA, IDV, KYC).
  3. The Dodgeball Console: This is where you configure which integrations should run, whether a request should be allowed to proceed (via Checkpoints), and if a human needs to be alerted to investigate suspected fraud.

Understanding the Flow​

Tracking Users​

Tracking usage builds a profile of site users in the Dodgeball Customer Data Platform. This data is accessible for review in the Customer profile in the Dodgeball Console. This data may also be used in a Dodgeball Checkpoint to inform a decision.

The Tracking function also automatically enables data collection for any configured 3rd party integrations that require this information.

It is possible to execute Dodgeball Checkpoints without the benefit of this usage data. Tracking users is optional if none of the above use cases are required.

Tracking is performed through the Dodgeball Client SDKs.

Tracking Flow

  1. Dodgeball should be configured as soon as your application loads.
  2. When you construct Dodgeball using your public API key, it finds the active list of integrations that need to run on the frontend and loads them.
  3. When you have a session, and optionally a logged-in user, pass them to Dodgeball. This will configure all loaded integrations and start tracking page views.

Protecting Your Application​

Protecting your application happens by executing a Dodgeball Checkpoint. These may be executed through any of the Dodgeball Server SDKs. To use client-side progressive friction -- such as MFA, Identity Verification, Shared Secret checks, and 3DS verification — a Dodgeball Client SDK must also be implemented.

Checkpoint Flow

  1. Dodgeball secures any risky action. A risky action is one that may open your application up to fraud (e.g. Registration, Login, Payments, Posting a Listing).

  2. To identify who is attempting the risky action, Dodgeball fingerprints the device and returns a token representing the source.

  3. When you make a request to your API, send along the source token.

  4. Before taking any action, verify that the request should be allowed to proceed by calling a Dodgeball checkpoint. Checkpoints can be called whatever you want (e.g. BOOK_A_RIDE, MAKE_RESERVATION, POST_LISTING) and can be updated to protect your application without having to touch code.

  5. The checkpoint will run and create a new verification, which tells your application how to proceed:

    a) If allowed, you should complete the request and return a successful response.

    b) If denied, you should reject the request and return the verification that was performed — it'll have contain a denial message to display to the user.

    c) If pending, no determination on how to proceed has been reached yet. This happens when the checkpoint needs to gather additional information, such as an MFA code or picture of a government ID. You should take no action and return the verification that was performed.

  6. When you get a response from your API, use Dodgeball to parse the verification returned, which determines the correct callback to invoke:

    a) When the request is allowed, you should inform the user, either by progressing to the next screen in a flow or displaying a success message.

    b) When the request is denied, you should display a denial message to the user.

    c) If additional information was gathered from the user and they are now allowed to proceed, you should retry the request to your API, being sure to pass along the ID of the verification that was performed.

  7. If a verification ID is sent along with a request to your API, send it to the Dodgeball checkpoint. Dodgeball will check if the verification is complete and allowed to proceed. If so, it will be marked as used (to prevent replay attacks) and the request will be allowed to proceed.