Usage

Browser

Include dist/bundle.js in your html page.

Initialize event tracker

  var qualetics = new Qualetics.service("YOUR_APPLICATION_ID", "YOUR_APPLICATION_SECRET", "SESSION_PREFIX" /* , false (Optional, can be used to disable automatic pageview tracking, Options (Optional) object containing additional options ) */).init();

Angular

Install the sdk with npm

npm install --save @deerden/qualeticssdk;

Since webpack 5 no longer includes polyfills for the node.js core modules, they need to be added to webpack configuration.

This is done by first installing @angular-builders/custom-webpack and node-polyfill-webpack-plugin packages

npm install --save-dev @angular-builders/custom-webpack
npm install --save-dev node-polyfill-webpack-plugin

Then angular.json file needs to be edited, from that file, first locate line containing "builder": "@angular-devkit/build-angular:browser" and replace it with "builder": "@angular-builders/custom-webpack:browser" then inside architect.build.options add following property:

"customWebpackConfig": {
  "path": "./custom-webpack.config.js"
},

to have the custom webpack configuration to be used also by the development server, locale also following line "builder": "@angular-devkit/build:dev-server" and replace it with "builder": "@angular-builders/custom-webpack:dev-server"

next crate file called custom-webpack.config.js to the project root and add following content to that file:

const NodePolyfillPlugin = require("node-polyfill-webpack-plugin")

module.exports = {
  plugins: [
    new NodePolyfillPlugin()
  ]
};

Now SDK should work in Angular module:

import { Component } from '@angular/core';
import { QualeticsService } from "@deerden/qualeticssdk";

@Component({
  selector: 'example-component',
  templateUrl: './example.component.html',
  styleUrls: ['./example.component.css']
})
export class ExampleComponent {

  applicationId = "APPLICATION_ID";
  applicationSecret = "APPLICATION_SECRET";
  sessionPrefix = "SESSION_PREFIX";

  qualetics = new QualeticsService(this.applicationId, this.applicationSecret, this.sessionPrefix, true, {
    host:'wss://api.qualetics.com',
    port:443,
    appVersion: "1.0.0"
  });

  ngOnInit() {
    this.qualetics.init();
  }

  sendMessage() {
    this.qualetics.send({
      "actor": {
        "type": "User",
        "id": "js1234"
      },
      "action": {
        "type": "ButtonClick"
      },
      "context": {
        "type": "Button",
        "name": "Button1"
      }
    });
  }

}

Node

Install the sdk with npm

npm install --save @deerden/qualeticssdk;

When the sdk has been installed it needs to be initialized with following code.

const Qualetics = require("@deerden/qualeticssdk");
const qualetics = new Qualetics.service("YOUR_APPLICATION_ID", "YOUR_APPLICATION_SECRET", "SESSION_PREFIX");
qualetics.init();

The initialized sdk can be then used to track events

Sending events

After the tracker has been initialized you can start sending events. Data format in the event should be:

{
  "actor": {
    "type": "User", // Required
    "id": "js1234", // Optional, id of the user
    "attributes": { //Optional, key - value pairs that can provide more data about the actor
      "name": "John Doe",
      "age": "31",
      "address": {
        "street": "Test street 1",
        "zip": "50100"
      }
    }
  },
  "action": {
    "type": "New User", // Required
    "attributes": { // Optional, key - value pairs that can provide more data about the action
      "referrer": "Facebook",
      "coupon": "KIHSK123FS"
    }
  },
  "context": {
    "type": "Course", // Require
    "id": "12321123", // Optional, identifier for the context
    "attributes": { // Optional, key - value pairs that can provide more data about the context
      "speaker": "Jane Doe"
    }
  },
  "object": { // Optional
    "type": "Object",
    "name": "12321123",
    "attributes": {
      "speaker": "Jane Doe"
    }
  }

}

Events can be sent either by sending the complete JSON object

    qualetics.send({
      "actor": {
        "type": "User",
        "id": "js1234"
      },
      "action": {
        "type": "ButtonClick"
      },
      "context": {
        "type": "Button",
        "name": "Button1"
      },
      "object": {
        "type": "Object",
        "name": "Object1"
      }
    });

or using the builder message builder

    let message = qualetics.createMessage();
    message.setAction({
      type: "ButtonClick"
    }).setActor({
      type: "User",
      id: "js1234"
    }).setContext({
      type: "Button",
      name: "Button2"
    }).setObject({
      name: "Object",
      type: "ObjectType",
      attributes: {
        something: "else"
      }
    }).send();

Options

You can provide few options when construction the tracker instance.

{
  host: string, // Host that tracker will connect to, defaults to ws://api.qualetics.com

  port: number, // Port that tracker will connect to, defaults to 8083

  defaultActor: Actor object // Default actor for all the messages

  stickySessionId: boolean, // Store sessionId as cookie, defaults to true, only usable on browser
                            // If stored sessionId has different session prefix than what is configured
                            // new session id will be generated and it will be stored

  storeDefaultActorFromApiCall: boolean, // Store default actor from api call, defaults to true, only usable on browser
                                        // This setting will have no effect if default actor setting is set
  trackUserGeoLocation: boolean  // Include users geolocation information as metadata, defaults to false, only usable on browser
  
  trackPageVisibilityChanges: boolean //Track users page exits and returns automatically, defaults to true, only usable on browser
  
  appVersion: string // Version of app using the SDK, will be delivered to server with messages that are being sent

  disableErrorCapturing: boolean // Setting this to true will disable automatic error capturing

  captureClicks: boolean // If true, SDK will automatically capture click events

  captureTimings: boolean // If true, SDK will automatically capture timing information
}

Events

Currently you can listen to connection events from the tracker if you for some reason want to wait until tracker has connected. This is not necessary since the tracker will sent events when to connection is made is it wasn't at the time of the sending.

  qualetics.onConnect(() => {
    console.log("Connected");
  });

Development

Creating bundle to use with browser

Install required tools

npm install -g browserify
npm install -g terser

Build typescript

npm run build

Generate bundle

npm run bundle

Now updated bundle should be located in dist/bundle.js