Countly

Namespace

Countly

Description:
Source:
Example

SDK integration

var Countly = require("countly-sdk-nodejs");

Countly.init({
  app_key: "{YOUR-APP-KEY}",
  url: "https://API_HOST/",
  debug: true
});

Countly.begin_session();

Namespaces

userData

Members

(static) features

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

Methods

(static) init(conf)

Description:
  • Initialize Countly object
Source:
Deprecated:
  • {number} [conf.max_logs=100] - maximum amount of breadcrumbs to store for crash logs
Example
Countly.init({
  app_key: "{YOUR-APP-KEY}",
  url: "https://API_HOST/",
  debug: true,
  app_version: "1.0",
  metrics:{
     _os: "Ubuntu",
     _os_version: "16.04",
     _device: "aws-server"
  }
});
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 own 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
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
session_update number <optional>
 60 how often in seconds should session be extended
max_events number <optional>
 100 maximum amount of events to send in one batch
force_post boolean <optional>
 false force using post method for all requests
salt string <optional>
 shared secret used to append checksum256 to outgoing requests
clear_stored_device_id boolean <optional>
 false set it to true if you want to erase the stored device ID
test_mode boolean <optional>
 false set it to true if you want to initiate test_mode
storage_path string <optional>
 .countly-storage folder where the SDK stores data, including id, queues, etc. A relative path is resolved against the app's working directory
request_timeout number <optional>
 30 seconds to wait for the server's answer; after that the request counts as failed and is sent again later
standalone_worker boolean <optional>
 false in a cluster worker, send the worker's data directly instead of handing it to the main process. Needed when the main process does not run the SDK, for example in PM2 cluster mode. Each worker then keeps its data in its own "worker-" folder inside the storage folder
require_consent boolean <optional>
 false pass true if you are implementing GDPR compatible consent management. It would prevent running any functionality without proper consent
remote_config boolean | function <optional>
 false Enable automatic remote config fetching, provide callback function to be notified when fetching done
http_options= function <optional>
 function to get http options by reference and overwrite them, before running each request
max_key_length number <optional>
 128 maximum size of all string keys
max_value_size number <optional>
 256 maximum size of all values in our key-value pairs (Except "picture" field, that has a limit of 4096 chars)
max_segmentation_values number <optional>
 30 max amount of custom (dev provided) segmentation in one event
max_breadcrumb_count number <optional>
 100 maximum amount of breadcrumbs that can be recorded before the oldest one is deleted
max_stack_trace_lines_per_thread number <optional>
 30 maximum amount of stack trace lines would be recorded per thread
max_stack_trace_line_length number <optional>
 200 maximum amount of characters are allowed per stack trace line. This limits also the crash message length
metrics Object provide Metrics for this user/device, 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/device/installation came from
storage_type StorageTypes to determine which storage type is going to be applied
custom_storage_method Object user given storage methods
behavior_settings Object <optional>
 SDK behavior settings to use until the server's settings have been fetched once, in the format SDK Manager exports: an object with a "c" object
disable_sdk_behavior_settings_updates boolean <optional>
 false do not fetch the SDK behavior settings from the server; stored and provided settings still apply
disable_health_check boolean <optional>
 false do not send the health check at start
disable_backoff_mechanism boolean <optional>
 false never pause sending when the server answers slowly, whatever the server settings say

(static) halt(preventRequestProcessing)

Description:
  • WARNING!!! Should be used only for testing purposes!!! Resets Countly to its initial state (used mainly to wipe the queues in memory). Calling this will result in a loss of data
Source:
Parameters:
Name Type Description
preventRequestProcessing boolean if true request queues wont be processed, for testing purposes

(static) group_features(features)

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

Adding all features under one group

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

Grouping features

Countly.group_features({
   activity:["sessions","events","views"],
   info:["attribution","users"]
});
//After this call Countly.add_consent("activity") to allow "sessions","events","views"
//or call Countly.add_consent("info") to allow "attribution","users"
//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
Description:
  • Check if consent is given for specific feature (either core feature of from custom feature group)
Source:
Parameters:
Name Type Description
feature string name of the feature, possible values, "sessions","events","views","crashes","attribution","users" or customly provided through Countly.group_features
Returns:
true if consent is given, false if not
Type
bool
Description:
  • Check if any consent is given, for some cases, when crucial parts are like device_id are needed for any request
Source:
Returns:
true if any consent is given, false if not
Type
bool

(static) setLoggingEnabled(enableLogging)

Description:
  • Enable/disable logging, to be used after init
Source:
Parameters:
Name Type Description
enableLogging boolean if true logging is enabled
Description:
  • Add consent for specific feature, meaning, user allowed to track that data (either core feature of from custom feature group)
Source:
Parameters:
Name Type Description
feature string | array name of the feature, possible values, "sessions","events","views","crashes","attribution","users" or customly provided through Countly.group_features
Description:
  • Remove consent for specific feature, meaning, user opted out to track that data (either core feature of from custom feature group)
Source:
Parameters:
Name Type Description
feature string | array name of the feature, possible values, "sessions","events","views","crashes","attribution","users" or custom provided through Countly.group_features
Description:
  • Remove consent internally for specific feature,so that a request wont be sent for the operation
