Segment

You'll find the official Castle destination documentation here

Getting Started

1. From the Segment web app, click Catalog.
2. Search for "Castle" in the Catalog, select it, and choose which of your sources to connect the destination to.
3. Enter the "Publishable Key" into your Segment Settings UI which you can find in your property in the Castle dashboard.
4. Calls will now be visible in Castle dashboards in real-time.

👍

NOTE: Castle will only ingest Segment client-side events at this point. Server-side events will be dropped and not processed.

NOTE: Castle only supports web integrations via Segment, but we are working on mobile support so please stay tuned.

Page

If you're not familiar with the Segment Specs, take a look to understand what the page method does. An example call would look like:

analytics.page()

page calls will be sent to Castle as $page events.

Track

If you're not familiar with the Segment Specs, take a look to understand what the Track method does. An example call would look like:

analytics.track('Added to Cart')

track calls will be sent to Castle as a $custom events.

Secure Mode

In order to prevent user information from being spoofed by a bad actor, it is highly recommended to send the user information as a signed JWT when Castle.js is used in production.

From your backend code, you need to encode the user as a JWT and sign it using your Castle "API Secret". Then, when Castle receives the JWT, the integrity of the user data will be verified to ensure that the data isn't being tampered with.

Below is an example of how to generate a JWT on your backend using the Ruby language:

jwt_from_backend = JWT.encode({
  id: '97980cfea0067',
  email: '[email protected]'
}, ENV.fetch('CASTLE_API_SECRET'), 'HS256')

You then need to transfer the user_jwt object to your frontend either via a separate API call, or by injecting the code using a templating language:

var userJwt = "<%= jwt_from_backend %>";

// Then use the `userJwt` argument instead of `user` when using any of the tracking methods
Castle.page({userJwt: userJwt});

analytics.identify('97980cfea0067', {
  email: '[email protected]',
}, {
  Castle: {
    userJwt: userJwt
  }
});

When Castle receives a JWT version of the user object, its contents will override the user object sent the standard Segment way.

Next steps

Once you've enabled the Castle Segment integration, we recommend starting to protect your backend actions by following the steps in this integration guide. Once completed, you'll be able to fully leverage Castle's risk scoring and rules engine