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

Members

(static) features

Source:
Array with list of available features that you can require consent for

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
max_logs number <optional>
100 maximum amount of breadcrumbs to store for crash logs
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
require_consent boolean <optional>
false Pass true if you are implementing GDPR compatible consent management. It would prevent running any functionality without proper consent
utm boolean <optional>
{"source":true, "medium":true, "campaign":true, "term":true, "content":true} Object instructing which UTM parameters to track
use_session_cookie boolean <optional>
true Use cookie to track session
session_cookie_timeout number <optional>
30 How long till cookie session should expire in minutes
remote_config boolean | function <optional>
false Enable automatic remote config fetching, provide callback function to be notified when fetching done
namespace string <optional>
"" Have separate namespace of of persistant data
metrics Object <optional>
{} provide metrics for this user, or else will try to collect what's possible
Properties
Name Type Description
_os string name of platform/operating system
_os_version string version of platform/operating system
_device string device name
_resolution string screen resolution of the device
_carrier string carrier or operator used for connection
_density string screen density of the device
_locale string locale or language of the device in ISO format
_store string source from where the user came from
_browser string browser name
_browser_version string browser version
_ua string user agent string
headers Object <optional>
{} Object to override or add headers to all SDK requests

(static) group_features(features)

Source:
Modify feature groups for consent management. Allows you to group multiple features under one feature group
Examples

Adding all features under one group

Countly.group_features({all:["sessions","events","views","scrolls","clicks","forms","crashes","attribution","users"]});
//After this call Countly.add_consent("all") to allow all features
    

Grouping features

Countly.group_features({
   activity:["sessions","events","views"],
   interaction:["scrolls","clicks","forms"]
});
//After this call Countly.add_consent("activity") to allow "sessions","events","views"
//or call Countly.add_consent("interaction") to allow "scrolls","clicks","forms"
//or call Countly.add_consent("crashes") to allow some separate feature
Parameters:
Name Type Description
features object object to define feature name as key and core features as value
Source:
Check if consent is given for specific feature (either core feature of from custom feature group)
Parameters:
Name Type Description
feature string name of the feature, possible values, "sessions","events","views","scrolls","clicks","forms","crashes","attribution","users" or customly provided through Countly.group_features
Source:
Check if any consent is given, for some cases, when crucial parts are like device_id are needed for any request
Source:
Add consent for specific feature, meaning, user allowed to track that data (either core feature of from custom feature group)
Parameters:
Name Type Description
feature string | array name of the feature, possible values, "sessions","events","views","scrolls","clicks","forms","crashes","attribution","users", etc or customly provided through Countly.group_features
Source:
Remove consent for specific feature, meaning, user opted out to track that data (either core feature of from custom feature group)
Parameters:
Name Type Description
feature string | array name of the feature, possible values, "sessions","events","views","scrolls","clicks","forms","crashes","attribution","users", etc or customly provided through Countly.group_features

(static) begin_session(noHeartBeat, force)

Source:
Start session
Parameters:
Name Type Description
noHeartBeat boolean true if you don't want to use internal heartbeat to manage session
force bool force begin session request even if session cookie is enabled

(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, force)

Source:
End current session
Parameters:
Name Type Description
sec int amount of seconds to report for current session, before ending it
force bool force end session request even if session cookie is enabled

(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) report_orientation(orientationopt)

Source:
Report device orientation
Parameters:
Name Type Attributes Description
orientation string <optional>
orientation as landscape or portrait

(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) 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_trace(trace)

Source:
Report performance trace
Parameters:
Name Type Description
trace Object apm trace object
Properties
Name Type Attributes Description
type string device or network
name string url or view of the trace
stz number start timestamp
etz number end timestamp
app_metrics Object key/value metrics like duration, to report with trace where value is number
apm_attr Object <optional>
object profiling attributes (not yet supported)

(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) fetch_remote_config(keysopt, omit_keysopt, callbackopt)

Source:
Fetch remote config
Parameters:
Name Type Attributes Description
keys array <optional>
Array of keys to fetch, if not provided will fetch all keys
omit_keys array <optional>
Array of keys to omit, if provided will fetch all keys except provided ones
callback function <optional>
Callback to notify with first param error and second param remote config object

(static) get_remote_config(keyopt)

Source:
Get Remote config object or specific value for provided key
Parameters:
Name Type Attributes Description
key string <optional>
if provided, will return value for key, or return whole object

(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, viewSegmentsopt)

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
viewSegments object <optional>
optional key value object with segments to report with the view

(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

(static) track_scrolls(parentopt)

Source:
Track all scrolls 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, trackHiddenopt)

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
trackHidden boolean <optional>
provide true to also track hidden inputs, default false

(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

(static) report_feedback(feedback)

Source:
Provide information about user
Parameters:
Name Type Description
feedback Object object with feedback properties
Properties
Name Type Attributes Description
widget_id string id of the widget in the dashboard
contactMe boolean <optional>
did user give consent to contact him
platform string <optional>
user's platform (will be filled if not provided)
app_version string <optional>
app's app version (will be filled if not provided)
rating number user's rating from 1 to 5
email string <optional>
user's email
comment string <optional>
user's comment

(static) show_feedback_popup(id)

Source:
Show specific widget popup by the widget id
Parameters:
Name Type Description
id string id value of related feedback widget, you can get this value by click "Copy ID" button in row menu at "Feedback widgets" screen

(static) enable_feedback(configurationopt)

Source:
Show feedback popup by passed widget ids array
Parameters:
Name Type Attributes Description
configuration object <optional>
required - includes "popups" property as string array of widgets ("widgets" for old versions) example configuration: {"popups":["5b21581b967c4850a7818617"]}

(static) serialize(value) → {string}

Source:
Overwrite serialization function for extending SDK with encryption, etc
Parameters:
Name Type Description
value any value to serialize
Returns:
serialized value
Type
string

(static) deserialize(data) → {varies}

Source:
Overwrite deserialization function for extending SDK with encryption, etc
Parameters:
Name Type Description
data string value to deserialize
Returns:
deserialized value
Type
varies

(static) getViewName() → {string}

Source:
Overwrite a way to retrieve view name
Returns:
view name
Type
string

(static) getViewUrl() → {string}

Source:
Overwrite a way to retrieve view url
Returns:
view url
Type
string