Track events

Page views, signed-in customers, and the ecommerce events that feed analytics and ad-platform conversions

On this page

• Page views
• Identify a customer
• Track an action
• Ecommerce events
• Purchase
• Sign out
• Groups
• Count each order once
• What the SDK adds for you

All examples call sfere, the global the loader creates. With the npm package, call the same methods on the instance SfereAnalytics.load() returns.

Page views#

The loader sends the first page view. On a single-page app, send one on every route change, because the SDK does not detect route changes itself:

JavaScript

sfere.page();                                  // URL, path, title and referrer are filled in
sfere.page("Product", { sku: "sku_221" });     // optional name and properties

Identify a customer#

Call identify when a customer signs in or registers. Send email and phone as plain values: Sfere hashes them for each destination, so never hash them yourself.

JavaScript

sfere.identify("user_1234", {
  email: "customer@example.com",
  phone: "+15555550123",
  first_name: "Sara",
});

Traits are kept for the visitor and copied onto every later event, so server-side destinations can match on them.

Track an action#

JavaScript

sfere.track("add_to_cart", {
  currency: "USD",
  value: 149,
  items: [{ item_id: "sku_221", item_name: "Linen Shirt", price: 149, quantity: 1 }],
});

Ecommerce events#

Use GA4 event names in snake_case. Any other name is accepted too and forwarded as-is.

Event	When to send it	Required properties
view_item_list	A product list is viewed	items
select_item	A product is clicked in a list	items
view_item	A product page is viewed	currency, value, items
add_to_cart	A product is added to the cart	currency, value, items
remove_from_cart	A product is removed from the cart	currency, value, items
add_to_wishlist	A product is saved to a wishlist	currency, value, items
view_cart	The cart is viewed	currency, value, items
begin_checkout	Checkout starts	currency, value, items
add_shipping_info	A shipping method is chosen	currency, value, items
add_payment_info	Payment details are entered	currency, value, items
purchase	An order is completed	transaction_id, currency, value, items
refund	An order is refunded	transaction_id, currency, value
search	A site search is submitted	search_term
sign_up	An account is created	none (method is optional)
login	A customer signs in	none (method is optional)
generate_lead	A lead form is submitted	none

Rules that keep data clean:

• currency is an ISO 4217 code such as USD, EUR or GBP, and is required whenever value is set.
• value is a number, not a string.
• Every item needs item_id or item_name. Other item fields: price, quantity, item_brand, item_category to item_category5, item_variant, coupon, discount, index.

Purchase#

If your server also reports the purchase, see Count each order once.

JavaScript

sfere.track("purchase", {
  transaction_id: "order_98765",
  currency: "USD",
  value: 313,
  tax: 39,
  shipping: 25,
  items: [
    { item_id: "sku_221", item_name: "Linen Shirt", price: 149, quantity: 1, item_category: "Apparel" },
    { item_id: "sku_305", item_name: "Canvas Tote", price: 100, quantity: 1, item_category: "Accessories" },
  ],
});

Sign out#

Clear the customer’s ID and traits when they sign out, so the next visitor on the same browser starts fresh:

JavaScript

sfere.reset();

Groups#

Link a customer to an account or company, for example in a B2B store:

JavaScript

sfere.group("company_42", { name: "Acme Trading", plan: "wholesale" });

Count each order once#

When a browser pixel and a server-side destination both report the same conversion, the ad platform counts it once only if both carry the same event ID and event name. Sfere’s server-side destinations use the event’s messageId. Once the SDK has loaded, track() resolves to the sent event, so you can hand that ID to the pixel:

JavaScript

const sent = await sfere.track("generate_lead", { form_type: "demo" });
const eventId = sent.event.messageId;

fbq("track", "Lead", {}, { eventID: eventId });   // Meta
ttq.track("Lead", {}, { event_id: eventId });      // TikTok

In Google Tag Manager, push eventId to the dataLayer and read it in the pixel tags with a Data Layer Variable.

What the SDK adds for you#

Each event automatically carries the page URL and title, a session ID, the customer’s traits after identify, consent categories when set, and ad-platform click IDs from the landing URL and cookies (for example gclid, fbclid, ttclid). Click IDs in the landing URL are kept for the rest of the session.