For more details, please visit https://TrackZero.io

Installation

npm install @leiratech/trackzero-js

Setup

Import

Note: You can either use import or require, both work fine

import { TrackZeroClient } from "@leiratech/trackzero-js";

Initialization

Initialize the TrackZeroClient instance by passing in your API key before using any of the methods.

let instance = new TrackZeroClient("API-KEY");

Getting Started

TrackZero Instance

After initializing the TrackZero instance, you could get the instance anywhere in your project

let instance = TrackZeroClient.getInstance();

Analytics Spaces

The first you need to do before sending data to TrackZero is to create your data container (Analytics Space), please make sure to read the Concepts & Definitions to fully understand how TrackZero works.

Creating Analytics Spaces

await instance.createAnalyticsSpaceAsync("analytics-space-id");

Deleting Analytics Spaces

await instance.deleteAnalyticsSpaceAsync("analytics-space-id");

Entity

TrackZero uses what is known as Upsert (Update or Insert). Creating an Entity or updating it uses the same operation. This allows undeterministic creation of Entities (Or updating), which means you don’t have to remember the state of an Entity in order to determine whether you need to update or create.

import { Entity } from "@leiratech/trackzero-js";

Create an Entity object

/**
 * @constructor
 * Initializes the Entity object
 *
 * @param {string} type
 * @param {(string|number)} identity
 */
let entity = new Entity("type", "id");

Add Attributes

/**
 * Adds custom attributes to the entity
 *
 * @param {string} attribute
 * @param {*} value
 * @returns the entity instance
 */
entity.addAttribute("attribute", "value");

Add Attributes Referencing Other Entities

/**
 * Adding Reference Attributes that will link to other entities
 *
 * @param {string} attribute
 * @param {string} referenceTypereferencing
 * @param {(string|number)} referenceId
 * @returns the entity instance
 */
entity.addEntityReferencedAttribute(
  "attribute",
  "referenceType",
  "referenceId"
);

Attach a geopoint to an entity to analyse it on a map

/**
 * Automatically Translates a GeoPoint (Lat, Long) to Country and State and links them as Referenced Entity.
 *
 * @param {number} latitude
 * @param {number} longitude
 * @returns the entity instance
 */
entity.addAutomaticallyTranslatedGeoPoint(
  41.037086118695825,
  28.98489855136287
);

Track Entity

/**
 * Creates/Updates the Entity
 *
 * @async
 * @param {Entity} entity
 * @param {string} analyticsSpaceId
 * @returns the response status
 */
await instance.upsertEntityAsync(entity, "analytics-space-id");

Note: Upsert (Update/Insert) is applied when sending the entity. So, if the the entity of type X with id Y already exists, then it gets updated, else a new entity is created. This also applies to the entity's referenced attributes in addEntityReferencedAttribute.

Complete Entity Example

let user = new Entity("User", "USER_ID")
  .addAttribute("Name", "Sam Smith")
  .addAttribute("Date Of Birth", new Date(Date.UTC(1990, 11, 23))) //Make sure dates are in UTC
  .addEntityReferencedAttribute("Location", "Country", "US")
  .addAutomaticallyTranslatedGeoPoint(41.037086118695825, 28.98489855136287);

await instance.upsertEntityAsync(user, "analytics-space-id");

Delete Entity

:exclamation:   Deletion is permanent and cannot be undone.

/**
 * Deletes the Entity
 *
 * @async
 * @param {string} type
 * @param {(string|number)} id
 * @param {string} analyticsSpaceId
 * @returns the response status
 */
await instance.deleteEntityAsync("type", "id", "analytics-space-id");

Analytics Spaces

When your user wants to access their data in order to run reports or view dashboards, you will have to create an Analytics Space Session. These sessions are short lived and scoped sessions. Simply create an Analytics Space session and forward the user to the URL in the response.

Get an Analytics Space Portal Session

You can easily create the analytics space session. The result from the server will contain one attribute that we are interested in which is the Url. Once you have the Url, send the user to that Url provided by TrackZero and they can start using the platform.

/**
 * Creates an analytics portal session
 *
 * @async
 * @param {number} analyticsSpaceId
 * @param {number} [ttl]
 * @returns the portal session
 */
let session = await instance.createAnalyticsSpacePortalSessionAsync(
  "analytics-space-id",
  3600
);

Sessions automatically expire and get removed. No action is necessary from your side.

Resources

Changelog

License

MIT