Countly

Countly

Source:
Countly object to manage the internal queue and send requests to Countly server. More information on http://resources.count.ly/docs/countly-sdk-for-web

Example

SDK integration

<script type='text/javascript'>
  
//some default pre init
var Countly = Countly || {};
Countly.q = Countly.q || [];

//provide your app key that you retrieved from Countly dashboard
Countly.app_key = "YOUR_APP_KEY";

//provide your server IP or name. Use try.count.ly for EE trial server.
//if you use your own server, make sure you have https enabled if you use
//https below.
Countly.url = "https://yourdomain.com"; 

//start pushing function calls to queue
//track sessions automatically
Countly.q.push(['track_sessions']);
  
//track sessions automatically
Countly.q.push(['track_pageview']);
  
//load countly script asynchronously
(function() {
 var cly = document.createElement('script'); cly.type = 'text/javascript'; 
 cly.async = true;
 //enter url of script here
 cly.src = 'https://cdn.jsdelivr.net/countly-sdk-web/latest/countly.min.js';
 cly.onload = function(){Countly.init()};
 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(cly, s);
})();
</script>

Namespaces

userData

Methods

(static) init(conf)

Source:
Initialize Countly object
Example
Countly.init({
  //provide your app key that you retrieved from Countly dashboard
  app_key: "YOUR_APP_KEY",
  //provide your server IP or name. Use try.count.ly for EE trial server.
  url: "http://yourdomain.com" 
});
Parameters:
Name Type Description
conf Object Countly initialization Init object with configuration options
Properties
Name Type Attributes Default Description
app_key string app key for your app created in Countly
device_id string to identify a visitor, will be auto generated if not provided
url string your Countly server url, you can use your server URL or IP here
app_version string <optional>
0.0 the version of your app or website
country_code string <optional>
country code for your visitor
city string <optional>
name of the city of your visitor
ip_address string <optional>
ip address of your visitor
debug boolean <optional>
false output debug info into console
ignore_bots boolean <optional>
true option to ignore traffic from bots
interval number <optional>
500 set an interval how often to check if there is any data to report and report it in miliseconds
queue_size number <optional>
1000 maximum amount of queued requests to store
fail_timeout number <optional>
60 set time in seconds to wait after failed connection to server in seconds
inactivity_time number <optional>
20 after how many minutes user should be counted as inactive, if he did not perform any actions, as mouse move, scroll or keypress
session_update number <optional>
60 how often in seconds should session be extended
max_events number <optional>
10 maximum amount of events to send in one batch
ignore_referrers array <optional>
array with referrers to ignore
ignore_prefetch boolean <optional>
true ignore prefetching and pre rendering from counting as real website visits
force_post boolean <optional>
false force using post method for all requests
ignore_visitor boolean <optional>
false ignore this current visitor

(static) begin_session(noHeartBeat)

Source:
Start session
Parameters:
Name Type Description
noHeartBeat boolean true if you don't want to use internal heartbeat to manage session

(static) session_duration(sec)

Source:
Report session duration
Parameters:
Name Type Description
sec int amount of seconds to report for current session

(static) end_session(sec)

Source:
End current session
Parameters:
Name Type Description
sec int amount of seconds to report for current session, before ending it

(static) change_id(newId, merge)

Source:
Change current user/device id
Parameters:
Name Type Description
newId string new user/device ID to use
merge boolean move data from old ID to new ID on server

(static) add_event(event)

Source:
Report custom event
Parameters:
Name Type Description
event Object Countly Event object
Properties
Name Type Attributes Default Description
key string name or id of the event
count number <optional>
1 how many times did event occur
sum number <optional>
sum to report with event (if any)
dur number <optional>
duration to report with event (if any)
segmentation Object <optional>
object with segments key /values

(static) start_event(key)

Source:
Start timed event, which will fill in duration property upon ending automatically
Parameters:
Name Type Description
key string event name that will be used as key property

(static) end_event(event)

Source:
End timed event
Parameters:
Name Type Description
event string | object event key if string or Countly event same as passed to Countly.add_event

(static) user_details(user)

