Introduction

The Alphastream event tracker is a package which helps track different events on your website along with its data, time, urls, etc.

Getting Started

To use the application, simply run npm i as-event-tracker and import it into the app.

Set Up

All methods and classes mentioned in this guide can be accessed through the global EventCapture class, for example EventCapture.create({}), so that keyword will be omitted from the remainder of the guide.

Initialisation

Before any events can be logged, you'll first need to initialise the app. To do this you'll need to call the create method as shown below:

create({
    storeInCookies: false,
    apiKey: <insert api key>,
    logEvents: true, //if you'd like to log events for debugging
    captureUrl: 'https://collect.alphastream.io/v1/collect',
    clientChannelMeta: <ClientChannelMeta object> // this is a nullable value and does not need to be passed in.
});

A list of the options that will be except are as follows:

Option	Type	Default	Role	Optional
apiKey	`string`		The api key used to identify clients.
storeInCookies	`boolean`	`true`	Specifies if VisitorId and/or Session ids will be held in cookie storage.	☑️
captureUrl	`string`		The capture url to use, there is currently only https://collect.alphastream.io/v1/collect.
logEvents	`boolean`	`false`	Will log out to the `console` on every event request and response. Note that errors will still be logged even if this feature is turned off.	☑️
clientChannelMeta	`ClientChannelMeta`		This allows for the channel meta, that is passed on each call to be predifined, if not set then this values in the channel meta will be determined based on global values provided by the device/browser.	☑️
dataSource	`string`	taken from `[global].window.location.hostname`	The data source identifier for the client app, this can be an app name, url or whatever you use to identify your app on a domain or environemt level.	☑️
logger	`Logger`	an instance of the `Logger` object that uses the console.log	The logger used for debugging errors and calls to and from the collection api.	☑️

`ClientChannelMeta`

This object represents pre set channel meta default values that are passed through the create method:

Name	Type	Default
`timezone_offset`	`string`	`Intl.DateTimeFormat()` api provided.
`device_type`	`string`	Provided by the `navigator` api
`device_platform`	`string`	Provided by the `navigator` api
`screen_width`	`number`	Provided by the `global` api
`screen_height`	`number`	Provided by the `global` api
`culture_code`	`string`	Provided by the `navigator` api
`os`	`string`	Provided by the `navigator` api
`browser`	`string`	Provided by the `navigator` api

Custom Logging

Clients can define a custom Logger to be used in place of the default Logger which uses console.log. The Logger is an abstract class that can be extanded to create a custon logger, as shown below:

npm package 'custom logger' example:

import { LogLevel, Logger } from 'as-event-tracker';

export default class ConsoleLogger extends Logger {
    executeLog(
        message: string,
        level: LogLevel,
        content?: any
    ) : void {
        if(level !== LogLevel.Error)
            return;
    
        if(content)
            console.error(`WBC Event - ${message}: `, content);
        else
            console.error(`WBC Event - ${message}`);
    }
}

`Logger`

This object is an abstract class that can be implemented, to create your own custom logger:

Name	Params	Notes	Abstract
`log`	`message: { type: string }`, `content?: {type: any	nullable}`	Fired on events that are `LogLevel.Debug`
`info`	`message: { type: string }`, `content?: {type: any	nullable}`	Fired on events that are `LogLevel.Information`
`warn`	`message: { type: string }`, `content?: {type: any	nullable}`	Fired on events that are `LogLevel.Warning`
`error`	`message: { type: string }`, `content?: {type: any	nullable}`	Fired on events that are `LogLevel.Error`
`executeLog`	`message: { type: string }`, `content?: {type: any	nullable}`,` level: { type: LogLevel }`	An abstract method to be defined by the client when implmenting the abstract `Logger` class

`LogLevel`

An enum used to specify the level of the log message being called.

Name	Value
`Debug`	`"log"`
`Information`	`"info"`
`Warning`	`"warn"`
`Error`	`"error"`

User Set Up

In order to associate an event to a given clients application user, the client ref will need to be provided using the following code:

setClientRef(<local client>);

This can be any identify used to identify users on a clients application.

Request Entities

`Component`

The Components class is created to represent the component associated with the event being called. This is an optional parameter on all event requests and is made of the following properties:

Name	Type	Notes	Required
`type`	`string`	Used to specify the element type.	☑️
`id`	`string`	The elements `id` attribute.	☑️
`elementTree`	`string`	This is best represented as a `/` delimited string the represents a list of parent dom tree element ids.	☑️
Example use case:

