Skip to main content

Quick Start

What is involved in integrating Dodgeball into your application? This guide will walk you through the steps to get started with Dodgeball.

Integration Process​

Prerequisites​

Get an account​

Before you begin, you'll need to have a Dodgeball account. If you don't already have one, you can contact support at support@dodgeballhq.com

Find Your API Keys​

Once you've logged-in to the Dodgeball Console, you can find your keys in the Developer Center under API Configuration.

Where to Find Keys

Decide what Points of Risk to Protect​

These are typically points in the User Journey where fraud is most likely to occur, like:

  1. Account Creation (fake accounts)
  2. Login (stolen credentials)
  3. Payment (chargeback abuse, stolen credit cards, etc)
  4. Listing Creation (fake listings)

Understanding the User Journey​

As a customer uses your application, Dodgeball builds a profile of their behavior. This profile includes data gathered from SDKs, including any information you send to Dodgeball from your server-side code. This data is managed securely by the Dodgeball platform.

For example, imagine that a user goes through four checkpoints in your application, each of which collects different data points:

SIGN_UP Checkpoint​

  • customer.location
  • customer.firstName
  • customer.lastName
  • customer.primaryEmail
  • customer.primaryPhone

VERIFY Checkpoint​

  • customer.isVerified
  • customer.location (2nd reading)

LOGIN Checkpoint​

  • customer.location (3rd reading)

PAYMENT Checkpoint​

  • customer.location (4th reading)
  • transaction.amount
  • transaction.currency
  • billing.zip

By the time the user reaches the PAYMENT checkpoint, Dodgeball has a rich set of data points about the user's journey through the application. This includes multiple location data points collected at different stages of the user's interaction with the application.

With this accumulated data, Dodgeball can perform advanced analyses. For example, it can calculate whether the user has ever been within a certain distance of the billing zip code for a payment. This type of analysis helps identify potential fraudulent activities by leveraging a rich set of data points collected throughout the user's journey.

Configure Client Side SDK (optional)​

The primary purpose of the Client SDKs is to track user behavior and send it to Dodgeball. This data is used to build a profile of the user's behavior, which is then used to determine if the user is acting suspiciously, or enable features like Session Replay.

Additionally, the Client Side SDKs enable you to react to Checkpoint Verifications in real-time, allowing you to prompt the user for additional information or actions like MFA, IDV, etc. Finally, you can use the results of the Checkpoint Verifications to determine how to proceed with the user's request.

Finally, the Client SDKs simplify integrations with Dodgeball by intelligently loading supported integration scripts which can save you time and effort when working with new anti-fraud services.

Client code example​

info

This example has been simplified to show the general flow of information. See the Client SDKs for proper usage

import { Dodgeball } from "@dodgeball/trust-sdk-client"
const dodgeball = new Dodgeball(dodgeballPublicApiKey)

// Start Tracking
dodgeball.track(currentSessionId, currentUserId);

// Call a Checkpoint
const endpointResponse = await fetch("https://my-server/dodgeball-checkpoint", fetchConfig);
const responseData = await endpointResponse.json();
dodgeball.handleVerification(responseData?.verification, {
  ... // Handle the verification...
});

Information Gathered​

  • Device Fingerprints (automatic)
  • Page Views (automatic)
  • Session Replay (automatic if enabled)
  • Integration Scripts (automatic if enabled)
  • MFA Interactions (automatic if configured in checkpoints)
  • IDV Interactions (automatic if configured in checkpoints)

Configure Server Side SDK (required)​

The primary purpose of the Server SDKs is to securely interact with the Dodgeball API to execute Checkpoints and send Server Events.

Server code example​

info

This example has been simplified to show the general flow of information. See the Server SDKs for proper usage

import { Dodgeball } from "@dodgeball/trust-sdk-server";
const dodgeball = new Dodgeball(process.env.DODGEBALL_PRIVATE_API_KEY);
const checkpointPayload = {
  checkpointName: "MY_CHECKPOINT_NAME",
  event: {
    ip: "some-ip-address",
    data: {
      // Add your data here
    }
  }
}
// Call a checkpoint
const checkpointResponse = await dodgeball.checkpoint(checkpointPayload);
// Handle Checkpoint Response...

Information Sent​

You can send arbitrary data to Dodgeball from your server-side code. This can include information like:

  • Customer Data (emails, phones, etc)
  • Transaction Data (amounts, items, etc)
  • Address Data (billing, shipping, etc)
  • Historical Data (age of account, customer lifetime value, ratings, etc)
  • Custom Data (any other data you want to send)

Create Checkpoints​

Engineers typically create empty checkpoints for each Point of Risk in the User Journey. These checkpoints are then called from the application code by name. Business teams can customize the policies for each checkpoint in the Dodgeball Console later on in the process.

Run Checkpoints via SDKs​

Engineers will call the checkpoints from the application code, passing along the required data. Dodgeball will then run the checkpoint and return a verification that tells the application how to proceed. This verification can be optionally flow back to the client side to react in real-time.

note

If you have any checkpoints with requirements for MFA, IDV, or other client side interactions, you will need to integrate the Dodgeball Client SDKs into your application's frontend code, and handle the interactions as they are returned from the checkpoint.

Business Teams can customize checkpoint policies to react to fraud patterns without needing to write code​

As long as required data is available, there is no need to involve engineering teams to update checkpoint policies. Business teams can update the policies in the Dodgeball Console, and the changes will take effect immediately.

Occasionally, a new integration may require data that has not been gathered yet, in which case the engineering team will need to update the application code to send the required data (for example, some integrations require a phone number to send an SMS: if you have not been gathering phone numbers, you will need to update your application to send phone numbers to Dodgeball).

Test that it's working​

  1. Use your application to make a call to a checkpoint you have created. Then, take a look at your Developer Center > Checkpoint Logs to see the logs for your application. You should see a log for the checkpoint you just called.
  2. Make a change to your checkpoint, hit the "Publish" button in the top right, and then call the checkpoint again. You should see a new log for the checkpoint with the updated version.

That's it! You've successfully integrated Dodgeball into your application. You can now start protecting your application's endpoints and dynamically loading integrations.