Introduction

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

Getting Started

To use the application, simply run npm i pfai-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://behaviour-capture-receiver-serverless.azurewebsites.net/api/wbc_listener?code=G892JaeoDZD-Yif114Xn-EblkciSKfA3dBWDRFHdDDe7AzFu2d7M0Q==', // nullable
    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. Does not need to be provided as it defaults to https://behaviour-capture-receiver-serverless.azurewebsites.net/api/wbc_listener?code=G892JaeoDZD-Yif114Xn-EblkciSKfA3dBWDRFHdDDe7AzFu2d7M0Q==. | | | 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 | Notes | Required | |--------------|-----------|------------|------------|------------| | 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 identifier used to identify users on a clients application, however, care should be taken to avoid sending sensitive or personal information.

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 | Default | 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 | Default | Notes | Required | |--------------|-----------|------------|------------|------------| | event | any | | The javascript Event object that fired the event. | ☑️ | | eventAction | AuthenticationAction | | | | | metaData | Array<MetaData> | | | |

ClickEventRequest

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

ContentEventRequest

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

CustomEventRequest

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

EntityEventRequest

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

FilterEventRequest

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

LoadEventRequest

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

NotifictionEventRequest

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

ReactionEventRequest

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

RecomendationEventRequest

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

ResearchEventRequest

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

SearchEventRequest

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

TopicEventRequest

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

TradeEventRequest

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

TransactionEventRequest

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