@leiratech/trackzero-js

    2.1.0 • Public • Published

    # #

    #

    logo

    TrackZero-JS

    Powerful, insightful and real-time analytics that helps you take your products and apps to the next level.

    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

      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

    Keywords

    Install

    npm i @leiratech/trackzero-js

    DownloadsWeekly Downloads

    16

    Version

    2.1.0

    License

    MIT

    Unpacked Size

    21.7 kB

    Total Files

    10

    Last publish

    Collaborators

    • adelzu
    • shahrourit