Background

This quickstart guide will help you get started with Castle by populating your environment with test data, allowing you to explore the basic concepts of users, devices, risk scores, and behavioral signals. You'll be using the developer console in your web browser to make a handful of calls to Castle by leveraging the client-side integration.

Once you've completed this guide, you should be ready to implement Castle into your production environment by following the complete integration guide.

Setting up your account

Before you start, you need a Castle user account with admin access in order to view and copy the API keys required to send data to Castle.

👍

Get your free API keys

If you haven't already, sign up for a free 30-day trial to get your API keys. If you need more than 30 days to evaluate Castle, then don't hesitate to reach out to [email protected]

The first phase of the integration requires you to have access to the frontend source code of your application, as well as some knowledge on how to inject server-side template variables to populate a user object.

Environments

A new Castle organization is created with two default environments, one for Sandbox and one for Production. You should always use the Sandbox environment while developing in order to not taint your production data, and only once you've completed with the integration and the data has been verified, you switch to the production environment by replacing the integration keys described below.

Your data will appear in the Sandbox in real-time, with the limitation of having tighter rate limits and lower data retention. The Production environment is optimized for throughput, but you might have to wait up to 60 seconds to see your data.

Integration keys

To complete the integration, you need both the Publishable Key and the API Secret. You'll find both in the Dashboard Settings.

• Publishable Key – this is what'll you'll be using for the quickstart guide. It's a non-secret string starting with pk_, used to identify your application on the client-side side of the integration.

• API Secret – a 32 character long string comprised of random numbers and letters, which you'll be using for your server-side integration.

Step 1. Include the Browser SDK

For this getting started guide, we'll be using the CDN version since it's the fastest way to get to know the product, however, once deployed to production, it would inevitably be blocked by users using browser privacy extensions and adblockers, which is why you should instead use the full client-side guide once you're completed your initial evaluation.

📘

For security reasons, the CDN version doesn't support the createRequestToken method required for a server-side integration of Castle.

Navigate to a page on your site and copy the following code:

var tag = document.createElement("script");
tag.setAttribute("src","https://d2t77mnxyo7adj.cloudfront.net/v3/castle.js");
document.getElementsByTagName("head")[0].appendChild(tag);

Paste and run the code in your browser's developer console:

The rest of the examples in this guide will be run from the same console environment.

Step 2. Initialize the SDK

Update the example below to use your own Publishable Key:

var castle = Castle.configure({ pk: '<YOUR_PUBLISHABLE_KEY>' });

Step 2. Build the user object

var user = {
  id: 'ca1242f498', // required
  email: '[email protected]',
  phone: '+1415232183',
  name: 'Lea Brown',
  registered_at: '2012-12-02T00:30:08.276Z',
  traits: {
    plan: 'premium'
  }
}

This identifies Lea by her unique User ID (in this case, ca1242f498, which is what you know her by in your database). The User ID is the only required field, but it's recommended that you fill out as many fields so that Castle can look for suspicious patters, such as disposable email addresses and phone numbers inconsistent with the current IP address.

When you actually put that code on your site, you need to replace those hard-coded trait values with the variables that represent the details of the currently logged-in user.

Step 3. Send a page view

The page method is how you tell Castle who the current user is and what page it's currently viewing. It includes a unique User ID, email address, as well as any optional traits you know about them. In production, you would call this method at every page load.

Copy and paste the following code into your console:

castle.page({ user: user });

Head over to the Events tab in the Castle Dashboard to see you first event appear in the table and in the chart. You can click on the row it to review details such as device and location information, and since the email we used in the example was from a disposable email domain, the event got flagged with the signal "Disposable Email Domain". Any details and signals can be used to build sophisticated queries that can later be used create Policies to block activity in real-time on the server-side.

By clicking the user email, you'll also be able to review the user's profile. Once you start sending more events to Castle, this view will give you a complete view of the user's journey throughout your app.

Step 4. Send a form submission

Passing information about the forms a user submits inside of your application is a quick way to get a more complete picture of important actions without having you go through a heavy lift server-side integration.

The name parameter is the human-readable name of the form, for instance "Payment", "Change password", or "Add credit card". The values object can be any list of custom data.

castle.form({
  user: user,
  name: 'Update Profile',
  values: {
    first_name: 'John',
    age: '36'
  }
});

Step 5. Send a custom event

Custom events are used to complete the picture of the user journey by tracking things such as "Downloaded Transactions" , "Disabled two-factor", or "Liked post".

castle.custom({
  user: user,
  name: 'Added To Cart',
  properties: {
    product: 'iPhone 13 Pro',
    price: '1099.99'
  }
});

Let's integrate!

The guide above was a first dry-run of what's to come. Now head over to complete integration guide to learn how to integrate Castle into your app and see real user profiles and events appear up in the dashboard.