Sending custom events

Usermaven automatically captures all clicks, form submissions, and page visits on your website and product with its auto-capture technology, so you can easily follow conversions and users' activities without writing code.

For more advanced actions, such as third-party embedded content (chat windows, Youtube videos, order forms, etc.), you can utilize Usermaven’s Javascript API to send an event.

If you want to learn more about different ways of event tracking offered by Usermaven, read more here.

Before you can send your first custom event, make sure that you have the tracking script already installed on the page from where you are sending the event.

To track an event, use the usermaven("track", "EVENT_NAME") function. You can choose any name you want for the event. We recommend giving your events short and precise names and using the same letter case such as 'snake case'. It makes it easier to work with them in the future.

If you are sending custom events from a SaaS app and want to associate events with the People/Company who performed those actions, then you will have to use the usermaven("id") function before using the the usermaven("track", "EVENT_NAME") function.

General example codes

// Send a "sign up" event to Usermaven
usermaven("track", "signed_up");
// Send a "chat initiation" event to Usermaven
usermaven("track", "chat_started");
// Send an event that a user watched a whole video
usermaven("track", "viewed_complete_video");

Note: Any JavaScript code added to your website must be wrapped in <script> and </script> tags.

Adding custom data/attributes to an event

Providing more details about an event could be a great thing. In order to do this, use the second argument to attach data to an event. This information will appear in the contacts view for the specified People/Company. You can also use these attributes to filter stats inside the dashboard.

usermaven("track", "plan_upgraded", {
  plan_name: "pro",
  amount: 99
})

Example: Sending events for YT video engagement to Usermaven

One of the most popular custom code events is sending engagement stats of a Youtube video embedded on your website. To send a custom event for a Youtube video on your site, first, make sure Usermaven's tracking script is installed on the page the video is on.

Then, create a short script to add callback listeners to the video player event. Catch events for the video player progress and send them accordingly to Usermaven.

Here’s an example code for embedded Youtube videos. Note that this is just an example and has to be adjusted for each individual site and video.

let player; 
let videoInterval;
let videoEventName = "sample-video"; 
let passedBreakpoint = 0; 
const breakpoints = [0.25, 0.5, 0.75]; 
 
 
function onYouTubeIframeAPIReady() {     
    player = new YT.Player("player", { 
        height: "360",
        width: "640", 
        videoId: "M7lc1UVf-VE", 
        events: { 
            onStateChange: onPlayerStateChange 
        } 
    });
}
 
 
let done = false;
function onPlayerStateChange(event) {
    if ( 
        !done && 
        event.data === YT.PlayerState.PLAYING &&  parseInt(player.getCurrentTime(), 10) === 0 
     ) {
        usermaven("track", `clicked-${videoEventName}`);
        videoInterval = setInterval(checkVideoState, 1000); 
     } 
 
 
     if (event.data === YT.PlayerState.ENDED) { 
         done = true; usermaven("track", `watched-${videoEventName}-100%`);
          clearInterval(videoInterval);
         }
} 
 
 
function checkVideoState() {
    const viewedPercentage = player.getCurrentTime() / player.getDuration(); 
    breakpoints.forEach((breakpoint) => { 
        if (passedBreakpoint < breakpoint && viewedPercentage >= breakpoint) { 
            passedBreakpoint = breakpoint; usermaven("track", `watched-${videoEventName}-${breakpoint * 100}%`); 
            } 
    }); 
}

Take some time to consider the names you will give to your events. You can name them whatever you want, but it's best to keep it simple and consistent.