Overview

This guide demonstrates how to use Zoom Analytics API using JavaScript language. The API is based on JSON format.
The API is used to send actions (goals or non-goals) and properties to Zoom Analytics so that they can be tracked and be used to find insights.
They are used in addition to all the data that is collected automatically such as the pages visited, GEO-location information, time of day, referral and many other properties.

Note: API requires version 4 of the widget. You can get the latest version from the Settings page. New customers get automatically the latest version available.
If your code snippet includes _zaVer=4 then you have the latest version.

Defining the page name

By default the page name is taken from the browser's URL address bar. The query parameters (that come after the question mark ?) are excluded from the page name. For example if the URL is http://www.mysite.com/page123?some-query=4&other_query=5 then the page name will be 'page123'.
There are 3 other options for setting the page name:
1) Taking also the query string in the name
2) Setting a user-defined name
3) Using the page title as name
To set a non-default page name you need to add an additional JavaScript to the code snippet.
To take also the query string add the following to the code snippet:
__za_api({ type: 'init', include_query_string: true});
To set user-defined name add the following to the code snippet:
__za_api({ type: 'init', page: 'page name'});
To set the page title as the page name add the following to the code snippet:
__za_api({ type: 'init', take_name_from_title: true});
Note: page, take_name_from_title and include_query_string are optional and are mutually exclusive. That means that only one of them can appear in a page.

User specific pages (such as a photo album a user has created and shares with friends) should be defined as one page. If you have 1000 customers and each has a similar page (conceptually) but different URL then you will not get meaningful statistical information. For example if you have a sharing page named '/user-album/abcd12345' for one user and '/user-album/efgh12345' for another, you should set the page name to be '/user-album/'. You can do it by adding the following to the code snippet:
__za_api({ type: 'init', page: '/user-album/'});

To set the page name in callback function you need to implement a function called __ZA_PageNameCallback:
__ZA_PageNameCallback = function() {
      return "My Custom Name"; //must return a string
}
Note: if callback function returns false (or any non-string value) then page name will be taken as default value or according to what is defined in the code snippet.

Add action / goal

Syntax
__za_api({type: 'add_action', list_name: 'list_name', action_name: 'action_name', action_int_val :[int], is_goal: [0/1], action_tag: 'action_tag', is_exclusive: [0/1]});
General Description
Actions can be used to track any interaction the user has with the website. Usually actions are assigned to meaningful mouse clicks. An Action can be a goal or a non-goal. Note that every page viewis automatically an action, so no need to add special API calls for that. You can read more about Actions here.
Parameters
type:
Mandatory parameter. Must be equal to 'add_action'
list_name:
Optional parameter. The action will be part of this list (read more about lists). It is a string up to 50 characters long. Can't start with underscore.
action_name:
Mandatory parameter. Identifies the action (read more about actions). It is a string up to 50 characters long. Can't start with underscore.
action_int_val:
Optional parameter. Tracks the average value over time (read more about int_val). It is an integer number.
is_goal:
Optional parameter. Defines if action is a goal or not (read more about goals). By default an action is non-goal. Possible values are 0 or 1.
action_tag:
Optional parameter. Describes the type of the action. Here is the list of possible action tags. A tag is purely informative and its purpose is to help Zoom Analytics engine to provide better insights.
is_exclusive:
Optional parameter. Defines if action that is part of a list is exclusive or not. Exclusive means that only one action per list will be recorded for a session. If more than one action belonging to the same list is sent during a session, only the last one will be recorded. All actions are not exclusive by default.
Examples
Define two types of signup goals - 'free' and 'pro'
__za_api({type: 'add_action', list_name: 'signup', action_name: 'free', is_goal: 1, action_tag: 'signup'});
__za_api({type: 'add_action', list_name: 'signup', action_name: 'pro', is_goal: 1, action_tag: 'signup'});
Track the average amount users spend and define it as 'goal'
__za_api({type: 'add_action', action_name: 'amount bought', action_int_val: 45, is_goal: 1, action_tag: 'buy'});
A sample insight may be:
'Users who visit your 'FAQ' page are likely to spend higher amount of money (49$ on average)'
or
'Users coming between 12:00-13:00 are likely to spend less amount of money (12.4$ on average)'
Define user reading a product review as an action
__za_api({type: 'add_action', action_name: 'Read review'});
Track the fields filled in a signup form. Add action to list 'signup form' whenever user takes the focus out of a form input field
(Using jQuery to detect focusout event)
$('#setup_form').find('input').focusout(function(){
   __za_api({type: 'add_action', list_name: 'Signup form', action_name: $(this).attr('name')});
});
Track the type of product a customer buys: 'Standard product' or 'Premium product'; and define it as 'goal'
__za_api({type: 'add_action', list_name: 'Buy', action_name: 'Standard product', is_goal: 1, action_tag: 'buy'});
__za_api({type: 'add_action', list_name: 'Buy', action_name: 'Premium product', is_goal: 1, action_tag: 'buy'});
In general avoid too much granularity in the defined lists, it may prevent finding meaningful insights. You should group actions into categories such that a category has similar characteristics. For example if you are selling 2 types of bracelets 'black' and 'blue', create only one action called 'bracelet'. But if you are looking to characterize the users who buy each type of bracelet then you define two different actions for them.
Define list that holds the type of article the user has read
__za_api({type: 'add_action', list_name: 'Articles read', action_name: 'Sports section', action_tag: 'watch_content'});
__za_api({type: 'add_action', list_name: 'Articles read', action_name: 'News section', action_tag: 'watch_content'});
__za_api({type: 'add_action', list_name: 'Articles read', action_name: 'Economics section', action_tag: 'watch_content'});

