Client-side Javascript Integration
Bot Defender will send an asynchronous event to the client-side environment, containing the result of the bot-or-not decision, as well as any other configured enrichment data.
To share this Bot Defender data with Google Analytics, a new function must be added to the client-side code that receives each of these events, and then passes it along to Google Analytics as an event with custom dimensions.
While the logic and information flow is the same, the syntax for sending custom events is different for Google Analytics and Google Tag Manager.
Universal Analytics (UA)
Sending Bot Decision Data
The below example code receives a score event from Bot Defender, and then sends it to Google Analytics as an event.
In your implementation, make sure to use the correct index for dimension1 that is assigned to the custom dimension you have created.
Google Tag Manager
window.<APPID>_asyncInit = function(px) {
px.Events.on('score', function(score) {
try {
// use any string you like for 'BD-category', 'BD-action', and 'BD-label' -- these are for sorting events within Google Analytics
// please ensure the index of 'dimension1' matches the index configured within the GA portal (e.g. 'dimension2', 'dimension3', etc.)
gtag('event', 'BD-action', {
'event_category': 'BD-category',
'event_label': 'BD-label',
'dimension1': score
});
} catch (err) {
// remove the below line if you do not want to log errors in productions
console.log("error: " + err);
}
});
};
Google Analytics (analytics.js)
window.<APPID>_asyncInit = function(px) {
px.Events.on('score', function(score) {
try {
// use any string you like for 'BD-category', 'BD-action', and 'BD-label' -- these are for sorting events within Google Analytics
// please ensure the index of 'dimension1' matches the index configured within the GA portal (e.g. 'dimension2', 'dimension3', etc.)
ga('send', 'event',
'BD-category',
'BD-action',
'BD-label',
{'dimension1': score}
);
} catch (err) {
// remove below line if you do not want to log errors in productions
console.log("error: " + err);
}
});
};
Checking your Integration
TO check your integration is working correctly:
- Navigate to Realtime > Events.
- Check that Google Analytics is receiving event data from your application related to the Bot Defender integration.
- Navigate to your application.
- Make sure the Real Time Report in Google Analytics shows a new event every time you load the page with the new event code.
The event should have the same Event Category and Event Action that you configured in the client-side JavaScript.
Sending Enrichment Data (Optional)
See Data Enrichment for more information on the values available to send.
The below example code receives both a score event and an enrich event from Bot Defender. Separate functions are defined to receive these events. The code then send the events to Google Analytics.
Make sure in your implementation the dimension index for each field matches the index configured in Google Analytics.
The below examples use f_id as an example data point from data enrichment.
Google Tag Manager
window.<APPID>_asyncInit = function(px) {
px.Events.on('score', function(score) {
try {
// use any string you like for 'BD-category', 'BD-action', and 'BD-label' -- these are for sorting events within Google Analytics
// please ensure the index of 'dimension1' matches the index configured within the GA portal (e.g. 'dimension2', 'dimension3', etc.)
gtag('event', 'BD-action-score', {
'event_category': 'BD-category',
'event_label': 'BD-label',
'dimension1': score
});
} catch (err) {
// remove below line if you do not want to log errors in production
console.log("error: " + err);
}
});
px.Events.on('enrich', function (value) {
// ...
const base64Data = value.split(":")[1]; // split value to get the base64 encoded data
const dataStr = atob(base64Data); // base64 decode the enrichment data
const data = JSON.parse(dataStr); // get the data as JSON
try {
gtag('event', 'BD-action-enrich', {
'event_category': 'BD-category',
'event_label': 'BD-label',
'dimension2': data['f_id']
});
} catch (err) {
// remove the below line if you do not want to log errors in production
console.log("error: " + err);
}
});
};
Google Analytics (analytics.js)
window.APPID_asyncInit = function(px) {
px.Events.on('score', function(score) {
try {
// use any string you like for 'BD-category', 'BD-action', and 'BD-label' -- these are for sorting events within Google Analytics
// please ensure the index of 'dimension1' matches the index configured within the GA portal (e.g. 'dimension2', 'dimension3', etc.)
ga('send', 'event',
'BD-category',
'BD-action',
'BD-label',
{'dimension1': score}
});
} catch (err) {
// remove below line if you do not want to log errors in production
console.log("error: " + err);
}
});
px.Events.on('enrich', function (value) {
// ...
const base64Data = value.split(":")[1]; // split value to get the base64 encoded data
const dataStr = atob(base64Data); // base64 decode the enrichment data
const data = JSON.parse(dataStr); // get the data as JSON
try {
ga('send', 'event',
'BD-category',
'BD-action',
'BD-label',
{'dimension2': data['f_id']}
});
} catch (err) {
// remove the below line if you do not want to log errors in production
console.log("error: " + err);
}
});
};
Deploying Google Analytics on the Block Page
Google Analytics (either analytics.js or Google Tag Manager) should also be deployed on the block page you show to users. This way, Bot Defender can share data back to Google Analytics before the bot leaves the application.
Google Analytics 4 Example Syntax
The below example will set a custom dimension with the parameter name bot_flag with User scope.
window.<APPID>_asyncInit = function(px) {
px.Events.on('score', function(score) {
try {
// The parameter 'bot_flag' should match the parameter you configured within your GA Admin dashboard
// You can also provide additional labels and data to GA in the same method. See the GA4 docs for more information.
gtag('set', 'user-properties', {
'bot_flag': score
});
} catch (err) {
// remove below line if you do not want to log errors in production
console.log("error: " + err);
}
});
};
Updated 12 days ago