Pixel API Reference

The Datahappy JavaScript SDK, also known as the Pixel, provides a simple API for tracking events and managing user identity and consent from your website’s frontend.

The datahappy.init() method is asynchronous. It kicks off the process of fetching your configuration and getting the SDK ready. All subsequent API calls (like page or track) are safely queued and will be processed in order once initialisation is complete.You can wait for the SDK to be fully loaded using await datahappy.init() or by using the global datahappy.ready.then() handler. This is only necessary if you need to access SDK properties, like the datahappy.Event constants, immediately after initialisation.

Methods

`init()`

Initialises the SDK. This should be the first method called to ensure the SDK is configured correctly. The installation snippet calls this for you.

datahappy.init(projectId, [options])

projectId

string

required

Your unique project identifier, provided during onboarding.

options

Object

An object containing initial identity or configuration overrides.

Show options

userId

string

Set the user’s ID if they are already logged in.

traits

Object

A dictionary of user traits.

debug

boolean

default:"false"

Set to true to enable verbose logging in the console.

`page()`

Tracks a page view. The installation snippet calls this once on initial page load. For Single-Page Applications (SPAs), you must call this method again after each route change.

datahappy.page([params])

params

Object

An object containing a properties key, which can be used to send custom properties with the page view and to override any automatically captured page data (e.g. page_title, page_url).

`track()`

Tracks a custom event.

datahappy.track(event)

event

Object

required

An object containing the event details.

Show event

event

string

required

The name of the event.

properties

Object

A dictionary of properties for the event.

userId

string

A user ID to associate with the event.

traits

Object

A dictionary of user traits to update. The SDK will update the user’s profile before sending the event.

`updateIdentity()`

Updates the current visitor’s identity profile.

datahappy.updateIdentity(identity)

identity

Object

required

An object containing the identity fields to update.

Show identity

userId

string

The user’s unique identifier.

traits

Object

A dictionary of traits.

`getIdentity()`

Returns the current identity stored in the SDK (anonymousId, userId, traits).

const identity = datahappy.getIdentity()

`updateConsent()`

Updates the visitor’s consent preferences. If you are using a custom consent solution, you must call this method on every page load to ensure the SDK is initialised with the correct consent state.

datahappy.updateConsent(consent)

An object where keys are consent categories (e.g. advertising, analytics) and values are booleans.

`getConsent()`

Returns the current consent state stored in the SDK.

const consent = datahappy.getConsent()

`reset()`

Resets the current user’s identity. This is an asynchronous operation that clears the userId and traits and generates a new anonymousId. It is useful for “log out” functionality.

await datahappy.reset()

Data Reference: The Datahappy Schema

This is a reference for the standard events, properties and traits that Datahappy recognises natively. Using this schema where possible helps us automatically map your data to downstream integrations.

Standard Events

We provide a set of standard event names via the datahappy.Event object. It’s recommended to use these where applicable.

Object Key	Event Name (string)	Description
`LEAD_FORM_COMPLETED`	`lead_form_completed`	A user submitted a form to express interest.
`SIGNUP_COMPLETED`	`signup_completed`	A user created an account.
`USER_LOGGED_IN`	`user_logged_in`	A user logged in to their account.
`SEARCH_PERFORMED`	`search_performed`	A user performed a search.
`ITEM_LIST_VIEWED`	`item_list_viewed`	A user viewed a list of items (e.g. a product category page).
`ITEM_VIEWED`	`item_viewed`	A user viewed a specific item.
`ITEM_ADDED`	`item_added`	A user added an item to their cart.
`CHECKOUT_STARTED`	`checkout_started`	A user started the checkout process.
`PAYMENT_INFO_ADDED`	`payment_info_added`	A user submitted their payment information.
`PURCHASE_COMPLETED`	`purchase_completed`	A user completed a purchase.
`TRIAL_STARTED`	`trial_started`	A user started a free trial.
`SUBSCRIPTION_STARTED`	`subscription_started`	A user started a paid subscription.
`SUBSCRIPTION_CANCELLED`	`subscription_cancelled`	A user cancelled their subscription.

Event Properties

Name	Type	Description
`value`	Float	A monetary value associated with an event e.g. revenue
`currency`	String	The currency of the transaction e.g. “USD”
`transaction_id`	String	A unique ID for the transaction.
`subscription_id`	String	A unique ID for the subscription. Only set here if you’re not passing an `items` array.
`coupon`	String	Optional. Discount code that was used.
`shipping`	Float	Optional. Cost of shipping.
`tax`	Float	Optional. Value added tax.
`delivery_category`	String	Optional. e.g. “home_delivery”.
`items`	Array	A list of items related to the event. See below for item properties.

Item Properties

Name	Type	Description
`item_id`	String	Unique identifier for the item being purchased.
`item_name`	String	Human-readable name of the item.
`is_subscription`	Boolean	Indicates whether the item is a subscription or not.
`subscription_id`	String	Unique identifier for the subscription.
`affiliation`	String	Store or business affiliation from where the item originates.
`coupon`	String	Code for any discount coupon applied.
`discount`	Float	Monetary discount applied to the item’s price.
`index`	Integer	Position index of the item, often used in a list or cart.
`item_brand`	String	Brand of the item.
`item_category`	String	Category to which the item belongs.
`item_list_id`	String	Identifier for the list in which the item appears.
`item_list_name`	String	Human-readable name of the list in which the item appears.
`item_variant`	String	Specifies the variant of the item (e.g. colour, size).
`location_id`	String	Identifier for the store location from where the item was purchased.
`price`	Float	Price of a single unit of the item.
`quantity`	Integer	Number of units of the item being purchased.

User Traits

Name	Type	Description
`firstName`	String	First name of a user.
`lastName`	String	Last name of a user.
`name`	String	Full name of a user. If you only pass a first and last name, Datahappy automatically fills in the full name for you.
`email`	String	Email address of a user.
`phone`	String	Phone number of a user.
`title`	String	Title of a user, usually related to their position at a specific company. Example: “VP of Engineering”.
`companyName`	String	Company the user represents.
`company`	Object	Company the user represents, optionally containing: `name` (String), `id` (String or Number), `industry` (String), `employeeCount` (Number) and `plan` (String).
`address`	Object	Street address of a user optionally containing: `street`, `city`, `region`, `state`, `postalCode`, `country` & `countryCode` (ISO 3166-1 alpha-2 standard).
`gender`	String	Gender of a user.
`birthday`	Date	User’s birthday.
`website`	String	Website of a user.
`message`	String	A message from the user e.g. for lead capture.
`description`	String	Description of the user.
`createdAt`	String	Date the user’s account was first created. datahappy recommends using ISO-8101 date strings. If not set datahappy will set to the date the event is triggered.

Pixel API

​Methods

​init()

​page()

​track()

​updateIdentity()

​getIdentity()

​updateConsent()

​getConsent()

​reset()

​Data Reference: The Datahappy Schema

​Standard Events

​Event Properties

​Item Properties

​User Traits

Methods

`init()`

`page()`

`track()`

`updateIdentity()`

`getIdentity()`

`updateConsent()`

`getConsent()`

`reset()`

Data Reference: The Datahappy Schema

Standard Events

Event Properties

Item Properties

User Traits