@xylabs/pixel

Event Client for xylabs ESB

Reference

@xylabs/pixel

Classes

| Class | Description | | ------ | ------ | | PixelApi | HTTP client for sending tracking events to the XY Labs pixel API. | | XyPixel | Singleton pixel tracker that queues and sends user events to the XY Labs tracking API. | | Referrer | Tracks and persists the document referrer in both session and local storage. | | UniqueUserId | Generates and persists a unique user identifier in localStorage. | | UserEventHandler | Abstract base class for handling user tracking events. | | UtmFields | Tracks UTM campaign parameters from query strings, persisting history in localStorage. | | XyUserEventHandler | Concrete event handler that sends tracking events through the XyPixel singleton. |

Interfaces

| Interface | Description | | ------ | ------ | | UserEvent | Represents a single user tracking event to be sent to the pixel API. | | CommonFields | Common fields shared across all tracking event types. | | FunnelStartedFields | Fields for a funnel-started tracking event. | | PurchaseFields | Fields for a purchase tracking event. | | TestStartedFields | Fields for a test-started tracking event (e.g. A/B test). | | UserClickFields | Fields for a user click tracking event. | | ViewContentFields | Fields for a view-content tracking event. | | XyLabsTrackingEventJson | JSON structure for an XY Labs tracking event as stored or transmitted. |

Type Aliases

| Type Alias | Description | | ------ | ------ | | UserEventSystem | Parsed browser/OS/engine information from the user agent string. |

classes

PixelApi

@xylabs/pixel

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

Constructors

Constructor

new PixelApi(baseUri?: string): PixelApi;

Parameters

| Parameter | Type | Default value | | ------ | ------ | ------ | | baseUri | string | 'prod' |

Returns

PixelApi

Methods

trackEvents()

trackEvents(events: UserEvent[]): Promise<any>;

Sends an array of user events to the tracking API.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | events | UserEvent[] | The events to submit |

Returns

Promise<any>

The response data from the API

Referrer

@xylabs/pixel

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

Constructors

Constructor

new Referrer(): Referrer;

Returns

Referrer

Properties

| Property | Type | | ------ | ------ | | local | string | | 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

UniqueUserId

@xylabs/pixel

Generates and persists a unique user identifier in localStorage.

Constructors

Constructor

new UniqueUserId(): UniqueUserId;

Returns

UniqueUserId

Properties

| Property | Type | | ------ | ------ | | id | string |

Methods

toString()

toString(): string;

Returns the unique user ID as a string.

Returns

string

UserEventHandler

@xylabs/pixel

Abstract base class for handling user tracking events.

Extended by

• XyUserEventHandler

Type Parameters

| Type Parameter | | ------ | | TData extends EmptyObject |

Constructors

Constructor

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

Returns

UserEventHandler<TData>

Methods

funnelStarted()

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

Tracks a funnel-started event.

Type Parameters

| Type Parameter | | ------ | | T extends object |

Parameters

| Parameter | Type | | ------ | ------ | | fields | FunnelStartedFields | T |

Returns

Promisable<void>

testStarted()

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

Tracks a test-started event.

Type Parameters

| Type Parameter | | ------ | | T extends object |

Parameters

| Parameter | Type | | ------ | ------ | | fields | TestStartedFields | T |

Returns

Promisable<void>

userClick()

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

Tracks a user click event.

Type Parameters

| Type Parameter | | ------ | | T extends object |

Parameters

| Parameter | Type | | ------ | ------ | | fields | UserClickFields | T |

Returns

Promisable<void>

viewContent()

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

Tracks a view-content event.

Type Parameters

| Type Parameter | | ------ | | T extends object |

Parameters

| Parameter | Type | | ------ | ------ | | fields | T | ViewContentFields |

Returns

Promisable<void>

UtmFields

@xylabs/pixel

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

Constructors

Constructor

new UtmFields(): UtmFields;

Returns

UtmFields

Properties

| Property | Type | Default value | | ------ | ------ | ------ | | 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

XyPixel

@xylabs/pixel

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

Properties

| Property | Modifier | Type | Default value | | ------ | ------ | ------ | ------ | | api | static | PixelApi | undefined | | cid | public | string | undefined | | email? | public | string | undefined | | email_hash? | public | string | null | undefined | | exids? | public | ExIds | undefined | | pixelId? | public | string | undefined | | queue | public | 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: string): XyPixel;

Initializes the XyPixel singleton with the given pixel ID.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | pixelId | string | The pixel identifier for this tracking instance |

Returns

XyPixel

The newly created XyPixel instance

selectApi()

static selectApi(api: PixelApi): void;

Replaces the default PixelApi instance used for sending events.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | api | PixelApi | The PixelApi instance to use |

Returns

void

identify()

identify(email?: string): void;

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

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | email? | string | The email address to identify the user with |

Returns

void

send()

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

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

Type Parameters

| Type Parameter | | ------ | | T extends Record<string, unknown> |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | event | string | The event name | | fields? | T | Optional event-specific fields | | eventId? | string | Optional unique event identifier |