Source:
Parameters:
Name Type Description
feature string | array name of the feature, possible values, "sessions","events","views","crashes","attribution","users" or custom provided through CountlyBulkUser.group_features
enforceConsentUpdate Boolean regulates if a request will be sent to the server or not. If true, removing consents will send a request to the server and if false, consents will be removed without a request

(static) begin_session(noHeartBeat)

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

(static) session_duration(sec)

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

(static) end_session(sec)

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

(static) get_device_id_type() → {number}

Description:
  • Check and return the current device id type
Source:
Returns:
a number that indicates the device id type
Type
number

(static) get_device_id() → {string}

Description:
  • Gets the current device id
Source:
Returns:
device id
Type
string

(static) set_id(newId)

Description:
  • Changes the current device ID according to the device ID type (the preffered method)
Source:
Parameters:
Name Type Description
newId string new user/device ID to use. Must be a non-empty string value. Invalid values (like null, empty string or undefined) will be rejected

(static) change_id(newId, mergeopt)

Description:
  • Change current user/device id. Without merge, everything recorded for the current user is finished and sent under the current ID first: the open view's duration, unsaved custom property changes and recorded events. The session is ended, and timed events, breadcrumbs, calls waiting for consent and stored remote config values are cleared, so nothing of the previous user is reported for the new one.
Source:
Parameters:
Name Type Attributes Description
newId string new user/device ID to use. Must be a non-empty string; a number is used as text
merge boolean <optional>
 move data from old ID to new ID on server

(static) add_event(event)

Description:
  • Report custom event
Source:
Parameters:
Name Type Description
event Event 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)

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

(static) end_event(event)

Description:
  • End timed event
Source:
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)

Description:
  • Report user data
Source:
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
picturePath string <optional>
 local path to user's picture, if 'user.picture' is set this will be ignored
gender string <optional>
 M value for male and F value for female
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_id, campaign_user_idopt)

Description:
  • Report user conversion to the server (when user signup or made a purchase, or whatever your conversion is)
Source:
Parameters:
Name Type Attributes Description
campaign_id string id of campaign, the last part of the countly campaign link
campaign_user_id string <optional>
 id of user's clicked on campaign link, if you have one

(static) report_feedback(feedback)

Description:
  • Provide information about user
Source:
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
email string <optional>
 user's email
comment string <optional>
 user's comment

(static) track_errors(segmentsopt)

Description:
  • Automatically track javascript errors that happen on the nodejs process. An uncaught exception is reported as a fatal crash, stored synchronously and the process exits with code 1. An unhandled promise rejection is reported as a non-fatal error and the process keeps running, as it did before Node.js 15 made unhandled rejections stop the process.
Source:
Parameters:
Name Type Attributes Description
segments object <optional>
 additional key value pairs you want to provide with error report, like versions of libraries used, etc.

(static) log_error(err, segmentsopt)

Description:
  • Log an exception that you catched through try and catch block and handled yourself and just want to report it to server
Source:
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)

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

(static) fetch_remote_config(keysopt, omit_keysopt, callbackopt)

Description:
  • Fetch remote config. Values downloaded for a device ID that is no longer the current one are not used; the callback then gets an error and the current values.
Source:
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) → {varies}

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

(static) stop_time()

Description:
  • Stop tracking duration time for this user/device
Source:

(static) start_time()

Description:
  • Start tracking duration time for this user/device, by default it is automatically if you scalled (@link begin_session)
Source:

(static) track_view(nameopt, viewSegmentsopt)

Description:
  • Track which parts of application user visits
Source:
Parameters:
Name Type Attributes Description
name string <optional>
 optional name of the view
viewSegments object <optional>
 optional key value object with segments to report with the view

(static) track_pageview(nameopt, viewSegmentsopt)

Description:
  • Track which parts of application user visits. Alias of track_view method for compatability with Web SDK
Source:
Parameters:
Name Type Attributes Description
name string <optional>
 optional name of the view
viewSegments object <optional>
 optional key value object with segments to report with the view

(static) report_trace(trace)

Description:
  • Report performance trace
Source:
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) report_app_start()

Description:
  • Report time passed since app start trace
Source:

(static) request(request)

Description:
  • Make raw request with provided parameters. The values are sent as given, without the SDK's length limits, and the request counts towards the request queue size like every other request.
Source:
Example
Countly.request({app_key:"somekey", device_id:"someid", events:'[{"key":"val","count":1}]', begin_session:1});
Parameters:
Name Type Description
request Object object with key/values which will be used as request parameters

(static) flush(timeoutopt, callbackopt) → {Promise.<boolean>}

Description:
  • Sends everything recorded so far without waiting for the next heartbeat: recorded events are packed into requests and the queued requests are sent one after another, also right after an earlier failed attempt. Use it before a script, a scheduled job or a serverless function ends, or in a shutdown handler before calling process.exit().
Source:
Example
process.on("SIGTERM", async () => {
    Countly.end_session();
    await Countly.flush(5);
    process.exit(0);
});
Parameters:
Name Type Attributes Description
timeout number <optional>
 seconds to wait at most. Without it, the call waits until the requests queued at the time of the call are sent, or one of them fails
callback function <optional>
 called with true when they were all delivered, and with false when something is still waiting: the server could not be reached, the timeout passed, test mode is on, or this is a cluster worker that hands its data to the main process
Returns:
resolves with the same value the callback receives
Type
Promise.<boolean>