API Specification

The Analytics framework offers several methods for both client-side and server-side operations. These methods provide a consistent way to track user behavior across your application.

Basic Tracking Methods

The basic tracking methods below serve as the building blocks of your Dreamdata tracking. They include Track, Page, Identify, Group, and Alias.

Track

The track method enables you to record individual events, such as user actions like signing up, downloading an e-book, or adding items to a shopping cart.

Method Signature

dreamdata.track(event, [properties], [options], [callback]);

Parameters

Field	Type	Required	Description
event	string	Yes	The name of the event you're tracking.
properties	object	No	A dictionary of properties for the event. If the event was "Product Added", it might have properties like price or product.
options	object	No	A dictionary of options, such as enabling or disabling specific destinations for the call.
callback	function	No	A function executed after a short timeout, giving the browser time to make outbound requests first.

Usage

To manually trigger a tracking event, use the following command:

dreamdata.track("Download e-book", {
  bookName: "How to use Dreamdata",
});

In this example, the event "Download e-book" is tracked with additional metadata specifying the book name.

You can also track events without properties:

dreamdata.track("User Signed Up");

Or with a callback to execute code after the event is sent:

dreamdata.track("Order Completed", { orderId: "12345" }, {}, () => {
  console.log("Event tracked successfully");
});

Page

The page method lets you record page views on your website, along with optional extra information about the page being viewed.

Method Signature

dreamdata.page([category], [name], [properties], [options], [callback]);

Parameters

Field	Type	Required	Description
category	string	No	The category of the page. Useful for grouping pages together (e.g., "Docs", "Product").
name	string	No	The name of the page (e.g., "Pricing", "About Us").
properties	object	No	A dictionary of properties of the page. By default, properties include url, title, referrer, etc.
options	object	No	A dictionary of options, such as enabling or disabling specific destinations for the call.
callback	function	No	A function executed after a short timeout, giving the browser time to make outbound requests first.

The Dreamdata analytics snippet automatically calls page once when the

script loads. For single-page applications (SPAs), you need to manually call page when routes change.

Usage

The simplest page call requires no arguments:

dreamdata.page();

This automatically collects the page URL, title, referrer, and other contextual information.

You can also specify a page name:

dreamdata.page("Pricing");

Or include both category and name:

dreamdata.page("Product", "Feature Overview");

You can add custom properties to the page call:

dreamdata.page("Docs", "API Reference", {
  section: "Client-side",
  version: "2.0",
});

Identify

The identify method is used to link your users and their actions to a recognizable userId and traits. Use this method when a user signs up, logs in, or updates their profile information.

Method Signature

dreamdata.identify([userId], [traits], [options], [callback]);

Parameters

Field	Type	Required	Description
userId	string	No	The database ID for the user. If you don't know who the user is yet, you can omit the userId and just record traits.
traits	object	No	A dictionary of traits you know about the user, like email or name.
options	object	No	A dictionary of options, such as enabling or disabling specific destinations for the call. Note: If you do not pass a traits object, pass an empty object ({}) before options.
callback	function	No	A function executed after a short timeout, giving the browser time to make outbound requests first.

Dreamdata automatically retrieves an anonymousId from localStorage

or assigns one for new visitors, and then attaches it to all Page and Track events both before and after an Identify call.

Usage

To identify a user with their ID and traits:

dreamdata.identify("5c684fbb-b00e-4f27-8709-c21734fbc90d", {
  email: "friends@dreamdata.io",
});

In this example, the user is identified by the ID 5c684fbb-b00e-4f27-8709-c21734fbc90d, and their email is specified as additional information.

You can also identify a user with just traits (without a userId):

dreamdata.identify({
  email: "visitor@example.com",
  plan: "free",
});

Or with more detailed traits when a user signs up:

dreamdata.identify("user-123", {
  name: "Jane Doe",
  email: "jane@example.com",
  company: "Acme Inc",
  plan: "enterprise",
  createdAt: "2024-01-15",
});

Group

The group method allows you to associate the current user with a group, typically representing an organization or company. This is useful for B2B applications where you want to track company-level analytics.

Method Signature

dreamdata.group([groupId], [traits], [options], [callback]);

Parameters

Field	Type	Required	Description
groupId	string	No	The unique identifier for the group (typically the company ID from your database).
traits	object	No	A dictionary of traits you know about the group, like name, industry, or employees.
options	object	No	A dictionary of options, such as enabling or disabling specific destinations for the call. Note: If you do not pass a traits object, pass an empty object ({}) before options.
callback	function	No	A function executed after a short timeout, giving the browser time to make outbound requests first.

Usage

To add group information, use the following command:

dreamdata.group("90577a70-57b2-4ce6-aa03-a9917a157fc2", {
  companyName: "Dreamdata",
});

Here, the user is associated with a group identified by the ID 90577a70-57b2-4ce6-aa03-a9917a157fc2, and additional information about the group (such as the company name) is provided.

In practice, this will most often be the company the user is associated with:

dreamdata.group("company-456", {
  name: "Acme Corporation",
  industry: "Technology",
  employees: 250,
  plan: "enterprise",
  website: "https://acme.com",
});

Alias