Returns

Promise<void>

XyUserEventHandler

@xylabs/pixel

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

Extends

• UserEventHandler<T>

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T extends EmptyObject | EmptyObject |

Constructors

Constructor

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

Returns

XyUserEventHandler<T>

Overrides

UserEventHandler.constructor

Methods

funnelStarted()

funnelStarted(fields: FunnelStartedFields | T): Promise<void>;

Sends a funnel-started event via the pixel API.

Parameters

| Parameter | Type | | ------ | ------ | | fields | FunnelStartedFields | T |

Returns

Promise<void>

Overrides

UserEventHandler.funnelStarted

purchase()

purchase(fields: PurchaseFields | T): Promise<void>;

Sends a purchase event via the pixel API.

Parameters

| Parameter | Type | | ------ | ------ | | fields | PurchaseFields | T |

Returns

Promise<void>

testStarted()

testStarted(fields: TestStartedFields | T): Promise<void>;

Sends a test-started event via the pixel API.

Parameters

| Parameter | Type | | ------ | ------ | | fields | TestStartedFields | T |

Returns

Promise<void>

Overrides

UserEventHandler.testStarted

userClick()

userClick(fields: UserClickFields | T): Promise<void>;

Sends a user click event via the pixel API.

Parameters

| Parameter | Type | | ------ | ------ | | fields | UserClickFields | T |

Returns

Promise<void>

Overrides

UserEventHandler.userClick

viewContent()

viewContent(fields: ViewContentFields | T): Promise<void>;

Sends a view-content event via the pixel API.

Parameters

| Parameter | Type | | ------ | ------ | | fields | ViewContentFields | T |

Returns

Promise<void>

Overrides

UserEventHandler.viewContent

interfaces

CommonFields

@xylabs/pixel

Common fields shared across all tracking event types.

Extended by

• FunnelStartedFields
• PurchaseFields
• TestStartedFields
• UserClickFields
• ViewContentFields

Properties

| Property | Type | | ------ | ------ | | funnel? | string | | testData? | string |

FunnelStartedFields

@xylabs/pixel

Fields for a funnel-started tracking event.

Extends

• CommonFields

Properties

| Property | Type | Inherited from | | ------ | ------ | ------ | | funnel? | string | CommonFields.funnel | | testData? | string | CommonFields.testData | | name | string | - |

PurchaseFields

@xylabs/pixel

Fields for a purchase tracking event.

Extends

• CommonFields

Properties

| Property | Type | Inherited from | | ------ | ------ | ------ | | funnel? | string | CommonFields.funnel | | testData? | string | CommonFields.testData | | id | string | - | | name? | string | - | | price? | number | - | | value? | number | - |

TestStartedFields

@xylabs/pixel

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

Extends

• CommonFields

Properties

| Property | Type | Inherited from | | ------ | ------ | ------ | | funnel? | string | CommonFields.funnel | | testData? | string | CommonFields.testData | | name | string | - |

UserClickFields

@xylabs/pixel

Fields for a user click tracking event.

Extends

• CommonFields

Properties

| Property | Type | Inherited from | | ------ | ------ | ------ | | funnel? | string | CommonFields.funnel | | testData? | string | CommonFields.testData | | elementName | string | - | | elementType | string | - | | intent? | string | - | | placement? | string | - |

UserEvent

@xylabs/pixel

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

Properties

| Property | Type | | ------ | ------ | | cid | string | | create_time? | number | | email? | string | | email_hash? | string | | event? | string | | event_id? | string | | exids? | ExIds | | fields? | Record<string, unknown> | | host? | string | | pathname? | string | | pixel? | string | | receive_time? | number | | referrer? | { local: string; session: string; } | | referrer.local | string | | referrer.session | string | | rid? | string | | system? | ParsedResult | | uid? | string | | utm? | Record<string, string>[] | Record<string, string[]> |

ViewContentFields

@xylabs/pixel

Fields for a view-content tracking event.

Extends

• CommonFields

Properties

| Property | Type | Inherited from | | ------ | ------ | ------ | | funnel? | string | CommonFields.funnel | | testData? | string | CommonFields.testData | | name | string | - | | path | string | - |

XyLabsTrackingEventJson

@xylabs/pixel

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

Properties

| Property | Type | | ------ | ------ | | cid | string | | create_time? | number | | email? | string | | email_hash? | string | | event? | string | | event_id? | string | | exids? | Record<string, string> | | fields? | Record<string, unknown> | | host? | string | | ip? | string | | pathname? | string | | pixel? | string | | receive_time? | number | | rid? | string | | system? | unknown | | ua? | string | | uid? | string | | utm? | Record<string, string>[] | Record<string, string[]> |

type-aliases

UserEventSystem

@xylabs/pixel

type UserEventSystem = Bowser.Parser.ParsedResult;

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

Part of sdk-js

Maintainers

• Arie Trouw (arietrouw.com)
• Matt Jones
• Joel Carter
• Jordan Trouw

License

See the LICENSE file for license details

Credits

Made with 🔥 and ❄️ by XYLabs