@ariestools/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
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]#../interfaces/UserEvent
The events to submit
Returns
Promise<any>
The response data from the API
### <a id="Referrer"></a>Referrer
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
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
Abstract base class for handling user tracking events.
Extended by
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
Returns
Promisable<void>
testStarted()
abstract testStarted<T>(fields): Promisable<void>;
Tracks a test-started event.
Type Parameters
T
T extends object
Parameters
fields
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
Returns
Promisable<void>
### <a id="UtmFields"></a>UtmFields
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
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
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
Concrete event handler that sends tracking events through the XyPixel singleton.
Extends
Type Parameters
T
T extends EmptyObject = EmptyObject
Constructors
Constructor
new XyUserEventHandler<T>(): XyUserEventHandler<T>;
Returns
XyUserEventHandler<T>
Overrides
Methods
funnelStarted()
funnelStarted(fields): Promise<void>;
Sends a funnel-started event via the pixel API.
Parameters
fields
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
Returns
Promise<void>
Overrides
userClick()
userClick(fields): Promise<void>;
Sends a user click event via the pixel API.
Parameters
fields
UserClickFields | T
Returns
Promise<void>
Overrides
viewContent()
viewContent(fields): Promise<void>;
Sends a view-content event via the pixel API.
Parameters
fields
Returns
Promise<void>
Overrides
### interfaces
### <a id="CommonFields"></a>CommonFields
Common fields shared across all tracking event types.
Extended by
Properties
funnel?
optional funnel?: string;
testData?
optional testData?: string;
### <a id="FunnelStartedFields"></a>FunnelStartedFields
Fields for a funnel-started tracking event.
Extends
Properties
funnel?
optional funnel?: string;
Inherited from
testData?
optional testData?: string;
Inherited from
name
name: string;
### <a id="PurchaseFields"></a>PurchaseFields
Fields for a purchase tracking event.
Extends
Properties
funnel?
optional funnel?: string;
Inherited from
testData?
optional testData?: string;
Inherited from
id
id: string;
name?
optional name?: string;
price?
optional price?: number;
value?
optional value?: number;
### <a id="TestStartedFields"></a>TestStartedFields
Fields for a test-started tracking event (e.g. A/B test).
Extends
Properties
funnel?
optional funnel?: string;
Inherited from
testData?
optional testData?: string;
Inherited from
name
name: string;
### <a id="UserClickFields"></a>UserClickFields
Fields for a user click tracking event.
Extends
Properties
funnel?
optional funnel?: string;
Inherited from
testData?
optional testData?: string;
Inherited from
elementName
elementName: string;
elementType
elementType: string;
intent?
optional intent?: string;
placement?
optional placement?: string;
### <a id="UserEvent"></a>UserEvent
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
Fields for a view-content tracking event.
Extends
Properties
funnel?
optional funnel?: string;
Inherited from
testData?
optional testData?: string;
Inherited from
name
name: string;
path
path: string;
### <a id="XyLabsTrackingEventJson"></a>XyLabsTrackingEventJson
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[]>;
### interfaces
### <a id="UserEventSystem"></a>UserEventSystem
interface UserEventSystem
Parsed browser/OS/engine information from the user agent string.
Properties
browser?
optional browser: UserEventSystemBrowser;
engine?
optional engine: UserEventSystemEngine;
os?
optional os: UserEventSystemOS;
platform?
optional platform: UserEventSystemPlatform;