Send events

Depending on your implementation you can use one of the code examples here for getting started with tracking custom events.

Web SDK

import UserFlux from '@userflux/browser-js'

await UserFlux.track({
    event: 'purchase',
    properties: { 
        "amount": 99.50,
        "currency": "AUD",
        "orderId": "order-id",
        "productId": "product-id",
        "fees": {
            "cardSurcharge": 0.99
        }
    },
    userId: '<USER_ID>' // replace <USER_ID> with your user's unique identifier
})

React SDK

import { useUserFlux } from "@userflux/browser-js-react"

const userFlux = useUserFlux()

await userFlux.track({
    event: 'purchase',
    properties: { 
        "amount": 99.50,
        "currency": "AUD",
        "orderId": "order-id",
        "productId": "product-id",
        "fees": {
            "cardSurcharge": 0.99
        }
    },
    userId: '<USER_ID>' // replace <USER_ID> with your user's unique identifier
})

Backend JS SDK

import UserFlux from '@userflux/backend-js'

const ufClient = new UserFlux('<YOUR_WRITE_KEY>', { ... })

await ufClient.track({
    userId: '<USER_ID>', // replace <USER_ID> with your user's unique identifier
    event: 'purchase',
    properties: { 
        "amount": 99.50,
        "currency": "AUD",
        "orderId": "order-id",
        "productId": "product-id",
        "fees": {
            "cardSurcharge": 0.99
        }
    }
})

API

Events API

---

Best Practices

1. Start with Auto Capture on your frontend

We recommend starting with Auto Capture in your web app. Auto Capture records clicks, page views and more—no manual instrumentation required. This gives you immediate coverage and a baseline for insights.

2. Instrument Custom Events

Once Auto Capture is in place, add custom events to track your product’s critical actions:

• Signup flows

• Feature uses

• Purchases or upgrades

Use either the SDK or API to fire these events wherever they occur in your code.

3. Include properties on an event

We recommend providing as much context to an event as possible. Including more properties will help you filter, segment and analyse insights better later on.

There's no limit on the number properties an event can have and complex data types such as Arrays and Nested Objects are supported.

4. Follow Consistent Naming Conventions

Adopt clear, predictable event names. Event names do not support white spaces and should follow a common casing pattern such as TileCase, camelCase, or snake_case.

5. Sending events from the Client vs. Backend

We recommend sending high‑volume UI interactions client‑side. You should send critical, transactional events (e.g. payment succeeded) from your backend.

Backend‑side

• Reliability: immune to ad‑blockers, network drop‑outs

• Rich context: enrich with up‑to‑date database values

Client‑side

• User context: captures browser/device details

• Low overhead: instant capture of UI interactions

6. Understanding Ingestion Time

For transactional processes such as Workflows and Profile State Evaluations, data is ingested and available immediately.

For analytical processes such as queries and reporting, UserFlux is still generally very fast in terms of the time from event request sent to being available.

For analytical data availability, latency varies by throughput:

• Low volume (<1k events/sec): available in ~30 seconds

• High volume (≥1k events/sec): available in ~3  seconds