api/lib/countly.common

This module defines default model to handle users collection data

Source:

Members

(static) periodObj

Source:
Properties:
Name Type Description
start number

period start timestamp in miliseconds

end number

period end timestamp in miliseconds

currentPeriodArr array

array with ticks for current period (available only for special periods), example ["2016.12.22","2016.12.23","2016.12.24", ...]

previousPeriodArr array

array with ticks for previous period (available only for special periods), example ["2016.12.22","2016.12.23","2016.12.24", ...]

dateString string

date format to use when outputting date in graphs, example D MMM, YYYY

isSpecialPeriod boolean

true if current period is special period, false if it is not

daysInPeriod number

amount of full days in selected period, example 30

periodContainsToday boolean

true if period contains today, false if not

uniquePeriodArr array

array with ticks for current period which contains data for unique values, like unique users, example ["2016.12.22","2016.w52","2016.12.30", ...]

uniquePeriodCheckArr array

array with ticks for higher buckets to current period unique value estimation, example ["2016.w51","2016.w52","2016.w53","2017.1",...]

previousUniquePeriodArr array

array with ticks for previous period which contains data for unique values, like unique users, example ["2016.12.22","2016.w52","2016.12.30"]

previousUniquePeriodCheckArr array

array with ticks for higher buckets to previous period unique value estimation, example ["2016.w47","2016.w48","2016.12"]

activePeriod string

period name formatted in dateString (available in non-special periods)

previousPeriod string

previous period name formatted in dateString (available in non-special periods)

periodMax number

max value of current period tick (available in non-special periods)

periodMin number

min value of current period tick (available in non-special periods)

reqMonthDbDateIds array

metric model month document ids to query for this period

reqZeroDbDateIds array

metric model year document ids to query for this period

Currently selected period

Examples

Special period object (7days)

{
   "start":1487721600000,
   "end":1488326399000,
   "activePeriod":"NA",
   "periodMax":"NA",
   "periodMin":"NA",
   "previousPeriod":"NA",
   "currentPeriodArr":["2017.2.22","2017.2.23","2017.2.24","2017.2.25","2017.2.26","2017.2.27","2017.2.28"],
   "previousPeriodArr":["2017.2.15","2017.2.16","2017.2.17","2017.2.18","2017.2.19","2017.2.20","2017.2.21"],
   "uniquePeriodArr":["2017.2.22","2017.2.23","2017.2.24","2017.2.25","2017.w9"],
   "uniquePeriodCheckArr":["2017.w8","2017.w9"],
   "previousUniquePeriodArr":["2017.2.15","2017.2.16","2017.2.17","2017.2.18","2017.2.19","2017.2.20","2017.2.21"],
   "previousUniquePeriodCheckArr":["2017.w7","2017.w8"],
   "dateString":"D MMM",
   "daysInPeriod":7,
   "isSpecialPeriod":true,
   "reqMonthDbDateIds":["2017:2"],
   "reqZeroDbDateIds":["2017:0"],
   "periodContainsToday":true
}

Simple period object (today period - hour)

{
   "start":1488240000000,
   "end":1488326399000,
   "activePeriod":"2017.2.28",
   "periodMax":11,
   "periodMin":0,
   "previousPeriod":"2017.2.27",
   "currentPeriodArr":["2017.2.28"],
   "previousPeriodArr":["2017.2.27"],
   "uniquePeriodArr":[],
   "uniquePeriodCheckArr":[],
   "previousUniquePeriodArr":[],
   "previousUniquePeriodCheckArr":[],
   "dateString":"HH:mm",
   "daysInPeriod":1,
   "isSpecialPeriod":false,
   "reqMonthDbDateIds":["2017:2"],
   "reqZeroDbDateIds":["2017:0"],
   "periodContainsToday":true
}

Methods

(static) decode(str) → {string}

Source:

Decode value from db, decoding first $ to $ and all . to . (dots). Decodes also url encoded values as $.

Parameters:
Name Type Description
str string

value to decode

Returns:

decoded string

Type
string

(static) encode(str) → {string}