Source:
Provide information about user
Parameters:
Name Type Description
user Object Countly UserDetails object
Properties
Name Type Attributes Description
name string <optional>
user's full name
username string <optional>
user's username or nickname
email string <optional>
user's email address
organization string <optional>
user's organization or company
phone string <optional>
user's phone number
picture string <optional>
url to user's picture
gender string <optional>
M value for male and F value for femail
byear number <optional>
user's birth year used to calculate current age
custom Object <optional>
object with custom key value properties you want to save with user

(static) report_conversion(campaign_idopt, campaign_user_idopt)

Source:
Report user conversion to the server (when user signup or made a purchase, or whatever your conversion is), if there is no campaign data, user will be reported as organic
Parameters:
Name Type Attributes Description
campaign_id string <optional>
id of campaign, or will use the one that is stored after campaign link click
campaign_user_id string <optional>
id of user's click on campaign, or will use the one that is stored after campaign link click

(static) track_errors(segmentsopt)

Source:
Automatically track javascript errors that happen on the website and report them to the server
Parameters:
Name Type Attributes Description
segments string <optional>
additional key value pairs you want to provide with error report, like versions of libraries used, etc.

(static) log_error(err, segmentsopt)

Source:
Log an exception that you catched through try and catch block and handled yourself and just want to report it to server
Parameters:
Name Type Attributes Description
err Object error exception object provided in catch block
segments string <optional>
additional key value pairs you want to provide with error report, like versions of libraries used, etc.

(static) add_log(record)

Source:
Add new line in the log of breadcrumbs of what user did, will be included together with error report
Parameters:
Name Type Description
record string any text describing what user did

(static) stop_time()

Source:
Stop tracking duration time for this user

(static) start_time()

Source:
Start tracking duration time for this user, by default it is automatically tracked if you are using internal session handling

(static) track_sessions()

Source:
Track user sessions automatically, including time user spent on your website

(static) track_pageview(pageopt, ignoreListopt)

Source:
Track page views user visits
Parameters:
Name Type Attributes Description
page string <optional>
optional name of the page, by default uses current url path
ignoreList array <optional>
optional array of strings or regexes to test for the url/view name to ignore and not report

(static) track_view(pageopt, ignoreListopt)

Source:
Track page views user visits. Alias of track_pageview method for compatability with NodeJS SDK
Parameters:
Name Type Attributes Description
page string <optional>
optional name of the page, by default uses current url path
ignoreList array <optional>
optional array of strings or regexes to test for the url/view name to ignore and not report

(static) track_clicks(parentopt)

Source:
Track all clicks on this page
Parameters:
Name Type Attributes Description
parent Object <optional>
DOM object which children to track, by default it is document body
Source:
Generate custom event for all links that were clicked on this page
Parameters:
Name Type Attributes Description
parent Object <optional>
DOM object which children to track, by default it is document body

(static) track_forms(parentopt)

Source:
Generate custom event for all forms that were submitted on this page
Parameters:
Name Type Attributes Description
parent Object <optional>
DOM object which children to track, by default it is document body

(static) collect_from_forms(parentopt, useCustomopt)

Source:
Collect possible user data from submitted forms. Add cly_user_ignore class to ignore inputs in forms or cly_user_{key} to collect data from this input as specified key, as cly_user_username to save collected value from this input as username property. If not class is provided, Countly SDK will try to determine type of information automatically.
Parameters:
Name Type Attributes Default Description
parent Object <optional>
DOM object which children to track, by default it is document body
useCustom boolean <optional>
false submit collected data as custom user properties, by default collects as main user properties

(static) collect_from_facebook(customopt)

Source:
Collect information about user from Facebook, if your website integrates Facebook SDK. Call this method after Facebook SDK is loaded and user is authenticated.
Parameters:
Name Type Attributes Description
custom Object <optional>
Custom keys to collected from Facebook, key will be used to store as key in custom user properties and value as key in Facebook graph object. For example, {"tz":"timezone"} will collect Facebook's timezone property, if it is available and store it in custom user's property under "tz" key. If you want to get value from some sub object properties, then use dot as delimiter, for example, {"location":"location.name"} will collect data from Facebook's {"location":{"name":"MyLocation"}} object and store it in user's custom property "location" key

(static) opt_out()

Source:
Opts out user of any metric tracking

(static) opt_in()

Source:
Opts in user for tracking, if complies with other user ignore rules like bot useragent and prefetch settings