📈 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!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
fix: Correct usage examples
Blue Mousee0c61ce23221
diff --git a/packages/tracker-js/README.md b/packages/tracker-js/README.mdindex 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 cacheclearFeatureFlagsCache()```### 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 cacheclearExperimentsCache()```diff --git a/packages/tracker-js/src/Lib.ts b/packages/tracker-js/src/Lib.tsindex 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 flowdiff --git a/packages/tracker-js/src/index.ts b/packages/tracker-js/src/index.tsindex 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