@aicore/core-analytics-client-lib

Analytics client library for https://github.com/aicore/Core-Analytics-Server

Usage no npm install needed!

<script type="module">
  import aicoreCoreAnalyticsClientLib from 'https://cdn.skypack.dev/@aicore/core-analytics-client-lib';
</script>

README

Core Analytics Client Lib - JS

The Javascript client library to be used from browser/nodejs to raise analytics events for Core-Analytics-Server.

Code Guardian

<app> build verification

Sonar code quality check Security rating vulnerabilities Code Coverage Code Bugs Reliability Rating Maintainability Rating Lines of Code Technical debt

Usage

Initialize the session

Embed the script in your HTML file :

<html lang="en">
<script type="module">
    // For production use cases, use url: https://unpkg.com/@aicore/core-analytics-client-lib/dist/analytics.min.js
    // The below url is for development purposes only.
    import {initSession} from "https://unpkg.com/@aicore/core-analytics-client-lib/src/analytics.js";
    initSession("accountID", "appName");
</script>
</html>

initSession(): Initialize the analytics session. It takes the following parameters:

  • accountID: Your analytics account id as configured in the server or core.ai analytics
  • appName: The app name to log the events against. Eg: "phoenixCode"
  • postIntervalSeconds (Optional): This defines the interval between sending analytics events to the server. Default is 10 minutes
  • granularitySec (Optional): The smallest time period under which the events can be distinguished. Multiple events happening during this time period is aggregated to a count. The default granularity is 3 Seconds, which means that any events that happen within 3 seconds cannot be distinguished in ordering.
  • postBaseURLInit Optional: Provide your own analytics server address if you self-hosted the server
// Example for custom initSession where the analytics aggregated data 
// is posted to custom server https://localhost:3000 every 600 secs
// with a granularity(resolution) of 5 seconds.

initSession("accountID", "appName", 600, 5, "https://localhost:3000");

Raising analytics events

Once initSession is called, we can now start logging analytics events by calling analyticsEvent API. The API registers an analytics event. The events will be aggregated and send to the analytics server periodically.

// analyticsEvent(eventType, eventCategory, subCategory, eventCount, eventValue);

// Eg: event without counts and values
analyticsEvent("platform", "os", "linux");

// Eg: event with count, here it logs that html file is opened 100 times
analyticsEvent("file", "opened", "html", 100);

// Eg: event with count and value, here it logs that the startup time is 250 milliseconds. 
// Note that the value is unitless from analytics perspective. unit is deduced from subCategory name
analyticsEvent("platform", "performance", "startupTimeMs", 1, 250);

// Eg: event with fractional value.
analyticsEvent("platform", "CPU", "utilization", 1, .45);
// Eg. Here we register that the system has 8 cores with each core having 2300MHz frequency.
analyticsEvent("platform", "CPU", "coreCountsAndFrequencyMhz", 8, 2300);

API parameters

  • eventType - A string, required
  • eventCategory - A string, required
  • subCategory - A string, required
  • eventCount (Optional) : A non-negative number indicating the number of times the event (or an event with a particular value if a value is specified) happened. defaults to 1.
  • eventValue (Optional) : A number value associated with the event. defaults to 0

Contribute to core-analytics-client-lib

Building

Since this is a pure JS template project, build command just runs test with coverage.

> npm install   # do this only once.

# Before raising a pull request, run release script and add the generated
# minified files in dist folder to commits .
# WARNING!!!: If the minified files are not checkedin git push will fail. 
> npm run release

Linting

To lint the files in the project, run the following command:

> npm run lint

To Automatically fix lint errors:

> npm run lint:fix

Testing

To run tests, open the file test/unit-test.html in the browser.

Publishing packages to NPM

To publish a package to npm, raise a pull request against npm branch.

Dependency updates

We use Rennovate for dependency updates: https://blog.logrocket.com/renovate-dependency-updates-on-steroids/

Code Guardian

Several automated workflows that check code integrity are integrated into this template. These include:

  1. GitHub actions that runs build/test/coverage flows when a contributor raises a pull request
  2. Sonar cloud integration using .sonarcloud.properties
    1. In sonar cloud, enable Automatic analysis from Administration Analysis Method for the first time image

IDE setup

SonarLint is currently available as a free plugin for jetbrains, eclipse, vscode and visual studio IDEs. Use sonarLint plugin for webstorm or any of the available IDEs from this link before raising a pull request: https://www.sonarlint.org/ .

SonarLint static code analysis checker is not yet available as a Brackets extension.

Internals

Testing framework: Mocha , assertion style: chai

See https://mochajs.org/#getting-started on how to write tests Use chai for BDD style assertions (expect, should etc..). See move here: https://www.chaijs.com/guide/styles/#expect