In this article, we will focus on event callbacks. We will talk about what they are, how you can combine them with our products and give a couple of examples of use cases.
In this guide we’ll go over:
Event callbacks: what are they?
To understand the concept, we have to talk about a callback itself. In the most basic form, a callback is a piece of code which initiates an action after a specific piece of code has been executed. This last piece of code can actually be almost anything, but is usually an event. Hence, an event callback. So, in short:
an event has happened → an action has to take place → event callback makes it happen
To visualize it, we’ve created a simple example in which we want the browser to write down ‘This is AWESOME’ when a campaign is opened. Mind you: in this example, the word ‘action’ is part of the code we use for the event. This will happen and is sometimes inevitable. Don’t let that fool you and just remember the basics. This is the code we’re going to use:
The callback above is just a simple one, but in essence, this is what an event callback does.
So how does Usabilla use them? We use a number of callbacks (see below) to signal that an interaction with Usabilla has taken place on a website. You could then send information from Usabilla to other web optimization tools, such as analytics tools, A/B testing tools or Data Management Platforms.
How can I combine them with Usabilla?
In order to implement the Event Callbacks, your technical team will have to add a javascript snippet to the existing Usabilla code on your website or, if applicable, in your tag management system. The following information will help your technical team to use our Event Callbacks.
Event Callbacks can be placed on your website using the following code:
window.usabilla_live('setEventCallback', callback);
where callback is a javascript function with the following signature:
function(category, action, label, value, userData) {};
This function will be called when one of the below events occur on your website. For each event the function's parameters will be used as described.
Please note that 'setEventCallback' can only be defined once on every page and that it must always be defined after the default Usabilla script has been loaded. If you try to define it more than once on a page, the callback function will be overwritten with the last defined one.
Event 1: the feedback form is opened
This event is fired when the user clicks on your feedback button to open the feedback form. It uses the following arguments in the callback function.
-
category: "feedback"
-
action: "Feedback:Open"
-
label: null
-
value: null
- userData: An empty object
Event 2: feedback is given
This event is fired when the user successfully completes the feedback form. It uses the following arguments in the callback function.
-
category: "feedback"
-
action: "Feedback:Success"
-
label: The comment the user entered.
-
value: The mood rating score given by the user (1 - 5).
-
userData: An object containing the responses the user provided.
Event 3: a campaign is shown to the user
This event is fired when an active campaign is shown to the user. It uses the following arguments in the callback function.
-
category: "campaign"
-
action: "Campaign:Open"
-
label: The analytics ID of your campaign
-
value: null
-
userData: An empty object
Event 4: the user moves to the next page of a campaign
This event is fired when the user clicks the continue button in a campaign to navigate to the next page of this campaign. It uses the following arguments in the callback function.
-
category: "campaign"
-
action: "Campaign:Page Switch"
-
label: The analytics ID of your campaign
-
value: null
-
userData: An object containing the responses the user provided. The user's responses will be nested into another object called "data".
Event 5: the user successfully completes a campaign
This event is fired when the user submits their campaign responses on the last page of the campaign, clicks the redirect button of a Recruit Participants survey or when the user provides feedback, while a Boost live feedback campaign is active. It uses the following arguments in the callback function.
-
category: "campaign"
-
action: "Campaign:Success"
-
label: The analytics ID of your campaign
-
value: null
-
userData: An empty object
Event 6: the user closes the campaign
This event is fired when the user closes a campaign by clicking its exit cross or the optional "close" link. It uses the following arguments in the callback function.
-
category: "campaign"
-
action: "Campaign:Close"
-
label: The analytics ID of your campaign
-
value: null
- userData: An empty object
Event 7: the user clicks the call to action in Boost live Feedback campaign
This event is fired in addition to the "Feedback:Open" event when the user clicks the call to action button in a Boost live Feedback campaign. It uses the following arguments in the callback function.
-
category: "campaign"
-
action: "Campaign:Feedback Clicked"
-
label: The analytics ID of your campaign
-
value: null
- userData: An empty object
Examples
As mentioned in the introduction of this article, event callbacks essentially allow you to send Usabilla feedback to other solutions in the browser. Also, the event callbacks will allow you to take certain actions based on the feedback that your users leave. Possibilities include, but are not limited to:
- Push events to your analytics suite, including the feedback a user left.
- Push events to your A/B test tool, including the user's feedback on a test variant.
- Push events to your CRM tool, in order to add feedback to their profile.
- Trigger a chat functionality for unhappy users to provide further assistance.
- Trigger a Usabilla survey in the current or a future visit to follow up on the user's feedback.
In the following example, we will collect feedback and simply log the feedback to the console in case a user leaves feedback or responds to a campaign:
window.usabilla_live('setEventCallback', function(category, action, label, value, userData){
function flat(source, target) {
Object.keys(source).forEach(function (k) {
if (source[k]!== null && typeof source[k] === 'object') {
flat(source[k], target);
return;
}
target[k] = source[k];
});
}
if(action === "Feedback:Success" || (action === "Campaign:Page Switch" && userData.end)) {
var userDataFlat = {};
flat(userData, userDataFlat);
for(var i in userDataFlat) {
console.log(i +" => " + userDataFlat[i]);
}
}
});The steps that we are taking in the example are:
- Define the event callback function.
- Since some of the responses are in nested objects, we create a function to flatten arrays.
- We then check whether the user is taking the desired action; leaving a feedback item or campaign response.
- Lastly, we log each question value and user response to the console.
Hopefully, this article will get you started. We look forward to seeing your usage of our event callbacks live in action. Any questions? Please reach out to our support team.