new EventCapture.Component({
    type: "button",
    id: "btnOne",
    elementTree: "mainWrapper/sectionRight/btnOne"
});

`MetaData`

This class is used to store associated event meta data such as search terms or content ids:

Name	Type	Default	Notes	Required
`key`	`MetaDataKey`		The key that specifies what the data relates to.	☑️
`type`	`string`	`null`	An additional identifier for the the meta data value, for example when the key is `MetaDataKey.SearchTerm`, this value can specify what type of data was being searched, ie users or companies.
`value`	`string`			☑️

`MetaDataKey`

An enum used to specify the type of meta data being stored.

Name	Value
`EntityId`	`"entity_id"`
`ContentId`	`"content_id"`
`Topic`	`"topic"`
`SearchTerm`	`"term"`
`UserEmail`	`"user_email"`
`UserId`	`"user_id"`
`PageNumber`	`"page_number"`
`PageSize`	`"page_size"`
`SearchResults`	`"results"`
`Tab`	`"active_tab"`
`RelatedEntity`	`"related_entity"`
`ContentType`	`"content_type"`
`SortField`	`"sort_field"`

Note: Any meta data entities with a key of RelatedEntity will not be stored in the database as an event_meta item and instead will be stored as a seperate property under related_entities.

`RelatedEntityMetaDataType`

An enum used to specify the type of the type field in meta data that uses related entities, these are suggested values and aren't validate on, any string value can be passed through here.

Name	Value
`MT4`	`"MT4"`
`GT13`	`"GT13"`
`ADSSAlias`	`"ADSSAlias"`
`EODSymbol`	`"EODSymbol"`
`NetDania`	`"NetDania"`
`deeplink`	`"deeplink"`
`ASID`	`"ASID"`

Example use case:

new EventCapture.Component({
    type: "button",
    id: "btnOne",
    elementTree: "mainWrapper/sectionRight/btnOne"
});

`EventDetail`

An enum used in the ResearchEventRequest and ReactionEventRequest models. This property is supplementary to the provided action type.

Name	Value
`Add`	`"add"`
`Remove`	`"remove"`
`Create`	`"create"`
`Delete`	`"delete"`
`Modify`	`"modify"`
`Ascending`	`"ascending"`
`Descending`	`"descending"`
`Open`	`"open"`
`Close`	`"close"`

`EventType`

An enum used to specify the type of custom event.

Name	Value
`Load`	`"pageload"`
`Click`	`"click"`
`Recommendation`	`"recommendation"`
`Notification`	`"notification"`
`Entity`	`"entity"`
`Topic`	`"topic"`
`Content`	`"content"`
`Search`	`"search"`
`Filter`	`"filter"`
`Research`	`"research"`
`Authentication`	`"authentication"`
`Transaction`	`"transaction"`
`Trade`	`"trade"`
`Reaction`	`"reaction"`

Events Requests

All event request models will be listed below followed by the event action enums.

Request Models

`AuthenticationEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`eventAction`	`AuthenticationAction`
`metaData`	`Array<MetaData>`

`ClickEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`eventAction`	`ClickAction` or `string`		☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

`ContentEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`eventAction`	`ContentAction` or `string`		☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

`CustomEventRequest`

Name	Type	Notes
`event`	`any`	The javascript `Event` object that fired the event.
`eventType`	`EventType`
`eventAction`	`any`
`eventDetail`	`EventDetail`
`component`	`Component`
`metaData`	`Array<MetaData>`

`EntityEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`eventAction`	`ContentAction` or `string`		☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

`FilterEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`eventAction`	`FilterAction`		☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

`LoadEventRequest`

Name	Type	Notes	Required
`url`	`string`	Page url of the load event.	☑️
`eventAction`	`LoadAction`
`metaData`	`Array<MetaData>`

`NotifictionEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

`ReactionEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`eventDetail`	`EventDetail`		☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

`RecomendationEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

`ResearchEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`eventAction`	`ResearchAction`		☑️
`eventDetail`	`EventDetail`		☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

`SearchEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`eventAction`	`SearchAction`		☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

`TopicEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

`TradeEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`eventAction`	`TradeAction`		☑️
`eventDetail`	`EventDetail`
`component`	`Component`
`metaData`	`Array<MetaData>`

`TransactionEventRequest`

Name	Type	Notes	Required
`event`	`any`	The javascript `Event` object that fired the event.	☑️
`eventAction`	`TransactionAction`		☑️
`component`	`Component`
`metaData`	`Array<MetaData>`

