mytart 0.6.0 → 0.6.2

package/README.md

@@ -6,11 +6,13 @@
 
 ## Features
 
-- 🔌 **7 providers out of the box**: Google Analytics 4, Mixpanel, Segment, Amplitude, Plausible, PostHog, Meta Pixel
+- 🔌 **8 providers out of the box**: Google Analytics 4, Mixpanel, Segment, Amplitude, Plausible, PostHog, Meta Pixel, Microsoft Clarity
 - 🌐 **Universal**: works in Node.js, browsers, and any JS framework (Next.js, Remix, Astro, SvelteKit, etc.)
 - 🔷 **TypeScript-first**: precise typings, object-parameter style for great DX
 - 📦 **Dual ESM/CJS output**: works with `import` and `require`
 - 🪶 **Lightweight**: direct HTTP via axios, no SDK overhead
+- 🤖 **Bot filtering**: optionally ignore bots and crawlers via [ua-parser-js](https://github.com/nicolevanderhoeven/ua-parser-js)
+- 🔗 **Cross-provider linking**: auto-captures click IDs (`gclid`, `fbclid`, `msclkid`, etc.) and cookies, then injects them into every provider call for unified attribution
 - ✅ **Node.js ≥ 18**
 
 ## Installation
@@ -253,6 +255,123 @@ await provider.updatePixelConsent(true);   // fbq('consent', 'grant')
 await provider.updatePixelConsent(false);  // fbq('consent', 'revoke')
 ```
 
+### Microsoft Clarity
+
+[Microsoft Clarity](https://clarity.microsoft.com/) is a free behavioral analytics tool that provides session recordings, heatmaps, and insights. Clarity is **browser-only** — there is no server mode.
+
+```typescript
+{
+  provider: 'clarity',
+  projectId: 'YOUR_PROJECT_ID',
+  enabled: true,
+}
+```
+
+When enabled:
+
+- The official `https://www.clarity.ms/tag/{projectId}` script is loaded once on the first `track()`, `identify()`, or `page()` call
+- `track()` fires `clarity('event', eventName)` and sets each property as a custom tag via `clarity('set', key, value)`
+- `identify()` calls `clarity('identify', userId)` with an optional friendly name from `traits.name`, and sets remaining traits as custom tags
+- `page()` fires a `PageView` event and sets `pageUrl`, `pageName`, and `referrer` as custom tags
+- SSR-safe: silently succeeds when `window` is undefined
+
+#### Cookie consent
+
+By default Clarity operates in cookieless mode. To enable cookie-based tracking, set `cookie: true`:
+
+```typescript
+{
+  provider: 'clarity',
+  projectId: 'YOUR_PROJECT_ID',
+  cookie: true,
+  enabled: true,
+}
+```
+
+This calls `clarity('consent')` during initialisation so Clarity can set cookies for more accurate session tracking.
+
+## Bot Filtering
+
+Set `ignoreBots: true` at the top level to silently drop all `track()`, `identify()`, and `page()` calls when the visitor is a known bot or crawler. Detection is powered by [`ua-parser-js`](https://github.com/nicolevanderhoeven/ua-parser-js)'s `isBot()` function.
+
+```typescript
+const analytics = new Mytart({
+  ignoreBots: true,
+  providers: [
+    { provider: 'google-analytics', measurementId: 'G-XXXXXXXXXX', enabled: true },
+    { provider: 'segment', writeKey: 'YOUR_KEY', enabled: true },
+  ],
+});
+```
+
+When a bot is detected, all methods return an empty `TrackResult[]` array — no events are dispatched to any provider.
+
+The User-Agent is read from:
+
+1. `context.userAgent` if supplied in the `track()` call
+2. `navigator.userAgent` in browser environments
+
+If no User-Agent is available (e.g. server-side without `context.userAgent`), the call proceeds normally.
+
+## Cross-Provider Linking
+
+Set `crossProviderLinking: true` to automatically capture click IDs and analytics cookies, then inject them as `xpl_`-prefixed properties into every `track()`, `page()`, and `identify()` call. This lets you correlate events across providers — e.g. trace a Meta ad click through to a Clarity session recording or a Mixpanel funnel.
+
+```typescript
+const analytics = new Mytart({
+  crossProviderLinking: true,
+  providers: [
+    { provider: 'google-analytics', measurementId: 'G-XXXXXXXXXX', appType: 'browser', enabled: true },
+    { provider: 'meta-pixel', pixelId: '123456789', appType: 'browser', enabled: true },
+    { provider: 'clarity', projectId: 'YOUR_PROJECT_ID', enabled: true },
+    { provider: 'mixpanel', token: 'YOUR_TOKEN', enabled: true },
+  ],
+});
+```
+
+### What gets captured
+
+| Source | Captured ID | Property key |
+|---|---|---|
+| `?gclid=` URL param | Google click ID | `xpl_gclid` |
+| `?fbclid=` URL param | Meta click ID | `xpl_fbclid` |
+| `?ttclid=` URL param | TikTok click ID | `xpl_ttclid` |
+| `?msclkid=` URL param | Microsoft Ads click ID | `xpl_msclkid` |
+| `?li_fat_id=` URL param | LinkedIn click ID | `xpl_li_fat_id` |
+| `_fbp` cookie | Meta browser ID | `xpl_fbp` |
+| `_fbc` cookie | Meta click ID cookie | `xpl_fbc` |
+| `_ga` cookie | GA client ID | `xpl_ga_client_id` |
+
+If `fbclid` is present in the URL but the `_fbc` cookie has not yet been set, mytart synthesises an `fbc` value in Meta's standard format (`fb.1.{timestamp}.{fbclid}`).
+
+### How it flows to each provider
+
+All captured IDs are injected as event properties (`track`/`page`) or user traits (`identify`). No provider code changes are needed — each provider already forwards properties to its API:
+
+- **GA4** — `xpl_*` fields appear as event parameters and user properties (queryable in BigQuery exports)
+- **Meta Pixel** — `xpl_*` fields become custom data parameters (`fbclid`/`_fbp`/`_fbc` are also handled natively by Meta)
+- **Clarity** — `xpl_*` fields are set as custom tags, letting you filter session recordings by ad click source
+- **Mixpanel / Amplitude / PostHog** — `xpl_*` fields become event and user properties, fully queryable
+- **Segment** — `xpl_*` fields flow through to all downstream destinations in your Segment pipeline
+- **Plausible** — `xpl_*` fields are sent as custom props (must be [registered in your Plausible dashboard](https://plausible.io/docs/custom-props/introduction) to appear in reports)
+
+### Inspecting captured IDs
+
+Use `getCapturedIds()` to see what was captured at construction time:
+
+```typescript
+const ids = analytics.getCapturedIds();
+// { fbclid: 'abc123', fbc: 'fb.1.1234567890.abc123', gaClientId: '1234567890.1234567890' }
+```
+
+Returns `null` when `crossProviderLinking` is disabled.
+
+### Notes
+
+- **Browser-only.** SSR-safe — returns empty results when `window` is undefined.
+- **User properties take precedence.** If you pass a property with the same `xpl_*` key, your value wins.
+- **Consent.** This feature reads existing URL parameters and cookies — it does not set new cookies or tracking identifiers. Each provider's own consent mechanism remains authoritative.
+
 ## API Reference
 
 ### `new Mytart(config: MytartConfig)`
@@ -263,6 +382,8 @@ interface MytartConfig {
   defaultUserId?: string;      // applied to every track/page call if no userId given
   defaultAnonymousId?: string; // applied to every track/page call if no anonymousId given
   debug?: boolean;
+  ignoreBots?: boolean;          // when true, silently drops all tracking calls from known bots/crawlers
+  crossProviderLinking?: boolean; // when true, auto-captures click IDs & cookies and injects them into every call
 }
 ```
 
@@ -373,7 +494,7 @@ import type {
   TrackResult, MytartError, EventContext, ProviderName, GoogleAnalyticsAppType,
   GoogleAnalyticsConfig, ConsentSettings, ConsentState, MixpanelConfig, SegmentConfig,
   AmplitudeConfig, PlausibleConfig, PostHogConfig, MetaPixelConfig, MetaPixelAppType,
-  MetaPixelAdvancedMatching,
+  MetaPixelAdvancedMatching, ClarityConfig,
 } from 'mytart';
 ```
 

package/dist/index.d.mts

@@ -197,6 +197,32 @@ interface MytartConfig {
     defaultUserId?: string;
     defaultAnonymousId?: string;
     debug?: boolean;
+    /**
+     * When `true`, silently drops all `track`, `identify`, and `page` calls
+     * if the visitor's User-Agent belongs to a known bot or crawler.
+     *
+     * Detection uses `isBot()` from `ua-parser-js`. The User-Agent is read
+     * from `context.userAgent` (if supplied) or `navigator.userAgent` in
+     * browser environments.
+     *
+     * Defaults to `false` (bots are tracked like any other visitor).
+     */
+    ignoreBots?: boolean;
+    /**
+     * When `true`, automatically captures click IDs from URL parameters
+     * (`gclid`, `fbclid`, `ttclid`, `msclkid`, `li_fat_id`) and analytics
+     * cookies (`_fbp`, `_fbc`, `_ga`) at construction time, then injects
+     * them as `xpl_`-prefixed properties into every `track()`, `page()`,
+     * and `identify()` call.
+     *
+     * This enables cross-provider attribution — e.g. linking a Meta ad
+     * click to a Clarity session recording or a Mixpanel event — without
+     * any manual wiring.
+     *
+     * Browser-only. SSR-safe (no-op when `window` is undefined).
+     * Defaults to `false`.
+     */
+    crossProviderLinking?: boolean;
 }
 interface EventContext {
     ip?: string;
@@ -245,10 +271,46 @@ interface MytartError {
     originalError?: unknown;
 }
 
+/**
+ * Cross-provider identity linking.
+ *
+ * Captures click IDs from URL parameters and analytics cookies in the
+ * browser, then converts them into a flat property map that can be
+ * injected into every provider call.
+ *
+ * Browser-only — returns empty results when `window` is undefined.
+ */
+/** Identifiers captured from URL parameters and cookies. */
+interface CapturedIds {
+    /** Google click ID (`gclid` URL param) */
+    gclid?: string;
+    /** Meta/Facebook click ID (`fbclid` URL param) */
+    fbclid?: string;
+    /** TikTok click ID (`ttclid` URL param) */
+    ttclid?: string;
+    /** Microsoft Ads click ID (`msclkid` URL param) */
+    msclkid?: string;
+    /** LinkedIn click ID (`li_fat_id` URL param) */
+    li_fat_id?: string;
+    /** Meta browser ID (from `_fbp` cookie) */
+    fbp?: string;
+    /** Meta click ID cookie (from `_fbc` cookie, or synthesised from `fbclid`) */
+    fbc?: string;
+    /** Google Analytics client ID (extracted from `_ga` cookie) */
+    gaClientId?: string;
+}
+
 declare class Mytart {
     private readonly providers;
     private readonly config;
+    private readonly capturedIds;
+    private readonly linkingProperties;
     constructor(config: MytartConfig);
+    /**
+     * Returns `true` when `ignoreBots` is enabled and the given (or detected)
+     * User-Agent belongs to a known bot or crawler.
+     */
+    private isBotRequest;
     track(options: TrackOptions): Promise<TrackResult[]>;
     identify(options: IdentifyOptions): Promise<TrackResult[]>;
     page(options: PageOptions): Promise<TrackResult[]>;
@@ -265,6 +327,11 @@ declare class Mytart {
     addProvider(config: ProviderConfig): void;
     removeProvider(name: string): void;
     getProviders(): string[];
+    /**
+     * Returns the click IDs and cookie values captured at construction
+     * time, or `null` when `crossProviderLinking` is disabled.
+     */
+    getCapturedIds(): CapturedIds | null;
 }
 
 declare abstract class BaseProvider {
@@ -510,4 +577,4 @@ declare class ClarityProvider extends BaseProvider {
     page(options: PageOptions): Promise<TrackResult>;
 }
 
-export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type ClarityConfig, ClarityProvider, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MetaPixelAdvancedMatching, type MetaPixelAppType, type MetaPixelConfig, MetaPixelProvider, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type CapturedIds, type ClarityConfig, ClarityProvider, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MetaPixelAdvancedMatching, type MetaPixelAppType, type MetaPixelConfig, MetaPixelProvider, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };

package/dist/index.d.ts

@@ -197,6 +197,32 @@ interface MytartConfig {
     defaultUserId?: string;
     defaultAnonymousId?: string;
     debug?: boolean;
+    /**
+     * When `true`, silently drops all `track`, `identify`, and `page` calls
+     * if the visitor's User-Agent belongs to a known bot or crawler.
+     *
+     * Detection uses `isBot()` from `ua-parser-js`. The User-Agent is read
+     * from `context.userAgent` (if supplied) or `navigator.userAgent` in
+     * browser environments.
+     *
+     * Defaults to `false` (bots are tracked like any other visitor).
+     */
+    ignoreBots?: boolean;
+    /**
+     * When `true`, automatically captures click IDs from URL parameters
+     * (`gclid`, `fbclid`, `ttclid`, `msclkid`, `li_fat_id`) and analytics
+     * cookies (`_fbp`, `_fbc`, `_ga`) at construction time, then injects
+     * them as `xpl_`-prefixed properties into every `track()`, `page()`,
+     * and `identify()` call.
+     *
+     * This enables cross-provider attribution — e.g. linking a Meta ad
+     * click to a Clarity session recording or a Mixpanel event — without
+     * any manual wiring.
+     *
+     * Browser-only. SSR-safe (no-op when `window` is undefined).
+     * Defaults to `false`.
+     */
+    crossProviderLinking?: boolean;
 }
 interface EventContext {
     ip?: string;
@@ -245,10 +271,46 @@ interface MytartError {
     originalError?: unknown;
 }
 
+/**
+ * Cross-provider identity linking.
+ *
+ * Captures click IDs from URL parameters and analytics cookies in the
+ * browser, then converts them into a flat property map that can be
+ * injected into every provider call.
+ *
+ * Browser-only — returns empty results when `window` is undefined.
+ */
+/** Identifiers captured from URL parameters and cookies. */
+interface CapturedIds {
+    /** Google click ID (`gclid` URL param) */
+    gclid?: string;
+    /** Meta/Facebook click ID (`fbclid` URL param) */
+    fbclid?: string;
+    /** TikTok click ID (`ttclid` URL param) */
+    ttclid?: string;
+    /** Microsoft Ads click ID (`msclkid` URL param) */
+    msclkid?: string;
+    /** LinkedIn click ID (`li_fat_id` URL param) */
+    li_fat_id?: string;
+    /** Meta browser ID (from `_fbp` cookie) */
+    fbp?: string;
+    /** Meta click ID cookie (from `_fbc` cookie, or synthesised from `fbclid`) */
+    fbc?: string;
+    /** Google Analytics client ID (extracted from `_ga` cookie) */
+    gaClientId?: string;
+}
+
 declare class Mytart {
     private readonly providers;
     private readonly config;
+    private readonly capturedIds;
+    private readonly linkingProperties;
     constructor(config: MytartConfig);
+    /**
+     * Returns `true` when `ignoreBots` is enabled and the given (or detected)
+     * User-Agent belongs to a known bot or crawler.
+     */
+    private isBotRequest;
     track(options: TrackOptions): Promise<TrackResult[]>;
     identify(options: IdentifyOptions): Promise<TrackResult[]>;
     page(options: PageOptions): Promise<TrackResult[]>;
@@ -265,6 +327,11 @@ declare class Mytart {
     addProvider(config: ProviderConfig): void;
     removeProvider(name: string): void;
     getProviders(): string[];
+    /**
+     * Returns the click IDs and cookie values captured at construction
+     * time, or `null` when `crossProviderLinking` is disabled.
+     */
+    getCapturedIds(): CapturedIds | null;
 }
 
 declare abstract class BaseProvider {
@@ -510,4 +577,4 @@ declare class ClarityProvider extends BaseProvider {
     page(options: PageOptions): Promise<TrackResult>;
 }
 
-export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type ClarityConfig, ClarityProvider, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MetaPixelAdvancedMatching, type MetaPixelAppType, type MetaPixelConfig, MetaPixelProvider, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type CapturedIds, type ClarityConfig, ClarityProvider, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MetaPixelAdvancedMatching, type MetaPixelAppType, type MetaPixelConfig, MetaPixelProvider, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };

package/dist/index.js

@@ -43,6 +43,68 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/mytart.ts
+var import_bot_detection = require("ua-parser-js/bot-detection");
+
+// src/utils/cross-provider-ids.ts
+var CLICK_ID_PARAMS = ["gclid", "fbclid", "ttclid", "msclkid", "li_fat_id"];
+function getCookie(name) {
+  if (typeof document === "undefined") return void 0;
+  const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+  return match ? decodeURIComponent(match[1]) : void 0;
+}
+function parseGaClientId(gaCookie) {
+  const parts = gaCookie.split(".");
+  if (parts.length < 4) return void 0;
+  return parts.slice(-2).join(".");
+}
+function captureClickIds() {
+  if (typeof window === "undefined") return {};
+  const ids = {};
+  const params = new URLSearchParams(window.location.search);
+  for (const key of CLICK_ID_PARAMS) {
+    const value = params.get(key);
+    if (value) {
+      ids[key] = value;
+    }
+  }
+  const fbp = getCookie("_fbp");
+  if (fbp) ids.fbp = fbp;
+  const fbc = getCookie("_fbc");
+  if (fbc) {
+    ids.fbc = fbc;
+  } else if (ids.fbclid) {
+    ids.fbc = `fb.1.${Date.now()}.${ids.fbclid}`;
+  }
+  const ga = getCookie("_ga");
+  if (ga) {
+    const clientId = parseGaClientId(ga);
+    if (clientId) ids.gaClientId = clientId;
+  }
+  return ids;
+}
+var PREFIX = "xpl_";
+var KEY_MAP = {
+  gclid: "gclid",
+  fbclid: "fbclid",
+  ttclid: "ttclid",
+  msclkid: "msclkid",
+  li_fat_id: "li_fat_id",
+  fbp: "fbp",
+  fbc: "fbc",
+  gaClientId: "ga_client_id"
+};
+function capturedIdsToProperties(ids) {
+  const props = {};
+  for (const [field, suffix] of Object.entries(KEY_MAP)) {
+    const value = ids[field];
+    if (value) {
+      props[`${PREFIX}${suffix}`] = value;
+    }
+  }
+  return props;
+}
+
 // src/providers/base.ts
 var BaseProvider = class {
   /**
@@ -1223,23 +1285,58 @@ var Mytart = class {
   constructor(config) {
     this.config = config;
     this.providers = config.providers.filter((c) => c.enabled === true).map(createProvider);
+    if (config.crossProviderLinking) {
+      this.capturedIds = captureClickIds();
+      const props = capturedIdsToProperties(this.capturedIds);
+      this.linkingProperties = Object.keys(props).length > 0 ? props : null;
+    } else {
+      this.capturedIds = null;
+      this.linkingProperties = null;
+    }
+  }
+  /**
+   * Returns `true` when `ignoreBots` is enabled and the given (or detected)
+   * User-Agent belongs to a known bot or crawler.
+   */
+  isBotRequest(userAgent) {
+    if (!this.config.ignoreBots) return false;
+    const ua = userAgent ?? (typeof navigator !== "undefined" ? navigator.userAgent : void 0);
+    return ua ? (0, import_bot_detection.isBot)(ua) : false;
   }
   async track(options) {
+    if (this.isBotRequest(options.context?.userAgent)) return [];
     const enriched = {
       userId: this.config.defaultUserId,
       anonymousId: this.config.defaultAnonymousId,
-      ...options
+      ...options,
+      properties: {
+        ...this.linkingProperties,
+        ...options.properties
+      }
     };
     return Promise.all(this.providers.map((p) => p.track(enriched)));
   }
   async identify(options) {
-    return Promise.all(this.providers.map((p) => p.identify(options)));
+    if (this.isBotRequest()) return [];
+    const enriched = {
+      ...options,
+      traits: {
+        ...this.linkingProperties,
+        ...options.traits
+      }
+    };
+    return Promise.all(this.providers.map((p) => p.identify(enriched)));
   }
   async page(options) {
+    if (this.isBotRequest()) return [];
     const enriched = {
       userId: this.config.defaultUserId,
       anonymousId: this.config.defaultAnonymousId,
-      ...options
+      ...options,
+      properties: {
+        ...this.linkingProperties,
+        ...options.properties
+      }
     };
     return Promise.all(this.providers.map((p) => p.page(enriched)));
   }
@@ -1268,6 +1365,13 @@ var Mytart = class {
   getProviders() {
     return this.providers.map((p) => p.name);
   }
+  /**
+   * Returns the click IDs and cookie values captured at construction
+   * time, or `null` when `crossProviderLinking` is disabled.
+   */
+  getCapturedIds() {
+    return this.capturedIds;
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -1,3 +1,65 @@
+// src/mytart.ts
+import { isBot } from "ua-parser-js/bot-detection";
+
+// src/utils/cross-provider-ids.ts
+var CLICK_ID_PARAMS = ["gclid", "fbclid", "ttclid", "msclkid", "li_fat_id"];
+function getCookie(name) {
+  if (typeof document === "undefined") return void 0;
+  const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+  return match ? decodeURIComponent(match[1]) : void 0;
+}
+function parseGaClientId(gaCookie) {
+  const parts = gaCookie.split(".");
+  if (parts.length < 4) return void 0;
+  return parts.slice(-2).join(".");
+}
+function captureClickIds() {
+  if (typeof window === "undefined") return {};
+  const ids = {};
+  const params = new URLSearchParams(window.location.search);
+  for (const key of CLICK_ID_PARAMS) {
+    const value = params.get(key);
+    if (value) {
+      ids[key] = value;
+    }
+  }
+  const fbp = getCookie("_fbp");
+  if (fbp) ids.fbp = fbp;
+  const fbc = getCookie("_fbc");
+  if (fbc) {
+    ids.fbc = fbc;
+  } else if (ids.fbclid) {
+    ids.fbc = `fb.1.${Date.now()}.${ids.fbclid}`;
+  }
+  const ga = getCookie("_ga");
+  if (ga) {
+    const clientId = parseGaClientId(ga);
+    if (clientId) ids.gaClientId = clientId;
+  }
+  return ids;
+}
+var PREFIX = "xpl_";
+var KEY_MAP = {
+  gclid: "gclid",
+  fbclid: "fbclid",
+  ttclid: "ttclid",
+  msclkid: "msclkid",
+  li_fat_id: "li_fat_id",
+  fbp: "fbp",
+  fbc: "fbc",
+  gaClientId: "ga_client_id"
+};
+function capturedIdsToProperties(ids) {
+  const props = {};
+  for (const [field, suffix] of Object.entries(KEY_MAP)) {
+    const value = ids[field];
+    if (value) {
+      props[`${PREFIX}${suffix}`] = value;
+    }
+  }
+  return props;
+}
+
 // src/providers/base.ts
 var BaseProvider = class {
   /**
@@ -1178,23 +1240,58 @@ var Mytart = class {
   constructor(config) {
     this.config = config;
     this.providers = config.providers.filter((c) => c.enabled === true).map(createProvider);
+    if (config.crossProviderLinking) {
+      this.capturedIds = captureClickIds();
+      const props = capturedIdsToProperties(this.capturedIds);
+      this.linkingProperties = Object.keys(props).length > 0 ? props : null;
+    } else {
+      this.capturedIds = null;
+      this.linkingProperties = null;
+    }
+  }
+  /**
+   * Returns `true` when `ignoreBots` is enabled and the given (or detected)
+   * User-Agent belongs to a known bot or crawler.
+   */
+  isBotRequest(userAgent) {
+    if (!this.config.ignoreBots) return false;
+    const ua = userAgent ?? (typeof navigator !== "undefined" ? navigator.userAgent : void 0);
+    return ua ? isBot(ua) : false;
   }
   async track(options) {
+    if (this.isBotRequest(options.context?.userAgent)) return [];
     const enriched = {
       userId: this.config.defaultUserId,
       anonymousId: this.config.defaultAnonymousId,
-      ...options
+      ...options,
+      properties: {
+        ...this.linkingProperties,
+        ...options.properties
+      }
     };
     return Promise.all(this.providers.map((p) => p.track(enriched)));
   }
   async identify(options) {
-    return Promise.all(this.providers.map((p) => p.identify(options)));
+    if (this.isBotRequest()) return [];
+    const enriched = {
+      ...options,
+      traits: {
+        ...this.linkingProperties,
+        ...options.traits
+      }
+    };
+    return Promise.all(this.providers.map((p) => p.identify(enriched)));
   }
   async page(options) {
+    if (this.isBotRequest()) return [];
     const enriched = {
       userId: this.config.defaultUserId,
       anonymousId: this.config.defaultAnonymousId,
-      ...options
+      ...options,
+      properties: {
+        ...this.linkingProperties,
+        ...options.properties
+      }
     };
     return Promise.all(this.providers.map((p) => p.page(enriched)));
   }
@@ -1223,6 +1320,13 @@ var Mytart = class {
   getProviders() {
     return this.providers.map((p) => p.name);
   }
+  /**
+   * Returns the click IDs and cookie values captured at construction
+   * time, or `null` when `crossProviderLinking` is disabled.
+   */
+  getCapturedIds() {
+    return this.capturedIds;
+  }
 };
 export {
   AmplitudeProvider,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mytart",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Multi-Yield Tracking & Analytics Relay Tool — framework-agnostic analytics for any project",
   "keywords": [
     "analytics",
@@ -35,7 +35,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "axios": "^1.7.0"
+    "axios": "^1.7.0",
+    "ua-parser-js": "^2.0.9"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",