The alias method is used to merge two user identities, effectively connecting two sets of user data as the same person. This is useful when a user initially visits anonymously and later signs up or logs in.

Method Signature

dreamdata.alias(to, [from], [options], [callback]);

Parameters

Field	Type	Required	Description
to	string	Yes	The new user ID you want to associate with the user.
from	string	No	The previous ID that the user was recognized by. Defaults to the current anonymousId if not provided.
options	object	No	A dictionary of options, such as enabling or disabling specific destinations for the call.
callback	function	No	A function executed after a short timeout, giving the browser time to make outbound requests first.

Usage

Typically, you call alias when a user signs up or logs in for the first time:

// When user signs up, alias their anonymous ID to their new user ID
dreamdata.alias("new-user-id");

You can also explicitly specify both the new and old IDs:

dreamdata.alias("new-user-id", "previous-anonymous-id");

Utility Methods

These utility methods provide additional functionality for managing the analytics instance and debugging.

Ready

The ready method allows you to pass a callback that will be executed when all enabled destination plugins have loaded and analytics is fully initialized.

Method Signature

dreamdata.ready([callback]);

Parameters

Field	Type	Required	Description
callback	function	No	A function to be executed when analytics is ready.

Usage

dreamdata.ready(() => {
  console.log("Dreamdata Analytics is ready!");
  // You can now safely call analytics methods
});

Debug

The debug method enables or disables debug mode, which outputs detailed logs to the browser console. This is useful for troubleshooting your analytics implementation.

Method Signature

dreamdata.debug(toggle);

Parameters

Field	Type	Required	Description
toggle	boolean	Yes	true to enable debug mode, false to disable it.

Usage

Enable debug mode:

dreamdata.debug(true);

Disable debug mode:

dreamdata.debug(false);

You can also enable debug mode via localStorage by running this in your

browser console:

localStorage.setItem("DD_DEBUGGER", "true");

Then refresh the page to see debug logs.

Reset

The reset method clears the current user's identity (userId and traits) and group association. This is typically called when a user logs out of your application.

Method Signature

dreamdata.reset();

Usage

// When user logs out
function handleLogout() {
  // Clear your app's session
  clearSession();

  // Reset analytics identity
  dreamdata.reset();

  // Redirect to login page
  window.location.href = "/login";
}

After calling reset, the user will be assigned a new anonymousId on their next visit.

Set Anonymous ID

The setAnonymousId method allows you to manually set the anonymousId for the current user. This is useful when you want to maintain identity across different platforms or migrate from another analytics tool.

Method Signature

dreamdata.setAnonymousId(id);

Parameters

Field	Type	Required	Description
id	string	No	The anonymous ID to set. If not provided, returns the current ID.

Usage

Set a custom anonymous ID:

dreamdata.setAnonymousId("custom-anonymous-id-12345");

User

The user method returns the current user object, which contains the user's ID, anonymous ID, and traits.

Method Signature

dreamdata.user();

Usage

Access user information:

const user = dreamdata.user();
console.log(user.id()); // Current user ID
console.log(user.anonymousId()); // Anonymous ID
console.log(user.traits()); // User traits object

Auto-tracking Methods

These methods help you automatically track user interactions with links and forms without writing custom event handlers.

Track Link

The trackLink method (also available as trackClick) tracks clicks on a link or array of links. When a link is clicked, a track call is fired, and the browser is directed to the link's href.

Method Signature

dreamdata.trackLink(elements, event, [properties]);

Parameters

Field	Type	Required	Description
elements	Element | Element[]	Yes	The link element(s) to track. Can be a single DOM element or an array of elements.
event	string | function	Yes	The name of the event to track, or a function that returns the event name based on the clicked element.
properties	object | function	No	A dictionary of properties to include with the event, or a function that returns properties based on the clicked element.

Usage

Track clicks on a single link:

const link = document.getElementById("signup-link");
dreamdata.trackLink(link, "Clicked Signup");

Track clicks on multiple links with dynamic properties:

const links = document.querySelectorAll(".product-link");
dreamdata.trackLink(links, "Product Clicked", (el) => ({
  productId: el.dataset.productId,
  productName: el.textContent,
}));

Track Form

The trackForm method (also available as trackSubmit) tracks form submissions. When a form is submitted, a track call is fired, and the form submission continues normally.

Method Signature

dreamdata.trackForm(elements, event, [properties]);

Parameters

Field	Type	Required	Description
elements	Element | Element[]	Yes	The form element(s) to track. Can be a single DOM element or an array of elements.
event	string | function	Yes	The name of the event to track, or a function that returns the event name based on the submitted form.
properties	object | function	No	A dictionary of properties to include with the event, or a function that returns properties based on the submitted form.

Usage

Track submissions on a signup form:

const form = document.getElementById("signup-form");
dreamdata.trackForm(form, "Form Submitted", {
  formName: "Signup",
});

Track multiple forms with dynamic event names:

const forms = document.querySelectorAll("form");
dreamdata.trackForm(
  forms,
  (form) => `${form.id} Submitted`,
  (form) => ({
    formId: form.id,
    formAction: form.action,
  }),
);

The trackLink and trackForm methods ensure that the tracking call is

sent before the browser navigates away or submits the form. This prevents data loss that can occur with standard event handlers.