Event Actions

`AuthenticationAction`

Name	Value
`SignIn`	`"sign_in"`
`SignOut`	`"sign_out"`
`SignUp`	`"sign_up"`

`ClickAction`

Name	Value
`Entity`	`"entity"`

`ContentAction`

Name	Value
`Expand`	`"expand"`
`Shrink`	`"shrink"`
`FollowUrl`	`"follow_url"`
`EnteredView`	`"entered_view"`
`SeeMore`	`"see_more"`
`SeeLess`	`"see_less"`
`Select`	`"select"`

`FilterAction`

Name	Value
`Applied`	`"applied"`

`LoadAction`

Name	Value
`Load`	`"load"`
`Paged`	`"paged"`
`TabSelected`	`"tab_selected"`

`ReactionAction`

Name	Value
`Like`	`"like"`
`Favourite`	`"favourite"`
`Comment`	`"comment"`
`Basket`	`"basket"`
`Watchlist`	`"watchlist"`

`ResearchAction`

Name	Value
`Indicator`	`"indicator"`
`AdjustView`	`"adjust_view"`
`Filter`	`"filter"`
`DateSelect`	`"date_select"`
`SortView`	`"sort_view"`

`SearchAction`

Name	Value
`Applied`	`"applied"`
`Result`	`"result"`
`Filter`	`"filter"`
`Sort`	`"sort"`
`Selected`	`"selected"`
`FocusOn`	`"focus_on"`
`FocusAway`	`"focus_away"`
`Close`	`"close"`

`TradeAction`

Name	Value
`BuyMarket`	`"buy_market"`
`BuyLimit`	`"buy_limit"`
`BuyStop`	`"buy_stop"`
`SellMarket`	`"sell_market"`
`SellLimit`	`"sell_limit"`
`SellStop`	`"sell_stop"`

`TransactionAction`

Name	Value
`Withdraw`	`"withdraw"`
`Deposit`	`"deposit"`
`Buy`	`"buy"`
`Sell`	`"sell"`

Firing Events

All of the available events that can be fired, are listed as follows

Function	Request Model	Notes
`authentication`	`AuthenticationEventRequest`	Passing the `eventAction` as `AuthenticationAction.SignOut` will set the `clientRef` as `null`
`basket`	`ReactionEventRequest`
`click`	`ClickEventRequest`
`comment`	`ReactionEventRequest`
`content`	`ContentEventRequest`
`custom`	`CustomEventRequest`
`entity`	`EntityEventRequest`
`favourite`	`ReactionEventRequest`
`filter`	`FilterEventRequest`
`like`	`ReactionEventRequest`
`load`	`LoadEventRequest`
`notification`	`NotifictionEventRequest`
`recommendation`	`RecomendationEventRequest`
`research`	`ResearchEventRequest`
`search`	`SearchEventRequest`
`topic`	`TopicEventRequest`
`trade`	`TradeEventRequest`
`transaction`	`TransactionEventRequest`
`watchlist`	`ReactionEventRequest`

An example click event:

click(new EventCapture.ClickEventRequest{
    event: new PointerEvent(),
    eventAction: EventCapture.ClickAction.Entity,
    component: new EventCapture.Component({
        type: "button",
        id: "btnOne",
        elementTree: "mainWrapper/btnOne"
    }),
    metaData: [
        new EventCapture.MetaData({
            key: MetaDataKey.RelatedEntity,
            type: 'entity',
            value: "678901"
        }),
        new EventCapture.MetaData({
            key: MetaDataKey.EntityId,
            value: "123456"
        });
    ]
});

as-event-tracker

Introduction

Getting Started

Set Up

Initialisation

ClientChannelMeta

Custom Logging

Logger

LogLevel

User Set Up

Request Entities

Component

MetaData

MetaDataKey

RelatedEntityMetaDataType

EventDetail

EventType

Events Requests

Request Models

AuthenticationEventRequest

ClickEventRequest

ContentEventRequest

CustomEventRequest

EntityEventRequest

FilterEventRequest

LoadEventRequest

NotifictionEventRequest

ReactionEventRequest

RecomendationEventRequest

ResearchEventRequest

SearchEventRequest

TopicEventRequest

TradeEventRequest

TransactionEventRequest

Event Actions

AuthenticationAction

ClickAction

ContentAction

FilterAction

LoadAction

ReactionAction

ResearchAction

SearchAction

TradeAction

TransactionAction