Source:

Encode value to be passed to db as key, encoding $ symbol to $ if it is first and all . (dot) symbols to . in the string

Parameters:
Name Type Description
str string

value to encode

Returns:

encoded string

Type
string

(static) extractBarData(db, rangeArray, clearFunction, fetchFunction, maxItems, metricopt, totalUserOverrideObjopt) → {array}

Source:

Extracts top three items (from rangeArray) that have the biggest total session counts from the db object.

Example

Return data

[
   {"name":"iOS","percent":35},
   {"name":"Android","percent":33},
   {"name":"Windows Phone","percent":32}
]
Parameters:
Name Type Attributes Description
db object

countly standard metric data object

rangeArray object

array of all metrics/segments to extract (usually what is contained in meta)

clearFunction function

function to prefill all expected properties as u, t, n, etc with 0, so you would not have null in the result which won't work when drawing graphs

fetchFunction function

function to fetch property, default used is function (rangeArr, dataObj) {return rangeArr;}

maxItems number

amount of items to return, default 3

metric string <optional>

metric to output and use in sorting, default "t"

totalUserOverrideObj object <optional>

data from total users api request to correct unique user values

Returns:

array with top 3 values

Type
array

(static) extractChartData(db, clearFunction, chartData, dataProperties) → {object}

Source:

Extract single level data without metrics/segments, like total user data from users collection

Examples

Extracting total users data from users collection

countlyCommon.extractChartData(_sessionDb, countlySession.clearObject, [
     { data:[], label:"Total Users" }
 ], [
     {
         name:"t",
         func:function (dataObj) {
             return dataObj["u"]
         }
     }
 ]);
 

Returned data

{"chartDP":[
   {
       "data":[[0,0],[1,0],[2,0],[3,0],[4,0],[5,0],[6,0],[7,0],[8,0],[9,0],[10,0],[11,0],[12,0],[13,0],[14,0],[15,12]],
       "label":"Total Sessions",
       "color":"#DDDDDD",
       "mode":"ghost"
   },
   {
       "data":[[0,6],[1,14],[2,11],[3,18],[4,10],[5,32],[6,53],[7,55],[8,71],[9,82],[10,74],[11,69],[12,60],[13,17],[14,6],[15,3]],
       "label":"Total Sessions",
       "color":"#333933"
   }
 ],
 "chartData":[
   {"date":"22 Dec, 2016","pt":0,"t":6},
   {"date":"23 Dec, 2016","pt":0,"t":14},
   {"date":"24 Dec, 2016","pt":0,"t":11},
   {"date":"25 Dec, 2016","pt":0,"t":18},
   {"date":"26 Dec, 2016","pt":0,"t":10},
   {"date":"27 Dec, 2016","pt":0,"t":32},
   {"date":"28 Dec, 2016","pt":0,"t":53},
   {"date":"29 Dec, 2016","pt":0,"t":55},
   {"date":"30 Dec, 2016","pt":0,"t":71},
   {"date":"31 Dec, 2016","pt":0,"t":82},
   {"date":"1 Jan, 2017","pt":0,"t":74},
   {"date":"2 Jan, 2017","pt":0,"t":69},
   {"date":"3 Jan, 2017","pt":0,"t":60},
   {"date":"4 Jan, 2017","pt":0,"t":17},
   {"date":"5 Jan, 2017","pt":0,"t":6},
   {"date":"6 Jan, 2017","pt":12,"t":3}
 ],
 "keyEvents":[{"min":0,"max":12},{"min":0,"max":82}]
}
Parameters:
Name Type Description
db object

countly standard metric data object

clearFunction function

function to prefill all expected properties as u, t, n, etc with 0, so you would not have null in the result which won't work when drawing graphs

chartData object

prefill chart data with labels, colors, etc

dataProperties object

describing which properties and how to extract

Returns:

object to use in timeline graph with {"chartDP":chartData, "chartData":_.compact(tableData), "keyEvents":keyEvents}

Type
object

(static) extractData(db, clearFunction, dataProperties) → {array}

Source:

Extract single level data without metrics/segments, like total user data from users collection

Examples

Extracting total users data from users collection

countlyCommon.extractData(_sessionDb, countlySession.clearObject, [
    { name:"t" },
    { name:"n" },
    { name:"u" },
    { name:"d" },
    { name:"e" }
]);

Returned data

[
   {"_id":"2017-1-30","t":6,"n":6,"u":6,"d":0,"e":6},
   {"_id":"2017-1-31","t":2,"n":2,"u":2,"d":0,"e":2},
   {"_id":"2017-2-1","t":5,"n":5,"u":5,"d":0,"e":5},
   {"_id":"2017-2-2","t":5,"n":5,"u":5,"d":0,"e":5},
   {"_id":"2017-2-3","t":8,"n":8,"u":8,"d":0,"e":8},
   {"_id":"2017-2-4","t":7,"n":7,"u":7,"d":0,"e":7},
   {"_id":"2017-2-5","t":6,"n":6,"u":6,"d":0,"e":6},
   {"_id":"2017-2-6","t":5,"n":5,"u":5,"d":0,"e":5},
   {"_id":"2017-2-7","t":6,"n":6,"u":6,"d":0,"e":6},
   {"_id":"2017-2-8","t":5,"n":5,"u":5,"d":0,"e":5},
   {"_id":"2017-2-9","t":4,"n":4,"u":4,"d":0,"e":4},
   {"_id":"2017-2-10","t":6,"n":6,"u":6,"d":0,"e":6},
   {"_id":"2017-2-11","t":8,"n":8,"u":8,"d":0,"e":8},
   {"_id":"2017-2-12","t":3,"n":3,"u":3,"d":0,"e":3},
   {"_id":"2017-2-13","t":8,"n":6,"u":7,"d":0,"e":8},
   {"_id":"2017-2-14","t":7,"n":7,"u":7,"d":0,"e":7},
   {"_id":"2017-2-15","t":4,"n":4,"u":4,"d":0,"e":4},
   {"_id":"2017-2-16","t":2,"n":2,"u":2,"d":0,"e":2},
   {"_id":"2017-2-17","t":4,"n":4,"u":4,"d":0,"e":4},
   {"_id":"2017-2-18","t":14,"n":14,"u":14,"d":0,"e":14},
   {"_id":"2017-2-19","t":20,"n":11,"u":20,"d":0,"e":20},
   {"_id":"2017-2-20","t":25,"n":9,"u":25,"d":0,"e":25},
   {"_id":"2017-2-21","t":33,"n":12,"u":33,"d":0,"e":33},
   {"_id":"2017-2-22","t":36,"n":12,"u":36,"d":0,"e":36},
   {"_id":"2017-2-23","t":37,"n":12,"u":37,"d":0,"e":37},
   {"_id":"2017-2-24","t":29,"n":5,"u":29,"d":0,"e":29},
   {"_id":"2017-2-25","t":28,"n":7,"u":28,"d":0,"e":28},
   {"_id":"2017-2-26","t":3,"n":3,"u":3,"d":0,"e":3},
   {"_id":"2017-2-27","t":3,"n":3,"u":3,"d":0,"e":3},
   {"_id":"2017-2-28","t":7,"n":7,"u":7,"d":0,"e":7}
]
Parameters:
Name Type Description
db object

countly standard metric data object

clearFunction function

function to prefill all expected properties as u, t, n, etc with 0, so you would not have null in the result which won't work when drawing graphs

dataProperties object

describing which properties and how to extract

Returns:

object to use in timeline graph

Type
array

(static) extractMetric(db, rangeArray, clearFunction, dataProperties, totalUserOverrideObjopt) → {array}

Source:

Extract metrics data break down by segments, like total user by carriers

Examples

Extracting total users data from users collection

countlyCommon.extractData(countlyCarriers.getDb(), countlyCarriers.getMeta(), countlyCarriers.clearObject, [
    {
        name:"carriers",
        func:function (rangeArr, dataObj) {
            return rangeArr;
        }
    },
    { "name":"t" },
    { "name":"n" },
    { "name":"u" }
]);

