@aicore/core-analytics-client-lib 2.0.1 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +53 -27
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -28,49 +28,73 @@ in the `initAnalyticsSession` call below:
28
28
  onload="analyticsLibLoaded()"></script>
29
29
  <script>
30
30
  if(!window.analytics){ window.analytics = {
31
- _initData : [], loadStartTime: new Date().getTime(),
32
- event: function (){window.analytics._initData.push(arguments);}
31
+ _initData: [], loadStartTime: new Date().getTime(),
32
+ event: function (){window.analytics._initData.push(arguments);},
33
+ countEvent: function(t,c,s,n){window.analytics._initData.push([t,c,s,n||1,0]);},
34
+ valueEvent: function(t,c,s,v,n){window.analytics._initData.push([t,c,s,n||1,v||0]);}
33
35
  };}
34
36
  function analyticsLibLoaded() {
35
37
  initAnalyticsSession('your_analytics_account_ID', 'appName');
36
- analytics.event("core-analytics", "client-lib", "loadTime", 1, (new Date().getTime())-analytics.loadStartTime);
38
+ analytics.valueEvent("core-analytics", "client-lib", "loadTime", (new Date().getTime())-analytics.loadStartTime);
37
39
  }
38
40
  </script>
39
41
  ```
40
42
  This will create a global `analytics` variable which can be used to access the analytics APIs.
41
43
 
42
- NB: The script is loaded async, so it will not block other js scripts. `analytics.event` api can be called anytime
43
- after the above code and need not wait for the script load to complete.
44
+ NB: The script is loaded async, so it will not block other js scripts. `analytics.countEvent` and `analytics.valueEvent`
45
+ APIs can be called anytime after the above code and need not wait for the script load to complete.
44
46
 
45
47
  ## Raising analytics events
46
- We can now start logging analytics events by calling `analytics.event` API.
47
- The events will be aggregated and send to the analytics server periodically.
48
+ Events are aggregated and sent to the analytics server periodically.
49
+ Two APIs are available depending on your use case:
50
+
51
+ ### `analytics.countEvent` - Count occurrences
52
+ Use this to track how many times something happens.
48
53
 
49
54
  ```javascript
50
- // analyticsEvent(eventType, eventCategory, subCategory, eventCount, eventValue);
55
+ // countEvent(eventType, eventCategory, subCategory, eventCount)
51
56
 
