@xylabs/pixel

Event Client for xylabs ESB

Install

Using npm:

npm install {{name}}

Using yarn:

yarn add {{name}}

Using pnpm:

pnpm add {{name}}

Using bun:

bun add {{name}}

License

See the LICENSE file for license rights and limitations (LGPL-3.0-only).

Reference

packages

pixel

### .temp-typedoc

  ### classes

    ### <a id="PixelApi"></a>PixelApi

@xylabs/pixel

HTTP client for sending tracking events to the XY Labs pixel API.

Constructors

Constructor

new PixelApi(baseUri?): PixelApi;

Parameters

baseUri?

string = 'prod'

Returns

PixelApi

Methods

trackEvents()

trackEvents(events): Promise<any>;

Sends an array of user events to the tracking API.

Parameters

events

UserEvent[]

The events to submit

Returns

Promise<any>

The response data from the API

    ### <a id="Referrer"></a>Referrer

@xylabs/pixel

Tracks and persists the document referrer in both session and local storage.

Constructors

Constructor

new Referrer(): Referrer;

Returns

Referrer

Properties

local

local: string;

session

session: string;

Methods

toJson()

toJson(): 
  | {
  local: string;
  session: string;
}
  | undefined;

Returns the referrer data as a JSON object, or undefined if both values are empty.

Returns

| { local: string; session: string; } | undefined

An object with local and session referrer strings, or undefined

    ### <a id="UniqueUserId"></a>UniqueUserId

@xylabs/pixel

Generates and persists a unique user identifier in localStorage.

Constructors

Constructor

new UniqueUserId(): UniqueUserId;

Returns

UniqueUserId

Properties

id

id: string;

Methods

toString()

toString(): string;

Returns the unique user ID as a string.

Returns

string

    ### <a id="UserEventHandler"></a>UserEventHandler

@xylabs/pixel

Abstract base class for handling user tracking events.

Extended by

• XyUserEventHandler

Type Parameters

TData

TData extends EmptyObject

Constructors

Constructor

new UserEventHandler<TData>(): UserEventHandler<TData>;

Returns

UserEventHandler<TData>

Methods

funnelStarted()

abstract funnelStarted<T>(fields): Promisable<void>;

Tracks a funnel-started event.

Type Parameters

T

T extends object

Parameters

fields

FunnelStartedFields | T

Returns

Promisable<void>

testStarted()

abstract testStarted<T>(fields): Promisable<void>;

Tracks a test-started event.

Type Parameters

T

T extends object

Parameters

fields

TestStartedFields | T

Returns

Promisable<void>

userClick()

abstract userClick<T>(fields): Promisable<void>;

Tracks a user click event.

Type Parameters

T

T extends object

Parameters

fields

UserClickFields | T

Returns

Promisable<void>

viewContent()

abstract viewContent<T>(fields): Promisable<void>;

Tracks a view-content event.

Type Parameters

T

T extends object

Parameters

fields

T | ViewContentFields

Returns

Promisable<void>

    ### <a id="UtmFields"></a>UtmFields

@xylabs/pixel

Tracks UTM campaign parameters from query strings, persisting history in localStorage.

Constructors

Constructor

new UtmFields(): UtmFields;

Returns

UtmFields

Properties

fields

fields: Record<string, string>[] = [];

Methods

getUtmRecord()

getUtmRecord(): Record<string, string> | null;

Parses UTM parameters from the current URL query string.

Returns

Record<string, string> | null

A record of UTM key-value pairs, or null if none are present

toString()

toString(): string;

Returns the UTM fields history as a JSON string.

Returns

string

update()

update(): Record<string, string>[];

Checks the query string for new UTM values and appends them to the history if changed.

Returns

Record<string, string>[]

The current UTM fields array, or undefined if empty

    ### <a id="XyPixel"></a>XyPixel

@xylabs/pixel

Singleton pixel tracker that queues and sends user events to the XY Labs tracking API.

Properties

api

static api: PixelApi;

cid

cid: string;

email?

optional email?: string;

email_hash?

optional email_hash?: string | null;

exids?

optional exids?: ExIds;

pixelId?

optional pixelId?: string;

queue

queue: UserEvent[] = [];

Accessors

instance

Get Signature

get static instance(): XyPixel;

Returns the singleton XyPixel instance, throwing if not yet initialized.

Returns

XyPixel

Methods

init()

static init(pixelId): XyPixel;

Initializes the XyPixel singleton with the given pixel ID.

Parameters

pixelId

string

The pixel identifier for this tracking instance

Returns

XyPixel

The newly created XyPixel instance

selectApi()

static selectApi(api): void;

Replaces the default PixelApi instance used for sending events.

Parameters

api

PixelApi

The PixelApi instance to use

Returns

void

identify()

identify(email?): void;

Associates an email address with this pixel instance, hashing it for privacy.

Parameters

email?

string

The email address to identify the user with

Returns

void

send()

send<T>(
   event, 
   fields?, 
eventId?): Promise<void>;

Queues a tracking event and attempts to flush the queue to the API.

Type Parameters

T

T extends Record<string, unknown>

Parameters

event

string

The event name

fields?

T

Optional event-specific fields

eventId?

string

Optional unique event identifier

Returns

Promise<void>

    ### <a id="XyUserEventHandler"></a>XyUserEventHandler

@xylabs/pixel

Concrete event handler that sends tracking events through the XyPixel singleton.

Extends

• UserEventHandler<T>