Returned data

[
   {"_id":"Cricket Communications","t":37,"n":21,"u":34},
   {"_id":"Tele2","t":32,"n":19,"u":31},
   {"_id":"\tAt&amp;t","t":32,"n":20,"u":31},
   {"_id":"O2","t":26,"n":19,"u":26},
   {"_id":"Metro Pcs","t":28,"n":13,"u":26},
   {"_id":"Turkcell","t":23,"n":11,"u":23},
   {"_id":"Telus","t":22,"n":15,"u":22},
   {"_id":"Rogers Wireless","t":21,"n":13,"u":21},
   {"_id":"Verizon","t":21,"n":11,"u":21},
   {"_id":"Sprint","t":21,"n":11,"u":20},
   {"_id":"Vodafone","t":22,"n":12,"u":19},
   {"_id":"Orange","t":18,"n":12,"u":18},
   {"_id":"T-mobile","t":17,"n":9,"u":17},
   {"_id":"Bell Canada","t":12,"n":6,"u":12}
]
Parameters:
Name Type Attributes Description
db object

countly standard metric data object

rangeArray object

array of all metrics/segments to extract (usually what is contained in meta)

clearFunction function

function to prefill all expected properties as u, t, n, etc with 0, so you would not have null in the result which won't work when drawing graphs

dataProperties object

describing which properties and how to extract

totalUserOverrideObj object <optional>

data from total users api request to correct unique user values

Returns:

object to use in timeline graph

Type
array

(static) extractRangeData(db, propertyName, rangeArray, explainRange) → {array}

Source:

Extract range data from standard countly metric data model

Example

Extracting session frequency from users collection

   //outputs [{"f":"First session","t":352,"percent":"88.4"},{"f":"2 days","t":46,"percent":"11.6"}]
   countlyCommon.extractRangeData(_userDb, "f", _frequencies, countlySession.explainFrequencyRange);
Parameters:
Name Type Description
db object

countly standard metric data object

propertyName string

name of the property to extract

rangeArray object

array of all metrics/segments to extract (usually what is contained in meta)

explainRange function

function to convert range/bucket index to meaningful label

Returns:

array containing extracted ranged data as [{"f":"First session","t":352,"percent":"88.4"},{"f":"2 days","t":46,"percent":"11.6"}]

Type
array

(static) extractTwoLevelData(db, rangeArray, clearFunction, dataProperties, totalUserOverrideObjopt) → {object}

Source:

Extract two level data with metrics/segments, like total user data from carriers collection

Examples

Extracting carriers data from carriers collection

var chartData = countlyCommon.extractTwoLevelData(_carrierDb, ["At&t", "Verizon"], countlyCarrier.clearObject, [
     {
         name:"carrier",
         func:function (rangeArr, dataObj) {
             return rangeArr;
         }
     },
     { "name":"t" },
     { "name":"u" },
     { "name":"n" }
]);

Return data

{"chartData":['
   {"carrier":"At&t","t":71,"u":62,"n":36},
   {"carrier":"Verizon","t":66,"u":60,"n":30}
]}
Parameters:
Name Type Attributes Description
db object

countly standard metric data object

rangeArray object

array of all metrics/segments to extract (usually what is contained in meta)

clearFunction function

function to prefill all expected properties as u, t, n, etc with 0, so you would not have null in the result which won't work when drawing graphs

dataProperties object

describing which properties and how to extract

totalUserOverrideObj object <optional>

data from total users api request to correct unique user values

Returns:

object to use in bar and pie charts with {"chartData":_.compact(tableData)}

Type
object

(static) getDashboardData(data, properties, unique, totalUserOverrideObj, prevTotalUserOverrideObj) → {object}

Source:

Get calculated totals for each property, usualy used as main dashboard data timeline data without metric segments

