Sending custom events

Usermaven simplifies data collection by automatically recording clicks, form submissions, and page visits on your website and product through its auto-capture technology. For more sophisticated actions like tracking third-party embedded content, such as chat windows or YouTube videos, Usermaven provides a Javascript API for sending custom events. Ensure you have the tracking script installed on the relevant page before sending your first custom event.

If you’re interested in exploring various event tracking options with Usermaven, find more details here .

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 YouTube 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.