Type Parameters

T

T extends EmptyObject = EmptyObject

Constructors

Constructor

new XyUserEventHandler<T>(): XyUserEventHandler<T>;

Returns

XyUserEventHandler<T>

Overrides

UserEventHandler.constructor

Methods

funnelStarted()

funnelStarted(fields): Promise<void>;

Sends a funnel-started event via the pixel API.

Parameters

fields

FunnelStartedFields | T

Returns

Promise<void>

Overrides

UserEventHandler.funnelStarted

purchase()

purchase(fields): Promise<void>;

Sends a purchase event via the pixel API.

Parameters

fields

PurchaseFields | T

Returns

Promise<void>

testStarted()

testStarted(fields): Promise<void>;

Sends a test-started event via the pixel API.

Parameters

fields

TestStartedFields | T

Returns

Promise<void>

Overrides

UserEventHandler.testStarted

userClick()

userClick(fields): Promise<void>;

Sends a user click event via the pixel API.

Parameters

fields

UserClickFields | T

Returns

Promise<void>

Overrides

UserEventHandler.userClick

viewContent()

viewContent(fields): Promise<void>;

Sends a view-content event via the pixel API.

Parameters

fields

ViewContentFields | T

Returns

Promise<void>

Overrides

UserEventHandler.viewContent

  ### interfaces

    ### <a id="CommonFields"></a>CommonFields

@xylabs/pixel

Common fields shared across all tracking event types.

Extended by

• FunnelStartedFields
• PurchaseFields
• TestStartedFields
• UserClickFields
• ViewContentFields

Properties

funnel?

optional funnel?: string;

testData?

optional testData?: string;

    ### <a id="FunnelStartedFields"></a>FunnelStartedFields

@xylabs/pixel

Fields for a funnel-started tracking event.

Extends

• CommonFields

Properties

funnel?

optional funnel?: string;

Inherited from

CommonFields.funnel

testData?

optional testData?: string;

Inherited from

CommonFields.testData

name

name: string;

    ### <a id="PurchaseFields"></a>PurchaseFields

@xylabs/pixel

Fields for a purchase tracking event.

Extends

• CommonFields

Properties

funnel?

optional funnel?: string;

Inherited from

CommonFields.funnel

testData?

optional testData?: string;

Inherited from

CommonFields.testData

id

id: string;

name?

optional name?: string;

price?

optional price?: number;

value?

optional value?: number;

    ### <a id="TestStartedFields"></a>TestStartedFields

@xylabs/pixel

Fields for a test-started tracking event (e.g. A/B test).

Extends

• CommonFields

Properties

funnel?

optional funnel?: string;

Inherited from

CommonFields.funnel

testData?

optional testData?: string;

Inherited from

CommonFields.testData

name

name: string;

    ### <a id="UserClickFields"></a>UserClickFields

@xylabs/pixel

Fields for a user click tracking event.

Extends

• CommonFields

Properties

funnel?

optional funnel?: string;

Inherited from

CommonFields.funnel

testData?

optional testData?: string;

Inherited from

CommonFields.testData

elementName

elementName: string;

elementType

elementType: string;

intent?

optional intent?: string;

placement?

optional placement?: string;

    ### <a id="UserEvent"></a>UserEvent

@xylabs/pixel

Represents a single user tracking event to be sent to the pixel API.

Properties

cid

cid: string;

create_time?

optional create_time?: number;

email?

optional email?: string;

email_hash?

optional email_hash?: string;

event?

optional event?: string;

event_id?

optional event_id?: string;

exids?

optional exids?: ExIds;

fields?

optional fields?: Record<string, unknown>;

host?

optional host?: string;

pathname?

optional pathname?: string;

pixel?

optional pixel?: string;

receive_time?

optional receive_time?: number;

referrer?

optional referrer?: object;

local

local: string;

session

session: string;

rid?

optional rid?: string;

system?

optional system?: ParsedResult;

uid?

optional uid?: string;

utm?

optional utm?: Record<string, string>[] | Record<string, string[]>;

    ### <a id="ViewContentFields"></a>ViewContentFields

@xylabs/pixel

Fields for a view-content tracking event.

Extends

• CommonFields

Properties

funnel?

optional funnel?: string;

Inherited from

CommonFields.funnel

testData?

optional testData?: string;

Inherited from

CommonFields.testData

name

name: string;

path

path: string;

    ### <a id="XyLabsTrackingEventJson"></a>XyLabsTrackingEventJson

@xylabs/pixel

JSON structure for an XY Labs tracking event as stored or transmitted.

Properties

cid

cid: string;

create_time?

optional create_time?: number;

email?

optional email?: string;

email_hash?

optional email_hash?: string;

event?

optional event?: string;

event_id?

optional event_id?: string;

exids?

optional exids?: Record<string, string>;

fields?

optional fields?: Record<string, unknown>;

host?

optional host?: string;

ip?

optional ip?: string;

pathname?

optional pathname?: string;

pixel?

optional pixel?: string;

receive_time?

optional receive_time?: number;

rid?

optional rid?: string;

system?

optional system?: unknown;

ua?

optional ua?: string;

uid?

optional uid?: string;

utm?

optional utm?: Record<string, string>[] | Record<string, string[]>;

  ### type-aliases

    ### <a id="UserEventSystem"></a>UserEventSystem

@xylabs/pixel

type UserEventSystem = Bowser.Parser.ParsedResult;

Parsed browser/OS/engine information from the user agent string.