52
- // Eg: event without counts and values
53
- analytics.event("platform", "os", "linux");
57
+ // Count a single occurrence
58
+ analytics.countEvent("platform", "os", "linux");
59
+
60
+ // Count multiple occurrences at once (e.g., html file opened 100 times)
61
+ analytics.countEvent("file", "opened", "html", 100);
62
+ ```
54
63
 
55
- // Eg: event with count, here it logs that html file is opened 100 times
56
- analytics.event("file", "opened", "html", 100);
64
+ #### Parameters
65
+ * `eventType` - A string, required
66
+ * `eventCategory` - A string, required
67
+ * `subCategory` - A string, required
68
+ * `eventCount` (_Optional_) : A non-negative number indicating the number of times the event happened. Defaults to 1.
57
69
 
58
- // Eg: event with count and value, here it logs that the startup time is 250 milliseconds.
59
- // Note that the value is unitless from analytics perspective. unit is deduced from subCategory name
60
- analytics.event("platform", "performance", "startupTimeMs", 1, 250);
70
+ ### `analytics.valueEvent` - Track values
71
+ Use this to measure quantities like latencies, durations, sizes, or anything where you need
72
+ running averages and distributions.
61
73
 
62
- // Eg: event with fractional value.
63
- analytics.event("platform", "CPU", "utilization", 1, .45);
64
- // Eg. Here we register that the system has 8 cores with each core having 2300MHz frequency.
65
- analytics.event("platform", "CPU", "coreCountsAndFrequencyMhz", 8, 2300);
74
+ ```javascript
75
+ // valueEvent(eventType, eventCategory, subCategory, eventValue, count)
76
+
77
+ // Track startup time of 250 milliseconds
78
+ // Note that the value is unitless from analytics perspective. Unit is deduced from subCategory name.
79
+ analytics.valueEvent("platform", "performance", "startupTimeMs", 250);
80
+
81
+ // Track fractional values (e.g., CPU utilization)
82
+ analytics.valueEvent("platform", "CPU", "utilization", .45);
83
+
84
+ // Track that a system has 8 cores with each core having 2300MHz frequency
85
+ analytics.valueEvent("platform", "CPU", "coreCountsAndFrequencyMhz", 2300, 8);
66
86
  ```
67
- ### API parameters
87
+
88
+ #### Parameters
68
89
  * `eventType` - A string, required
69
90
  * `eventCategory` - A string, required
70
91
  * `subCategory` - A string, required
71
- * `eventCount` (_Optional_) : A non-negative number indicating the number of times the event (or an event with a
72
- particular value if a value is specified) happened. defaults to 1.
73
- * `eventValue` (_Optional_) : A number value associated with the event. defaults to 0
92
+ * `eventValue` (_Optional_) : A numeric value associated with the event. Defaults to 0.
93
+ * `count` (_Optional_) : A non-negative number indicating how many times this value occurred. Defaults to 1.
94
+
95
+ ### Deprecated: `analytics.event`
96
+ The legacy `analytics.event(eventType, eventCategory, subCategory, eventCount, eventValue)` API is still
97
+ available for backwards compatibility but is deprecated. Please migrate to `countEvent` or `valueEvent`.
74
98
 
75
99
 
76
100
  ## Advanced Usages
@@ -85,15 +109,17 @@ function _initCoreAnalytics() {
85
109
  // Load core analytics scripts
86
110
  if(!window.analytics){ window.analytics = {
87
111
  _initData: [], loadStartTime: new Date().getTime(),
88
- event: function (){window.analytics._initData.push(arguments);}
112
+ event: function (){window.analytics._initData.push(arguments);},
113
+ countEvent: function(t,c,s,n){window.analytics._initData.push([t,c,s,n||1,0]);},
114
+ valueEvent: function(t,c,s,v,n){window.analytics._initData.push([t,c,s,n||1,v||0]);}
89
115
  };}
90
116
  let script = document.createElement('script');
91
117
  script.type = 'text/javascript';
92
118
  script.async = true;
93
119
  script.onload = function(){
94
- // replace `your_analytics_account_ID` and `appName` below with your values
120
+ // replace `your_analytics_account_ID` and `appName` below with your values
95
121
  window.initAnalyticsSession('your_analytics_account_ID', 'appName'); // if you have a custom analytics server
96
- window.analytics.event("core-analytics", "client-lib", "loadTime", 1,
122
+ window.analytics.valueEvent("core-analytics", "client-lib", "loadTime",
97
123
  (new Date().getTime())- window.analytics.loadStartTime);
98
124
  };
99
125
  script.src = 'https://unpkg.com/@aicore/core-analytics-client-lib/dist/analytics.min.js';
@@ -124,7 +150,7 @@ which means that any events that happen within 3 seconds cannot be distinguished
124
150
  // Init with default values and server controlled config. use the following `analyticsLibLoaded` function
125
151
  function analyticsLibLoaded() {
126
152
  initAnalyticsSession('your_analytics_account_ID', 'appName');
127
- analytics.event("core-analytics", "client-lib", "loadTime", 1, (new Date().getTime())-analytics.loadStartTime);
153
+ analytics.valueEvent("core-analytics", "client-lib", "loadTime", (new Date().getTime())-analytics.loadStartTime);
128
154
  }
129
155
 
130
156
  //Replace initAnalyticsSession in analyticsLibLoaded function for the below use cases.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aicore/core-analytics-client-lib",
3
- "version": "2.0.1",
3
+ "version": "2.0.3",
4
4
  "description": "Analytics client library for https://github.com/aicore/Core-Analytics-Server",
5
5
  "main": "dist/analytics.min.js",
6
6
  "type": "module",