as-event-tracker v1.1.1

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:

ClientChannelMeta

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

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:

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:

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:

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.

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

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

Firing Events

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

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"
        });
    ]
});