🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(analytics): extend signup attribution to LinkedIn, Reddit, and X click ids (#16341)
Jannik Maierhöfer00b4d0de4f62
diff --git a/web/src/__tests__/server/unit/signupAttribution.servertest.ts b/web/src/__tests__/server/unit/signupAttribution.servertest.tsindex 9d99ada80d..ebf9d3821a 100644--- a/web/src/__tests__/server/unit/signupAttribution.servertest.ts+++ b/web/src/__tests__/server/unit/signupAttribution.servertest.ts@@ -1,96 +1,129 @@import { describe, expect, it } from "vitest";-import { getGclidFromRequest } from "@/src/features/auth/lib/signupAttribution";+import { getAdClickIdsFromRequest } from "@/src/features/auth/lib/signupAttribution";-// The gclid is read from first-party cookies on .langfuse.com so that-// cloud_signup_complete events can be attributed to Google Ads clicks that-// landed on the langfuse.com marketing site. See signupAttribution.ts for-// the source priority.-describe("getGclidFromRequest", () => {+// Click ids are read from first-party cookies on .langfuse.com so that+// cloud_signup_complete events can be attributed to ad clicks that landed on+// the langfuse.com marketing site. See signupAttribution.ts for the source+// priority per platform.+describe("getAdClickIdsFromRequest", () => {const posthogCookieName = "ph_phc_someProjectApiKey123_posthog";- it("returns undefined without any attribution cookies", () => {- expect(getGclidFromRequest({ cookies: {} })).toBeUndefined();+ it("returns an empty object without any attribution cookies", () => {+ expect(getAdClickIdsFromRequest({ cookies: {} })).toEqual({});});- it("reads the dedicated lf_gclid cookie", () => {+ it("reads the dedicated lf_* cookies for every platform", () => {expect(- getGclidFromRequest({- cookies: { lf_gclid: "Cj0KCQjw_test-123" },+ getAdClickIdsFromRequest({+ cookies: {+ lf_gclid: "Cj0KCQjw_google-123",+ lf_li_fat_id: "01fa-linkedin-uuid",+ lf_rdt_cid: "reddit_click_id",+ lf_twclid: "twitter-click-id",+ },}),- ).toBe("Cj0KCQjw_test-123");+ ).toEqual({+ gclid: "Cj0KCQjw_google-123",+ li_fat_id: "01fa-linkedin-uuid",+ rdt_cid: "reddit_click_id",+ twclid: "twitter-click-id",+ });+ });++ it("omits ids that did not resolve so the result can be spread into event properties", () => {+ expect(+ getAdClickIdsFromRequest({ cookies: { lf_rdt_cid: "reddit-only" } }),+ ).toEqual({ rdt_cid: "reddit-only" });});- it("prefers lf_gclid over _gcl_aw", () => {+ it("prefers lf_gclid over Google's _gcl_aw linker cookie", () => {expect(- getGclidFromRequest({+ getAdClickIdsFromRequest({cookies: {lf_gclid: "gclid-from-dedicated-cookie",_gcl_aw: "GCL.1700000000.gclid-from-google-cookie",},- }),+ }).gclid,).toBe("gclid-from-dedicated-cookie");});it("parses the gclid from Google's _gcl_aw linker cookie", () => {expect(- getGclidFromRequest({+ getAdClickIdsFromRequest({cookies: { _gcl_aw: "GCL.1700000000.Cj0KCQjw_abcDEF-123" },}),- ).toBe("Cj0KCQjw_abcDEF-123");+ ).toEqual({ gclid: "Cj0KCQjw_abcDEF-123" });});it("ignores a malformed _gcl_aw cookie", () => {expect(- getGclidFromRequest({ cookies: { _gcl_aw: "not-the-format" } }),- ).toBeUndefined();+ getAdClickIdsFromRequest({ cookies: { _gcl_aw: "not-the-format" } }),+ ).toEqual({});});- it("falls back to the gclid in the PostHog first-touch URL", () => {+ it("reads the LinkedIn Insight Tag's li_fat_id cookie", () => {+ expect(+ getAdClickIdsFromRequest({+ cookies: { li_fat_id: "11abcdef-1234-5678-9abc-def012345678" },+ }),+ ).toEqual({ li_fat_id: "11abcdef-1234-5678-9abc-def012345678" });+ });++ it("reads the Reddit Pixel's _rdt_cid cookie", () => {+ expect(+ getAdClickIdsFromRequest({ cookies: { _rdt_cid: "t2_reddit.click_id" } }),+ ).toEqual({ rdt_cid: "t2_reddit.click_id" });+ });++ it("falls back to click-id params in the PostHog first-touch URL", () => {const cookieValue = JSON.stringify({distinct_id: "some-id",$initial_person_info: {r: "https://www.google.com/",- u: "https://langfuse.com/?utm_source=x&gclid=Cj0-initial-touch",+ u: "https://langfuse.com/?utm_source=x&gclid=Cj0-initial&li_fat_id=li-initial&rdt_cid=rdt-initial&twclid=tw-initial",},});expect(- getGclidFromRequest({+ getAdClickIdsFromRequest({cookies: { [posthogCookieName]: cookieValue },}),- ).toBe("Cj0-initial-touch");+ ).toEqual({+ gclid: "Cj0-initial",+ li_fat_id: "li-initial",+ rdt_cid: "rdt-initial",+ twclid: "tw-initial",+ });});- it("returns undefined when the PostHog first-touch URL has no gclid", () => {+ it("returns an empty object when the PostHog first-touch URL has no click ids", () => {const cookieValue = JSON.stringify({distinct_id: "some-id",$initial_person_info: { r: "", u: "https://langfuse.com/docs" },});expect(- getGclidFromRequest({+ getAdClickIdsFromRequest({cookies: { [posthogCookieName]: cookieValue },}),- ).toBeUndefined();+ ).toEqual({});});it("ignores a malformed PostHog cookie", () => {expect(- getGclidFromRequest({+ getAdClickIdsFromRequest({cookies: { [posthogCookieName]: "%%%not-json" },}),- ).toBeUndefined();+ ).toEqual({});});it("rejects values with unexpected characters or excessive length", () => {expect(- getGclidFromRequest({- cookies: { lf_gclid: '"><script>alert(1)</script>' },- }),- ).toBeUndefined();- expect(- getGclidFromRequest({- cookies: { lf_gclid: "a".repeat(513) },+ getAdClickIdsFromRequest({+ cookies: {+ lf_gclid: '"><script>alert(1)</script>',+ lf_li_fat_id: "a".repeat(513),+ },}),- ).toBeUndefined();+ ).toEqual({});});});diff --git a/web/src/features/auth-credentials/lib/credentialsServerUtils.ts b/web/src/features/auth-credentials/lib/credentialsServerUtils.tsindex 7438333bba..96b89e0f10 100644--- a/web/src/features/auth-credentials/lib/credentialsServerUtils.ts+++ b/web/src/features/auth-credentials/lib/credentialsServerUtils.ts@@ -1,4 +1,5 @@import { createProjectMembershipsOnSignup } from "@/src/features/auth/lib/createProjectMembershipsOnSignup";+import { type AdClickIds } from "@/src/features/auth/lib/signupAttribution";import { prisma } from "@langfuse/shared/src/db";import { compare, hash } from "bcryptjs";@@ -16,8 +17,8 @@ export async function createUserEmailPassword(password: string,name: string,options?: {- /** Google Ads click id, see getGclidFromRequest */- gclid?: string;+ /** Ad-platform click ids, see getAdClickIdsFromRequest */+ adClickIds?: AdClickIds;},) {if (!isValidPassword(password))@@ -48,7 +49,7 @@ export async function createUserEmailPassword(await createProjectMembershipsOnSignup(newUser, {userWasJustCreated: true,- gclid: options?.gclid,+ adClickIds: options?.adClickIds,});return newUser.id;diff --git a/web/src/features/auth-credentials/server/signupApiHandler.ts b/web/src/features/auth-credentials/server/signupApiHandler.tsindex e3da5cc291..9aeead0744 100644--- a/web/src/features/auth-credentials/server/signupApiHandler.ts+++ b/web/src/features/auth-credentials/server/signupApiHandler.ts@@ -1,6 +1,6 @@import { env } from "@/src/env.mjs";import { createUserEmailPassword } from "@/src/features/auth-credentials/lib/credentialsServerUtils";-import { getGclidFromRequest } from "@/src/features/auth/lib/signupAttribution";+import { getAdClickIdsFromRequest } from "@/src/features/auth/lib/signupAttribution";import { signupSchema } from "@/src/features/auth/lib/signupSchema";import { getSsoAuthProviderIdForDomain } from "@/src/ee/features/multi-tenant-sso/utils";import { ENTERPRISE_SSO_REQUIRED_MESSAGE } from "@/src/features/auth/constants";@@ -98,7 +98,7 @@ export async function signupApiHandler(body.email,body.password,body.name,- { gclid: getGclidFromRequest(req) },+ { adClickIds: getAdClickIdsFromRequest(req) },);} catch (error) {const message =diff --git a/web/src/features/auth/lib/createProjectMembershipsOnSignup.ts b/web/src/features/auth/lib/createProjectMembershipsOnSignup.tsindex 4b0d9ddc07..71b27ac745 100644--- a/web/src/features/auth/lib/createProjectMembershipsOnSignup.ts+++ b/web/src/features/auth/lib/createProjectMembershipsOnSignup.ts@@ -9,6 +9,7 @@ import { getSfdcService } from "@/src/ee/features/sfdc-sync/server";import { canCreateOrganizations } from "@/src/features/organizations/server/canCreateOrganizations";import { provisionStarterOrganizationForNewUser } from "@/src/features/onboarding/server/onboardingService";import { projectRoleAccessRights } from "@langfuse/shared";+import { type AdClickIds } from "@/src/features/auth/lib/signupAttribution";export async function createProjectMembershipsOnSignup(user: {@@ -18,8 +19,8 @@ export async function createProjectMembershipsOnSignup(},options?: {userWasJustCreated?: boolean;- /** Google Ads click id, see getGclidFromRequest */- gclid?: string;+ /** Ad-platform click ids, see getAdClickIdsFromRequest */+ adClickIds?: AdClickIds;},) {try {@@ -304,7 +305,9 @@ export async function createProjectMembershipsOnSignup(hasDefaultOrg: defaultOrgs.length > 0,hasDefaultProject: defaultProjects.length > 0,// Google Ads click id for ad conversion attribution- ...(options?.gclid ? { gclid: options.gclid } : {}),+ // ad-platform click ids (gclid, li_fat_id, rdt_cid, twclid)+ // for ad conversion attribution; only resolved ids are present+ ...(options?.adClickIds ?? {}),},});await posthog.shutdown();diff --git a/web/src/features/auth/lib/signupAttribution.ts b/web/src/features/auth/lib/signupAttribution.tsindex 426b698655..dd8ac693b0 100644--- a/web/src/features/auth/lib/signupAttribution.ts+++ b/web/src/features/auth/lib/signupAttribution.ts@@ -1,7 +1,31 @@-// gclids are opaque tokens (typically ~60-120 chars); cap length and charset to-// avoid persisting arbitrary user-controlled strings into analytics events-const MAX_GCLID_LENGTH = 512;-const GCLID_FORMAT = /^[A-Za-z0-9_-]+$/;+// Ad-platform click ids appended to landing-page URLs by ad clicks. Keys use+// the platforms' canonical URL-param names — the same names PostHog's CDP+// destination templates expect — so event properties map 1:1 in destination+// configuration. `gclid` keeps the name it had in the Google-only+// implementation so the live Google Ads destination mapping keeps working.+export type AdClickIds = {+ /** Google Ads */+ gclid?: string;+ /** LinkedIn Ads (first-party ad tracking UUID) */+ li_fat_id?: string;+ /** Reddit Ads */+ rdt_cid?: string;+ /** X (Twitter) Ads — captured for future use, PostHog has no X destination */+ twclid?: string;+};++const CLICK_ID_PARAMS = [+ "gclid",+ "li_fat_id",+ "rdt_cid",+ "twclid",+] as const satisfies readonly (keyof AdClickIds)[];++// click ids are opaque tokens (typically ~60-120 chars); cap length and+// charset to avoid persisting arbitrary user-controlled strings into+// analytics events+const MAX_CLICK_ID_LENGTH = 512;+const CLICK_ID_FORMAT = /^[A-Za-z0-9_.-]+$/;// posthog-js persistence cookie, named after the project api keyconst POSTHOG_COOKIE_NAME = /^ph_phc_[A-Za-z0-9]+_posthog$/;@@ -10,73 +34,99 @@ type RequestWithCookies = {cookies: Partial<Record<string, string>>;};-function sanitizeGclid(value: string | null | undefined): string | undefined {+function sanitizeClickId(value: string | null | undefined): string | undefined {if (!value) return undefined;const trimmed = value.trim();if (trimmed.length === 0 ||- trimmed.length > MAX_GCLID_LENGTH ||- !GCLID_FORMAT.test(trimmed)+ trimmed.length > MAX_CLICK_ID_LENGTH ||+ !CLICK_ID_FORMAT.test(trimmed))return undefined;return trimmed;}+// The PostHog persistence cookie stores the URL of the visitor's first-ever+// pageview under `$initial_person_info.u` — a first-touch fallback source for+// every click id, e.g. when ad consent was not given so the platform pixels+// never ran.+function getFirstTouchUrl(req: RequestWithCookies): URL | undefined {+ const posthogCookie = Object.entries(req.cookies).find(([name]) =>+ POSTHOG_COOKIE_NAME.test(name),+ )?.[1];+ if (!posthogCookie) return undefined;+ try {+ const parsed: unknown = JSON.parse(posthogCookie);+ const initialUrl =+ typeof parsed === "object" &&+ parsed !== null &&+ "$initial_person_info" in parsed &&+ typeof parsed.$initial_person_info === "object" &&+ parsed.$initial_person_info !== null &&+ "u" in parsed.$initial_person_info &&+ typeof parsed.$initial_person_info.u === "string"+ ? parsed.$initial_person_info.u+ : undefined;+ return initialUrl ? new URL(initialUrl) : undefined;+ } catch {+ // malformed cookie — attribution is best-effort, ignore+ return undefined;+ }+}++// The ad platforms' own first-party cookies, where the pixel sets one. Only+// present when the visitor consented to advertisement cookies on+// langfuse.com and the pixel was not blocked.+function getPlatformCookieValue(+ req: RequestWithCookies,+ param: keyof AdClickIds,+): string | undefined {+ switch (param) {+ // Google conversion linker (gtag.js), format `GCL.<timestamp>.<gclid>`+ case "gclid":+ return req.cookies["_gcl_aw"]?.split(".").slice(2).join(".");+ // LinkedIn Insight Tag stores the click id under its own param name+ case "li_fat_id":+ return req.cookies["li_fat_id"];+ // Reddit Pixel+ case "rdt_cid":+ return req.cookies["_rdt_cid"];+ // X's pixel does not persist twclid in a readable first-party cookie+ case "twclid":+ return undefined;+ }+}+/**- * Extracts the Google Ads click id (gclid) of the ad click that led this- * browser to Langfuse, if any. Used to attribute `cloud_signup_complete`- * events to Google Ads campaigns (uploaded via a PostHog CDP destination).+ * Extracts the ad-platform click ids of the ad click that led this browser to+ * Langfuse, if any. Used to attribute `cloud_signup_complete` events to ad+ * campaigns, which PostHog CDP destinations upload to Google Ads, LinkedIn+ * Ads, and Reddit Ads as conversions.** All sources are first-party cookies on `.langfuse.com`, so they are sent* along with every request to the cloud app regardless of which page the ad- * click originally landed on (usually the langfuse.com marketing site):+ * click originally landed on (usually the langfuse.com marketing site). Per+ * click id, in priority order:*- * 1. `lf_gclid` — set by langfuse.com on every landing with a `?gclid=` param- * (last ad click wins).- * 2. `_gcl_aw` — Google's own conversion-linker cookie set by gtag.js on- * langfuse.com, format `GCL.<timestamp>.<gclid>`.- * 3. The PostHog cookie's `$initial_person_info.u` (the URL of the visitor's- * first-ever pageview) — first-touch fallback, e.g. when ad-consent was- * not given so gtag never ran.+ * 1. `lf_<param>` — set by langfuse.com on every landing with that platform's+ * click-id param (last ad click wins).+ * 2. The platform pixel's own first-party cookie, where it sets one.+ * 3. The click-id param in the PostHog cookie's first-touch URL.+ *+ * Only ids that resolved are present in the returned object, so it can be+ * spread straight into event properties.*/-export function getGclidFromRequest(- req: RequestWithCookies,-): string | undefined {- // 1. dedicated first-party cookie set by the marketing site- const fromDedicatedCookie = sanitizeGclid(req.cookies["lf_gclid"]);- if (fromDedicatedCookie) return fromDedicatedCookie;+export function getAdClickIdsFromRequest(req: RequestWithCookies): AdClickIds {+ const firstTouchUrl = getFirstTouchUrl(req);+ const clickIds: AdClickIds = {};- // 2. Google conversion-linker cookie: GCL.<timestamp>.<gclid>- const gclAw = req.cookies["_gcl_aw"];- if (gclAw) {- const fromGclAw = sanitizeGclid(gclAw.split(".").slice(2).join("."));- if (fromGclAw) return fromGclAw;- }-- // 3. PostHog persistence cookie: first-touch URL may contain the gclid- const posthogCookie = Object.entries(req.cookies).find(([name]) =>- POSTHOG_COOKIE_NAME.test(name),- )?.[1];- if (posthogCookie) {- try {- const parsed: unknown = JSON.parse(posthogCookie);- const initialUrl =- typeof parsed === "object" &&- parsed !== null &&- "$initial_person_info" in parsed &&- typeof parsed.$initial_person_info === "object" &&- parsed.$initial_person_info !== null &&- "u" in parsed.$initial_person_info &&- typeof parsed.$initial_person_info.u === "string"- ? parsed.$initial_person_info.u- : undefined;- if (initialUrl) {- return sanitizeGclid(new URL(initialUrl).searchParams.get("gclid"));- }- } catch {- // malformed cookie — attribution is best-effort, ignore- }+ for (const param of CLICK_ID_PARAMS) {+ const value =+ sanitizeClickId(req.cookies[`lf_${param}`]) ??+ sanitizeClickId(getPlatformCookieValue(req, param)) ??+ sanitizeClickId(firstTouchUrl?.searchParams.get(param));+ if (value) clickIds[param] = value;}- return undefined;+ return clickIds;}diff --git a/web/src/pages/api/auth/[...nextauth].ts b/web/src/pages/api/auth/[...nextauth].tsindex 028fa0f2f7..cc6b8c16e7 100644--- a/web/src/pages/api/auth/[...nextauth].ts+++ b/web/src/pages/api/auth/[...nextauth].ts@@ -1,5 +1,5 @@import { getAuthOptions } from "@/src/server/auth";-import { getGclidFromRequest } from "@/src/features/auth/lib/signupAttribution";+import { getAdClickIdsFromRequest } from "@/src/features/auth/lib/signupAttribution";import { getCookieName } from "@/src/server/utils/cookies";import { isValidCallbackUrl } from "@/src/server/utils/nextAuthCallbackUrl";import { env } from "@/src/env.mjs";@@ -138,7 +138,7 @@ export default async function auth(req: NextApiRequest, res: NextApiResponse) {// Pass Google Ads click attribution from first-party cookies so that new// SSO signups can be attributed to ad clicks (cloud_signup_complete event).const authOptions = await getAuthOptions({- gclid: getGclidFromRequest(req),+ adClickIds: getAdClickIdsFromRequest(req),});// https://github.com/nextauthjs/next-auth/issues/2408#issuecomment-1382629234// for api routes, we need to call the headers in the api route itselfdiff --git a/web/src/pages/api/auth/signup-verify.ts b/web/src/pages/api/auth/signup-verify.tsindex 8bd4d0b79b..650e0856cf 100644--- a/web/src/pages/api/auth/signup-verify.ts+++ b/web/src/pages/api/auth/signup-verify.ts@@ -2,7 +2,7 @@ import { env } from "@/src/env.mjs";import { isEmailVerificationRequired } from "@/src/features/auth-credentials/lib/credentialsUtils";import { validateSignupEligibility } from "@/src/features/auth-credentials/server/signupApiHandler";import { createProjectMembershipsOnSignup } from "@/src/features/auth/lib/createProjectMembershipsOnSignup";-import { getGclidFromRequest } from "@/src/features/auth/lib/signupAttribution";+import { getAdClickIdsFromRequest } from "@/src/features/auth/lib/signupAttribution";import { prisma } from "@langfuse/shared/src/db";import { logger } from "@langfuse/shared/src/server";import type { NextApiRequest, NextApiResponse } from "next";@@ -85,7 +85,7 @@ export default async function handler(await createProjectMembershipsOnSignup(newUser, {userWasJustCreated: true,- gclid: getGclidFromRequest(req),+ adClickIds: getAdClickIdsFromRequest(req),});// Trigger new user signup eventdiff --git a/web/src/server/auth.ts b/web/src/server/auth.tsindex 0188cff64c..a12e5cd5ab 100644--- a/web/src/server/auth.ts+++ b/web/src/server/auth.ts@@ -14,6 +14,7 @@ import {import { parseFlags } from "@/src/features/feature-flags/utils";import { env } from "@/src/env.mjs";import { createProjectMembershipsOnSignup } from "@/src/features/auth/lib/createProjectMembershipsOnSignup";+import { type AdClickIds } from "@/src/features/auth/lib/signupAttribution";import {type AdapterUser,type Adapter,@@ -604,10 +605,10 @@ if (env.AUTH_WORDPRESS_CLIENT_ID && env.AUTH_WORDPRESS_CLIENT_SECRET)const prismaAdapter = PrismaAdapter(prisma);const ignoredAccountFields = env.AUTH_IGNORE_ACCOUNT_FIELDS?.split(",") ?? [];// Factory instead of a static adapter so that per-request signup attribution-// (Google Ads click id from first-party cookies) can reach the signup event+// (ad-platform click ids from first-party cookies) can reach the signup event// captured for new SSO users.const createExtendedPrismaAdapter = (signupAttribution?: {- gclid?: string;+ adClickIds?: AdClickIds;}): Adapter => ({...prismaAdapter,async createUser(profile: Omit<AdapterUser, "id">) {@@ -630,7 +631,7 @@ const createExtendedPrismaAdapter = (signupAttribution?: {await createProjectMembershipsOnSignup(user, {userWasJustCreated: true,- gclid: signupAttribution?.gclid,+ adClickIds: signupAttribution?.adClickIds,});return user;@@ -674,7 +675,7 @@ const createExtendedPrismaAdapter = (signupAttribution?: {});if (user) {await createProjectMembershipsOnSignup(user, {- gclid: signupAttribution?.gclid,+ adClickIds: signupAttribution?.adClickIds,});}},@@ -751,14 +752,14 @@ const createExtendedPrismaAdapter = (signupAttribution?: {/*** Options for NextAuth.js used to configure adapters, providers, callbacks, etc.*- * @param signupAttribution - per-request marketing attribution (e.g. Google- * Ads click id) attached to the signup analytics event if the request results+ * @param signupAttribution - per-request marketing attribution (ad-platform+ * click ids) attached to the signup analytics event if the request results* in a new user. Only passed by the NextAuth API route.** @see https://next-auth.js.org/configuration/options*/export async function getAuthOptions(signupAttribution?: {- gclid?: string;+ adClickIds?: AdClickIds;}): Promise<NextAuthOptions> {let dynamicSsoProviders: Provider[] = [];try {