Count action

Syntax
__za_api({type: 'count_action', list_name: 'list_name', action_name: 'action_name', is_goal: [0/1], action_tag: 'action_tag'});
General Description
Action counters are used to track the average number of times users do a specific action. Usually action counters are assigned to specific mouse clicks. An Action counter can be a goal or a non-goal. You can read more about Action Counters here.
Parameters
type:
Mandatory parameter. Must be equal to 'count_action'
list_name:
Optional parameter. The action counter will be part of this list (read more about lists). It is a string up to 50 characters long. Can't start with underscore.
action_name:
Mandatory parameter. Identifies the action counter (read more about actions). It is a string up to 50 characters long. Can't start with underscore.
is_goal:
Optional parameter. Defines if action is a goal or not (read more about goals). By default an action is non-goal. Possible values are 0 or 1.
action_tag:
Optional parameter. Describes the type of the action. Here is the list of possible action tags. A tag is purely informative and its purpose is to help Zoom Analytics engine to provide better insights.
Examples
Count which types of articles users read more (on average)
__za_api({type: 'count_action', list_name: 'Articles read', action_name: 'Sports section', action_tag: 'watch_content'});
__za_api({type: 'count_action', list_name: 'Articles read', action_name: 'News section', action_tag: 'watch_content'});
__za_api({type: 'count_action', list_name: 'Articles read', action_name: 'Economics section', action_tag: 'watch_content'});
A possible insight might be 'Users who were originally referred by a search engine are likely to read more articles of the "Sports section" (5.4 articles on average).

Add property

Syntax
__za_api({type: 'add_property', list_name: 'list_name', property_name: 'property_name', property_int_val :[int], property_tag: 'property_tag', is_exclusive: [0/1]});
General Description
Properties are used to describe the user. They are independent of the user interaction with the website. Many properties are collected by Zoom Analytics automatically. You can configure custom properties by using the following JavaScript API. You can add the call anytime during the visitor's session. The properties you send will be associated with all the user actions during that session. You can read more about Properties here.
Parameters
type:
Mandatory parameter. Must be equal to 'add_property'
list_name:
Optional parameter if property_int_val defined. If property_int_val not defined then list_name is mandatory. The property will be part of this list (read more about lists). It is a string up to 50 characters long. Can't start with underscore.
property_name:
Mandatory parameter. Identifies the property (read more about properties). It is a string up to 50 characters long. Can't start with underscore.
property_int_val:
Optional parameter. Tracks the average value over time (read more about int_val). It is an integer number.
property_tag:
Optional parameter. Describes the type of the property. Here is the list of possible property tags. A tag is purely informative and its purpose is to help Zoom Analytics engine to provide better insights..
is_exclusive:
Optional parameter. Defines if property is exclusive or not (per the list it is defined in). Exclusive means that only one property per list will be recorded for a session. If more than one property belonging to the same list is sent during a session, only the last one will be recorded. All properties are exclusive by default.
Examples
Define users as either 'Registered users' or 'Visitors'
__za_api({type: 'add_property', list_name: 'user type', property_name: 'Registered user', property_tag: 'user_type_registered'});
__za_api({type: 'add_property', list_name: 'user type', property_name: 'Visitor', property_tag: 'user_type_visitor'});
Define days since user signup
__za_api({type: 'add_property', property_name: 'Days since signup', property_int_val: 17, property_tag: 'days_since'});
Define user's gender
__za_api({type: 'add_property', list_name: 'Gender', property_name: 'Male'});
__za_api({type: 'add_property', list_name: 'Gender', property_name: 'Female'});
Define user's age
__za_api({type: 'add_property', property_name: 'Age', property_int_val: 47});