Client-side event tracking
Castle lets you track page views on web and screen views on mobile to get better visibility into where the user spends their time between server-side events.
This chapter assumes that you have completed the Baseline Integration, including adding Castle.js or the mobile SDKs to track client-side activity.
Step 1. Identifying the logged in user
On any page where the user is logged in, call identify
with the User ID of the currently logged in user as the first argument. This method sets the identifier in memory and does not trigger any outbound request. Castle’s tracking pixels are automatically sent on each page load and they will include the set User ID.
Alternative A. Using a templating language
If you are using a templating language where the User ID can be set from the server-side before the page is served up, then you should set the User ID in the <head>
tag.
|
|
Alternative B. Not using a templating language
If you are not using a templating language or are unable to set the User ID inside the <head>
tag, for example if you have single-page application, then you should disable Castle from automatically sending tracking pixels by setting autoTrack
to false
.
Once you have authenticated via an asynchronous API call, you’ll call identify
followed by trackPageview
make sure the User ID is tracked to Castle.
|
|
trackPageview
appends the current URL and page title as metadata on the event. If you prefer to manually set the URL and title, you can pass them as parameters:
|
|
Pageviews
Since we’ve now turned off autoTrack
, you will need to explicitly call trackPageview
in order to track a page view every time the URL changes. It’s recommended that you only track this for full view transitions, and for example not in-page updates to the URL hash.
Logging out
In a similar way to how you logged in the user, you’ll also need to reset the state on logout. Finish it up by tracking a page view to ensure the reset call reaches the Castle API.
|
|
Step 2. Signing the requests
In order to prevent attackers from spoofing user activity, you’ll need to ensure that each page or screen view originates from the currently logged in user by signing each request.
To sign requests, you’ll need to generate a user signature on your server-side and pass it to the JavaScript snippet:
|
|
The signature is a SHA-256 HMAC in hex format. The HMAC shared secret is your API Secret, and the value is the User ID sent to identify
.
Identifying the user after page load
Keep in mind that if the User ID is set after page load, you will also need to disable autoTrack
in order to prevent the tracking pixel from firing prematurely:
|
|
Example
|
|
|
|
|
|
|
|
Step 3. Enabling secure mode in the dashboard
Once the secure signatures are included in your requests, you need to enable Secure Mode in the Castle dashboard. This informs Castle that only requests including the secure signature should be trusted, and all other client-side events will be dropped.
Mobile
If you are using Castle’s mobile SDKs, be sure to configure secure signatures for them as well or their client-side screen views will be dropped.
To enable secure mode, visit the Castle Dashboard and select the environment in the top right for which you want to enable Secure Mode. Then go to Settings > General and toggle on Secure Mode.
Mobile
Identify logged in users
The identify call lets you tie a user to their action and should be called right after the user logged in successfully. The user_id
will be persisted locally so subsequent activity will automatically be tied to that user.
|
|
|
|
|
|
If secure mode is enabled make sure to call
secure
beforeidentify
or any other tracking calls (track
,screen
) since any events not containing theuser_signature
will be discarded.
Tracking screen views
Screen
The screen call lets you record whenever a user sees a screen. It could look something like this:
|
|
|
|
|
|
Securing requests from Mobile SDKs
Secure Mode is available in Castle iOS SDK v1.0.0+ and Android SDK v1.1.0+
Securing requests is optional, but recommended. We strongly encourage all Castle customers to enable Secure Mode to prevent fraudsters from impersonating your users. This is important to make sure fraudsters can’t lock out your users by feeding in bad behavior. Read more about Secure mode in the “Secure Requests” section of the documentation.
Since the secure mode signature is generated on your backend you will need to pass it to your application. A straight forward way of doing that is by including the signature in the authentication response. After receiving the authentication response the application can set the signature by calling the secure
method.
The secure mode signature is a SHA-256 HMAC in hex format where the shared secret is your API Secret, and the value is the User ID being tracked in identify
.
See the example below on how the signature can be generated on your backend.
|
|
|
|
|
|
You will need to set the secure mode signature before calling identify
, otherwise the identify event will be rejected by the API since it won’t include the secure mode signature.
If Secure Mode is enabled on your Castle environment, you will need to pass the user signature to the mobile SDK using the secure method:
|
|
|
|
|
|
Once enabled the user signature will be included in every event. The
user_signature
will be persisted locally. Callingreset
will remove the stored user signature and callingsecure
again will replace the old user signature. Once secure mode is enabled any events not containing theuser_signature
field will be discarded.