Overview


UserJoy provides a customer success solution for software-as-a-service (SaaS) startups and enterprises. It allows you to easily track what users are doing on your web application and communicate with them in a personal way.


Installation


After signing up for UserJoy, we provide you a snippet of Javascript code that you need to add to every page on your web app. Follow the steps below to install UserJoy on your app:


  1. Paste this code before </body> on every page


  2.                             
    <script type = "text/javascript">
        window.userjoy=window.userjoy||[],window.userjoy.methods=["identify","company","track","page","track_link","track_form"],window.userjoy.factory=function(e){return function(){var t=Array.prototype.slice.call(arguments);return t.unshift(e),window.userjoy.push(t),window.userjoy}};for(var i=0;i < window.userjoy.methods.length;i++){var key=window.userjoy.methods[i];window.userjoy[key]=window.userjoy.factory(key)}window.userjoy.load=function(e){if(!document.getElementById("userjoy-client-js")){window._userjoy_id=e;var t=document.createElement("script");t.type="text/javascript",t.id="userjoy-client-js",t.async=!0,t.src=("https:"===document.location.protocol?"https:":"http:")+"//d1jozu9mugm1h5.cloudfront.net/js/userjoy.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(t,n)}};
        userjoy.SNIPPET_VERSION = '1.0.0';
    
        // TODO: update your app key below
        userjoy.load('YOUR_APP_KEY');
    
        userjoy.identify({
    
            // TODO: logged in user's email.
            // Used to identify the user and send him email messages
            // (REQUIRED)
            email: 'test@userjoy.co',
    
            // TODO: logged in user's unique id.
            // if your app allows a user to change his email address,
            // then user_id is required to identify user
            // (OPTIONAL)
            user_id: '758439753849',
    
            // TODO: logged in user's payment status
            // MUST be one of 'trial' / 'free' / 'paying' / 'cancelled'
            // (REQUIRED)
            status: 'trial',
    
            // TODO: logged in user's sign-up date in UNIX timestamp
            // (milliseconds after epoch)
            // (REQUIRED)
            joined: 1403353187345,
    
            // TODO: logged in user's name ('first-name last-name')
            // Used while sending emails e.g. 'Hi John, ...'
            // (OPTIONAL)
            name: 'John Appleseed',
    
            // TODO: logged in user's subscription plan
            // Helps you segment users by plan name
            // (OPTIONAL)
            plan: 'Enterprise',
    
            // TODO: monthly revenue from user
            // (OPTIONAL)
            revenue: 499
        });
    </script>
                                
                            
  3. Review the TODO comments, and edit the code to pass the correct values for the logged in user


  4. Activate your app by clicking on Start Tracking Now once you have installed the code on your website


Javascript API


To track all actions being carried out by a user, you must call the userjoy.identify api call with a set of properties. We require that you pass the ‘email’, ‘joined’ and ‘status’ properties. If you allow your users to change their email ids, then you must also pass the ‘user_id’ property to uniquely identify a user. This could be primary key of the user on your database, or some other id that uniquely identifies him.


Identify


                        
userjoy.identify(properties, callback)
                        
                    


Identify the logged in user


Params


Name Required Type Description
properties Yes Object Attributes of the user such as email, name, user_id etc.
callback No Function Optional function to be called after the userjoy.identify call

Properties


Name Required Type Description
email Yes String email address of the logged in user
user_id No String unique user id, should be database id
status Yes String must be one of 'trial', 'free', 'paying' or 'cancelled'
joined Yes Number user's sign-up date in UNIX timestamp (e.g. 1403353187345)
name No String user's name ('first-name last-name' or username). This would be used while sending messages to the user.
plan No String name of the plan
revenue No Number revenue from the user
custom No Object You can also pass custom properties related to the user in an optional object called 'custom'. These properties will appear on the User Profile page.

Company


                        
userjoy.company(properties, callback)
                        
                    


Identify the company/team/organization that the logged in user belongs to


Params


Name Required Type Description
properties Yes Object Attributes of the company such as name, members etc.
callback No Function Optional function to be called after the userjoy.company call

Properties


Name Required Type Description
name Yes String name of the company
company_id Yes String unique company id (e.g. database primary key id)
status Yes String must be one of 'trial', 'free', 'paying' or 'cancelled'
joined No Number company's joining / creation date in UNIX timestamp (e.g. 1403353187345)
plan No String name of the plan
custom No Object You can also pass custom properties related to the company in an optional object called 'custom'.

Track


                        
userjoy.track(name, callback)
                        
                    


Track an event performed by the user.


Params


Name Required Type Description
name Yes String Name of the event, i.e. 'Added New Member', 'Created New Task', 'Upgraded Plan' etc
callback No Function Optional function to be called after the userjoy.track call

Segmenting


UserJoy allows you to segment your users based on events and attributes.


Events


Every tracked action of the user is counted as an event.


Attributes


Properties associated with a user are called attributes, e.g. ‘joined’ time, ‘last session’ time, ‘name’, ‘email’, ‘plan’, ‘revenue’ etc.


Types of filters


Type Description
Has done To get users who have carried out an action in the given time frame
Has not done To get users who have not carried out an action in the given time frame
Count To get users who have carried out an action a certain number of times in the given time frame
Attribute filters To get users whose attribute matches the criteria set by the filter, e.g. os (operating system) equals ‘windows’

Engagement Score


The engagement score reflects the level of engagement of all your users.

It is a normalized score (0-100) in accordance to the amount of time a user has spent on your application in the last 14 days. Your most engaged users have a score close to 100, and your least engaged users have a score close to 0. It is calculated as follows:


user_avg_usage = average time spent by the user over the last 14 days
max_avg_usage = maximum average time spent by any user over the last 14 days
min_avg_usage = minimum average time spent by any user over the last 14 days

For the user,
engagement_score = 100*(user_avg_usage - min_avg_usage)/(max_avg_usage - min_avg_usage)

Health Segments


There are three special segments called Good Health, Average Health and Bad Health which are pre-defined when you create a new app.


By default, UserJoy defines:

  • ‘Poor Health’ as 33% of your users with the lowest engagement score (0-33)
  • ‘Average Health’ as middle 34% of your users according to engagement score (34-67)
  • ‘Good Health’ as 33% of your users with the highest engagement score (67-100)


You may update the definitions of these health segments based on the requirements of your application. For example, you may define ‘Good Health’ as users who have engagement score greater than 80, and have also done ‘Submitted form login-form’ within a day.


User health is updated every day. The health segments are evaluated and assigned in the following order:

  1. Good Health
  2. Average Health
  3. Poor Health


Therefore, the ‘Poor Health’ segment gets a preference over the ‘Average Health’ segment, that then gets a preference over the ‘Good Health’ segment.


It means that if a user a user matched both ‘Poor Health’ and ‘Good Health’ segments, then he will be considered to be in 'Poor Health'.


Messaging


Message-Box


By default, UserJoy puts a little icon with a ‘?’ mark on it, on all your pages, when the user is logged in. Clicking this opens the message-box where the user can send you support / feedback etc messages.


To switch off the default message-box icon, go to the App settings and in ‘Widget Settings’, turn the switch off.