Example
countlyCommon.getDashboardData(countlySession.getDb(), ["t", "n", "u", "d", "e", "p", "m"], ["u", "p", "m"], {u:"users"});
//outputs
{
     "t":{"total":980,"prev-total":332,"change":"195.2%","trend":"u"},
     "n":{"total":402,"prev-total":255,"change":"57.6%","trend":"u"},
     "u":{"total":423,"prev-total":255,"change":"75.7%","trend":"u","isEstimate":false},
     "d":{"total":0,"prev-total":0,"change":"NA","trend":"u"},
     "e":{"total":980,"prev-total":332,"change":"195.2%","trend":"u"},
     "p":{"total":103,"prev-total":29,"change":"255.2%","trend":"u","isEstimate":true},
     "m":{"total":86,"prev-total":0,"change":"NA","trend":"u","isEstimate":true}
}
Parameters:
Name Type Description
data object

countly metric model data

properties array

array of all properties to extract

unique array

array of all properties that are unique from properties array. We need to apply estimation to them

totalUserOverrideObj object

using unique property as key and total_users estimation property as value for all unique metrics that we want to have total user estimation overridden

prevTotalUserOverrideObj object

using unique property as key and total_users estimation property as value for all unique metrics that we want to have total user estimation overridden for previous period

Returns:

dashboard data object

Type
object

(static) getDateRange() → {string}

Source:

Getting the date range shown on the dashboard like 1 Aug - 30 Aug, using dateString property which holds the date format.

Returns:

string with formatted date range as 1 Aug - 30 Aug

Type
string

