Skip to content

📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

fix: Correct usage examples

Blue Mousee0c61ce23221
diff --git a/packages/tracker-js/README.md b/packages/tracker-js/README.md
index 620fcc85f..51c28452d 100644
--- a/packages/tracker-js/README.md
+++ b/packages/tracker-js/README.md
@@ -110,6 +110,7 @@ track({
ev: 'signup',
unique: true,
meta: { plan: 'pro', source: 'landing' },
+ profileId: 'user-123',
})
```
@@ -118,6 +119,7 @@ track({
| `ev` | Event name (max 256 chars). | **required** |
| `unique` | Only count once per session. | `false` |
| `meta` | Key-value metadata (max 20 keys, 1000 chars total). | `{}` |
+| `profileId` | Optional profile ID. Overrides the global `profileId` for this event. | `undefined` |
### `trackErrors(options?)`
@@ -161,26 +163,34 @@ pageview({
### Feature Flags
```javascript
-// Get all flags
+// Get all flags. Results are cached for 5 minutes.
const flags = await getFeatureFlags({ profileId: 'user-123' })
-// Get a single flag
+// Force a fresh fetch
+const freshFlags = await getFeatureFlags({ profileId: 'user-123' }, true)
+
+// Get a single flag. The third argument is an optional fallback value.
const enabled = await getFeatureFlag('dark-mode', { profileId: 'user-123' })
+const enabledWithFallback = await getFeatureFlag('dark-mode', { profileId: 'user-123' }, false)
-// Clear cache
+// Clear the shared feature flag / experiment cache
clearFeatureFlagsCache()
```
### A/B Experiments
```javascript
-// Get all experiments
+// Get all running experiment assignments. Results are cached for 5 minutes.
const experiments = await getExperiments({ profileId: 'user-123' })
-// Get a specific experiment variant
-const variant = await getExperiment('checkout-redesign', { profileId: 'user-123' })
+// Force a fresh fetch
+const freshExperiments = await getExperiments({ profileId: 'user-123' }, true)
+
+// Get a specific experiment variant. The third argument is an optional fallback variant.
+const variant = await getExperiment('checkout-redesign-experiment-id', { profileId: 'user-123' })
+const variantWithFallback = await getExperiment('checkout-redesign-experiment-id', { profileId: 'user-123' }, 'control')
-// Clear cache
+// Clear the shared feature flag / experiment cache
clearExperimentsCache()
```
diff --git a/packages/tracker-js/src/Lib.ts b/packages/tracker-js/src/Lib.ts
index 7d78eb013..253a0d968 100644
--- a/packages/tracker-js/src/Lib.ts
+++ b/packages/tracker-js/src/Lib.ts
@@ -431,10 +431,10 @@ export class Lib {
}
/**
- * Fetches all feature flags and experiments for the project.
- * Results are cached for 5 minutes by default.
+ * Fetches all feature flags for the project.
+ * Results are cached for 5 minutes by default and share a cache with experiments.
*
- * @param options - Options for evaluating feature flags.
+ * @param options - Options for evaluating feature flags (`profileId` only).
* @param forceRefresh - If true, bypasses the cache and fetches fresh data.
* @returns A promise that resolves to a record of flag keys to boolean values.
*/
@@ -512,8 +512,8 @@ export class Lib {
* Gets the value of a single feature flag.
*
* @param key - The feature flag key.
- * @param options - Options for evaluating the feature flag.
- * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+ * @param options - Options for evaluating the feature flag (`profileId` only).
+ * @param defaultValue - Optional default value to return if the flag is not found. Defaults to false.
* @returns A promise that resolves to the boolean value of the flag.
*/
async getFeatureFlag(key: string, options?: FeatureFlagsOptions, defaultValue: boolean = false): Promise<boolean> {
@@ -529,16 +529,16 @@ export class Lib {
}
/**
- * Fetches all A/B test experiments for the project.
+ * Fetches variant assignments for running A/B test experiments returned by feature flag evaluation.
* Results are cached for 5 minutes by default (shared cache with feature flags).
*
- * @param options - Options for evaluating experiments.
+ * @param options - Options for evaluating experiments (`profileId` only).
* @param forceRefresh - If true, bypasses the cache and fetches fresh data.
* @returns A promise that resolves to a record of experiment IDs to variant keys.
*
* @example
* ```typescript
- * const experiments = await getExperiments()
+ * const experiments = await getExperiments({ profileId: 'user-123' })
* // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
* ```
*/
@@ -571,13 +571,16 @@ export class Lib {
* Gets the variant key for a specific A/B test experiment.
*
* @param experimentId - The experiment ID.
- * @param options - Options for evaluating the experiment.
- * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+ * @param options - Options for evaluating the experiment (`profileId` only).
+ * @param defaultVariant - Optional default variant key to return if the experiment is not found. Defaults to null.
* @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
*
* @example
* ```typescript
- * const variant = await getExperiment('checkout-redesign')
+ * const variant = await getExperiment('checkout-redesign', { profileId: 'user-123' })
+ *
+ * // Optional fallback variant:
+ * const variantWithFallback = await getExperiment('checkout-redesign', undefined, 'control')
*
* if (variant === 'new-checkout') {
* // Show new checkout flow
diff --git a/packages/tracker-js/src/index.ts b/packages/tracker-js/src/index.ts
index 1b5c1958c..e6a84964a 100644
--- a/packages/tracker-js/src/index.ts
+++ b/packages/tracker-js/src/index.ts
@@ -124,17 +124,16 @@ export function pageview(options: IPageviewOptions): void {
/**
* Fetches all feature flags for the project.
- * Results are cached for 5 minutes by default.
+ * Results are cached for 5 minutes by default and share a cache with experiments.
*
- * @param options - Options for evaluating feature flags (visitorId, attributes).
+ * @param options - Options for evaluating feature flags (`profileId` only).
* @param forceRefresh - If true, bypasses the cache and fetches fresh flags.
* @returns A promise that resolves to a record of flag keys to boolean values.
*
* @example
* ```typescript
* const flags = await getFeatureFlags({
- * visitorId: 'user-123',
- * attributes: { cc: 'US', dv: 'desktop' }
+ * profileId: 'user-123'
* })
*
* if (flags['new-checkout']) {
@@ -155,13 +154,13 @@ export async function getFeatureFlags(
* Gets the value of a single feature flag.
*
* @param key - The feature flag key.
- * @param options - Options for evaluating the feature flag (visitorId, attributes).
- * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+ * @param options - Options for evaluating the feature flag (`profileId` only).
+ * @param defaultValue - Optional default value to return if the flag is not found. Defaults to false.
* @returns A promise that resolves to the boolean value of the flag.
*
* @example
* ```typescript
- * const isEnabled = await getFeatureFlag('dark-mode', { visitorId: 'user-123' })
+ * const isEnabled = await getFeatureFlag('dark-mode', { profileId: 'user-123' })
*
* if (isEnabled) {
* // Enable dark mode
@@ -179,8 +178,8 @@ export async function getFeatureFlag(
}
/**
- * Clears the cached feature flags, forcing a fresh fetch on the next call.
- * Useful when you know the user's context has changed significantly.
+ * Clears the cached feature flags and experiments, forcing a fresh fetch on the next call.
+ * Useful when you know the user's profile has changed.
*/
export function clearFeatureFlagsCache(): void {
if (!LIB_INSTANCE) return
@@ -189,10 +188,10 @@ export function clearFeatureFlagsCache(): void {
}
/**
- * Fetches all A/B test experiments for the project.
+ * Fetches variant assignments for running A/B test experiments returned by feature flag evaluation.
* Results are cached for 5 minutes by default (shared cache with feature flags).
*
- * @param options - Options for evaluating experiments.
+ * @param options - Options for evaluating experiments (`profileId` only).
* @param forceRefresh - If true, bypasses the cache and fetches fresh data.
* @returns A promise that resolves to a record of experiment IDs to variant keys.
*
@@ -223,13 +222,16 @@ export async function getExperiments(
* Gets the variant key for a specific A/B test experiment.
*
* @param experimentId - The experiment ID.
- * @param options - Options for evaluating the experiment.
- * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+ * @param options - Options for evaluating the experiment (`profileId` only).
+ * @param defaultVariant - Optional default variant key to return if the experiment is not found. Defaults to null.
* @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
*
* @example
* ```typescript
- * const variant = await getExperiment('checkout-redesign-experiment-id')
+ * const variant = await getExperiment('checkout-redesign-experiment-id', { profileId: 'user-123' })
+ *
+ * // Optional fallback variant:
+ * const variantWithFallback = await getExperiment('checkout-redesign-experiment-id', undefined, 'control')
*
* if (variant === 'new-checkout') {
* // Show new checkout flow