Table of Contents

• About The Project
• Getting Started
  • Installation
  • Static config
  • Generation
  • Local environment
• Usage

About The Project

This SDK helps to organize events in batches and to send batches to PaltaBrain API endpoint.

Getting Started

Installation

1. Get url and key from paltabrain team

2. Install NPM package

npm install @palta-brain/analytics

!Important. Tested only with npm.

Static config

When launching the analytics and logging files generator, the path parameter is mandatory. This parameter defines the directory where there will be no files named analytics.js and proto.js. This is necessary to avoid overwriting data in these files.

After the corresponding files are generated, all further work will be carried out with the analytics.js file, which is the main entry point.

Generation

Run next command

node node_modules/@palta-brain/analytics/dist/generator.cjs --url {url} --key {key} --path {path} [--shorten true --platforms Web,MobileWeb --dev true, --port {port}]

| Param | Description | Default value | Required | |---|---|---|---| | url | This link is also your login. It determines the address to which the events will be sent | - | true | | key | A key is the equivalent of a password | - | true | | path | The path to the generated analytics.js and proto.js file | - | true | | shorten | If true, all non-web events will be stripped. All descriptions will be stripped from data validation. | false | false | | platfroms | Activates platform filter, skipping events that are not marked for platforms. You can include several platfroms separating with comma without spaces. In terms of filtering, takes precedence over shorten. | - | false | | dev | This enables the operating mode for the local environment. This mode sends a request to http://localhost:8010/proxy. See chapter Local environment for more information | false | false | | port | Parameter that overrides the port. Used for local environment only | 8010 | false |

Local environment

For local environment you have to install proxy lib and start generation in dev mode. For proxy lib I recommend https://www.npmjs.com/package/local-cors-proxy

npm install -g local-cors-proxy

After it you have to start proxy

lcp --proxyUrl {url}

You can ovveride port if you need

lcp --proxyUrl {url} --port {port}

If you run generation with dev mode it shoulde use localhost url like main url and proxy will be redirect it to needed url.

node node_modules/@palta-brain/analytics/dist/generator.cjs --url {url} --key {key} --dev true

Usage

1. Import lib:

import analytics from "{path}/analytics";

2. Initialize SDK use init function. !Important. If you do not run the init function, nothing will work

analytics.init({
  logger?: (error: string) => void;
  defaultContext?: boolean;
  storageMode?: StorageMode;
  showLogs?: boolean;
});

Storage mode you can found in

analytics.config.storage;

| Param | Description | Default value | Required | |---|---|---|---| | logger | A logger is a function that will be called every time an error occurs. By default it is an empty function. But you can throw in console.log or, for example, sentry. The only parameter is a string that stores the error text | (error: string) => {} | false | | storageMode | StorageMode allows you to select the storage location where the data batches will be stored. There are two main parameters IN_MEMORY - we will save data in RAM only, IN_DB - we will use browser storage, currently LocalStorage, in the future IndexedDB | analytics.config.storage.IN_DB | false | | defaultContext | Used to set the default context settings | true | false | | showLogs | If set to true, the event name and its parameters will be logged to the console (not recommended for production) | false | false |

defaultContext

context.setApplication({ appPlatform: "Web" });
context.setOs({
  osName: parserResults.os.name,
  osVersion: parserResults.os.version,
});
context.setDevice({
  deviceBrand: parserResults.device.vendor,
  deviceCarrier: "",
  deviceModel: parserResults.device.model,
});

3. Set context properties.

Contex are the parameter that will be stamped on all the event submissions. Some parameters we fill in by default (you can disable this function). You can fill in, overwrite, or reset any parameters you enter.

The functions to set the relevant parts of the context are in the context object.

Each function takes a context object with typed parameters. Remember that only the parameters you passed in will be replaced

Example:

import analytics from "{path}/analytics";

analytics.context.setUser({ userId: 'UserId'});
...

4. Push event

Inside the events object you can find a list of all the categories, each of which will contain the corresponding functions for the required event. In order to send an event, you only need to call the function.

Note that each function may or may not accept the parameter object. If the function has no parameters, no object will be required. Otherwise, remember that parameters of this object are typed. They are typed not only at autocomplete and hint level, but also typing exists in runtime.

// Event without properties

  analytics.events.Logical.TestCase()?.track();

// Event with event properties

  analytics.events.Logical.EdgeCase({
    propString: 'String',
  })?.track();
...

5. Additional types

We can use additional types that do not exist in JS. If you see such types in the hint, you can find them in the types object.

new analytics.types.Decimal(1);
new analytics.types.Long(11);

6. Enum

Enum may be used for some parameters. If you come across such a parameter, you can find all the enums you need in the enum object/

analytics.enums.ResultEnum.resultError;
analytics.enums.ResultEnum.resultSuccess;