(static) getDescendantProp(obj, desc) → {object

Source:

Fetches nested property values from an obj.

Example

Path found

//outputs {"u":20,"t":20,"n":5}
countlyCommon.getDescendantProp({"2017":{"1":{"2":{"u":20,"t":20,"n":5}}}}, "2017.1.2");
Parameters:
Name Type Description
obj object

standard countly metric object

desc string

dot separate path to fetch from object

Returns:

fetched object from provided path

Type
object

(static) getPercentChange(previous, current) → {object}

Source:

Calculates the percent change between previous and current values.

Example
//outputs {"percent":"100%","trend":"u"}
  countlyCommon.getPercentChange(100, 200);
Parameters:
Name Type Description
previous number

data for previous period

current number

data for current period

Returns:

in the following format {"percent": "20%", "trend": "u"}

Type
object

(static) getPeriodObj(params, defaultPeriod) → {module:api/lib/countly.common.periodObj}

Source:

Get period object in atomic way from params, getting params.qstring.period for period and params.appTimezone for timezone

Parameters:
Name Type Description
params params

params object with app timezone and period

defaultPeriod string | Array.<string> | Array.<number>

default period value in case it's not supplied in the params

Returns:

period object

Type
module:api/lib/countly.common.periodObj

(static) getShortNumber(number) → {string}

Source:

Shortens the given number by adding K (thousand) or M (million) postfix. K is added only if the number is bigger than 10000, etc.

Example
//outputs 10K
countlyCommon.getShortNumber(10000);
Parameters:
Name Type Description
number number

number to shorten

Returns:

shorter representation of number

Type
string

(static) getSparklineData(data, props, clearObject) → {object}

Source:

Get total data for period's each time bucket as comma separated string to generate sparkle/small bar lines

Example
var sparkLines = countlyCommon.getSparklineData(countlySession.getDb(), {
    "total-sessions": "t",
    "new-users": "n",
    "total-users": "u",
    "total-duration": "d",
    "events": "e",
    "returning-users": function(tmp_x){return Math.max(tmp_x["u"] - tmp_x["n"], 0);},
    "avg-duration-per-session": function(tmp_x){return (tmp_x["t"] === 0) ? 0 : (tmp_x["d"] / tmp_x["t"]);},
    "avg-events": function(tmp_x){return (tmp_x["u"] === 0) ? 0 : (tmp_x["e"] / tmp_x["u"]);}
}, countlySession.clearObject);
//outputs
{
  "total-sessions":"73,84,80,72,61,18,11,7,17,27,66,39,41,36,39,36,6,11,6,16,22,30,33,34,32,41,29,9,2,2",
  "new-users":"24,30,25,20,16,18,11,7,17,18,20,18,17,11,15,15,6,11,6,16,13,14,12,10,7,4,8,9,2,2",
  "total-users":"45,54,50,44,37,18,11,7,17,27,36,39,41,36,39,36,6,11,6,16,22,30,33,34,32,29,29,9,2,2",
  "total-duration":"0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0",
  "events":"73,84,80,72,61,18,11,7,17,27,66,39,41,36,39,36,6,11,6,16,22,30,33,34,32,41,29,9,2,2",
  "returning-users":"21,24,25,24,21,0,0,0,0,9,16,21,24,25,24,21,0,0,0,0,9,16,21,24,25,25,21,0,0,0",
  "avg-duration-per-session":"0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0",
  "avg-events":"1.6222222222222222,1.5555555555555556,1.6,1.6363636363636365,1.6486486486486487,1,1,1,1,1,1.8333333333333333,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1.4137931034482758,1,1,1,1"
}
Parameters:
Name Type Description
data object

countly metric model data

props object

object where key is output property name and value could be string as key from data object or function to create new value based on existing ones

clearObject function

function to prefill all expected properties as u, t, n, etc with 0, so you would not have null in the result which won't work when drawing graphs

Returns:

object with sparkleline data for each property

Type
object

(static) getTimestampRangeQuery(params, inSeconds) → {object}

Source:

Get timestamp query range based on request data using period and app's timezone

Example
countlyCommon.getTimestampRangeQuery(params, true)
//outputs
{
   $gte:1488259482,
   $lte:1488279482
}
Parameters:
Name Type Description
params params

params object

inSeconds boolean

if true will output result in seconds, else in miliseconds

Returns:

mongodb query object with preset ts field to be queried

Type
object

(static) mergeMetricsByName(chartData, metric) → {object}

Source:

Merge metric data in chartData returned by @{link countlyCommon.extractChartData} or @{link countlyCommon.extractTwoLevelData }, just in case if after data transformation of countly standard metric data model, resulting chartData contains duplicated values, as for example converting null, undefined and unknown values to unknown

Examples

Sample input

   {"chartData":[
       {"metric":"Test","t":71,"u":62,"n":36},
       {"metric":"Test1","t":66,"u":60,"n":30},
       {"metric":"Test","t":2,"u":3,"n":4}
   ]}

Sample output

   {"chartData":[
       {"metric":"Test","t":73,"u":65,"n":40},
       {"metric":"Test1","t":66,"u":60,"n":30}
   ]}
Parameters:
Name Type Description
chartData object

chartData returned by @{link countlyCommon.extractChartData} or @{link countlyCommon.extractTwoLevelData }

metric string

metric name to merge

Returns:

chartData object with same metrics summed up

Type
object

(static) setPeriod(period)

Source:

Change currently selected period

Parameters:
Name Type Description
period string | array

new period, supported values are (month, 60days, 30days, 7days, yesterday, hour or [startMiliseconds, endMiliseconds] as [1417730400000,1420149600000])

(static) setTimezone(appTimezone)

Source:

Change timezone of internal Date object

Parameters:
Name Type Description
appTimezone string

name of the timezone

(static) timeString(timespent) → {string}

Source:

Format duration into highest unit of how much time have passed. Used in big numbers

Example
//outputs 2824.7 yrs
countlyCommon.timeString(1484654066);
Parameters:
Name Type Description
timespent number

amount in seconds or miliseconds passed since some reference point

Returns:

formated time with how much highest units passed

Type
string

(static) union(x, y) → {array}

Source:

Joined 2 arrays into one removing all duplicated values

Example
//outputs [1,2,3]
countlyCommon.union([1,2],[2,3]);
Parameters:
Name Type Description
x array

first array

y array

second array

Returns:

new array with only unique values from x and y

Type
array

(static) validateEmail(email) → {boolean}

Source:

Validate email address

Example
//outputs true
countlyCommon.validateEmail("test@test.test");

//outputs false
countlyCommon.validateEmail("test@test");
Parameters:
Name Type Description
email string

email address to validate

Returns:

true if valid and false if invalid

Type
boolean