Implementation:Helicone Helicone Attribution Tracking

Knowledge Sources	Helicone
Domains	Analytics, Marketing, Frontend
Last Updated	2026-02-14 06:32 GMT

Overview

A first-touch marketing attribution module that captures UTM parameters and Google Click IDs from URLs and stores them in localStorage for analytics integration.

Description

The attribution module implements a first-touch attribution model for tracking which marketing campaigns drive user signups. On the first visit where attribution parameters are present, it captures gclid (Google Click ID), utm_source, utm_medium, utm_campaign, utm_term, and utm_content from the URL query string, along with the landing page path and capture timestamp. These are stored in localStorage under the key helicone_attribution and are never overwritten (first-touch semantics).

The module provides a PostHog-formatted retrieval function that prefixes all keys with $initial_ for compatibility with PostHog's first-touch attribution tracking. It includes SSR safety guards that return early when window or localStorage are unavailable.

Usage

Call captureAttributionParams on application mount to capture attribution data from the URL. Use getAttributionParams to retrieve raw attribution data, or getAttributionForPostHog to get PostHog-compatible formatted attribution for event tracking and user identification.

Code Reference

Source Location

• Repository: Helicone
• File: packages/common/attribution/index.ts

Signature

export interface AttributionParams {
  gclid?: string;
  utm_source?: string;
  utm_medium?: string;
  utm_campaign?: string;
  utm_term?: string;
  utm_content?: string;
  captured_at?: string;
  landing_page?: string;
}

export function captureAttributionParams(search: string): void
export function getAttributionParams(): AttributionParams | null
export function getAttributionForPostHog(
  options?: { omitUndefined?: boolean }
): Record<string, string | undefined>
export function clearAttribution(): void

Import

import {
  captureAttributionParams,
  getAttributionParams,
  getAttributionForPostHog,
  clearAttribution,
} from "@helicone/common/attribution";

I/O Contract

Function	Parameters	Returns	Description
captureAttributionParams	search: string (URL query string)	void	Captures UTM/gclid params on first visit and stores in localStorage
getAttributionParams	None	null	Retrieves raw stored attribution data
getAttributionForPostHog	options?: { omitUndefined?: boolean }	undefined>	Returns attribution with $initial_ prefixed keys for PostHog
clearAttribution	None	void	Removes stored attribution from localStorage

Storage Key	Location	Description
helicone_attribution	localStorage	JSON-serialized AttributionParams object

Usage Examples

// Capture on app mount (e.g., in a React useEffect)
import { captureAttributionParams } from "@helicone/common/attribution";

useEffect(() => {
  captureAttributionParams(window.location.search);
}, []);

// Retrieve attribution for PostHog identify call
import { getAttributionForPostHog } from "@helicone/common/attribution";

const attribution = getAttributionForPostHog({ omitUndefined: true });
posthog.identify(userId, {
  ...attribution,
});
// Result: { $initial_utm_source: "google", $initial_utm_medium: "cpc", ... }

Related Pages

• Principle:Helicone_Helicone_Marketing_Attribution