Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(growth): restore daily reporting and campaign attribution (#7832)

Francesco Bonacci05a0358f9d12
diff --git a/libs/fleet/backend/handlers/analytics_attribution.go b/libs/fleet/backend/handlers/analytics_attribution.go
index fc98b08614..297c31e538 100644
--- a/libs/fleet/backend/handlers/analytics_attribution.go
+++ b/libs/fleet/backend/handlers/analytics_attribution.go
@@ -19,6 +19,7 @@ const (
var fleetAttributionProperties = map[string]string{
"campaign_id": productanalytics.FirstTouchCampaignIDProperty,
"content_id": productanalytics.FirstTouchContentIDProperty,
+ "utm_content": productanalytics.FirstTouchContentIDProperty,
"utm_source": productanalytics.FirstTouchUTMSourceProperty,
"utm_medium": productanalytics.FirstTouchUTMMediumProperty,
"utm_campaign": productanalytics.FirstTouchUTMCampaignProperty,
@@ -102,6 +103,9 @@ func validateFleetAttribution(record fleetAttributionRecord, now time.Time) (map
if !ok || !validFleetAttributionValue(value) {
return nil, false
}
+ if existing, exists := setOnce[property]; exists && existing != value {
+ return nil, false
+ }
setOnce[property] = value
}
return setOnce, true
diff --git a/libs/fleet/backend/handlers/analytics_attribution_test.go b/libs/fleet/backend/handlers/analytics_attribution_test.go
index 3bd6f14ee5..e5f128daa8 100644
--- a/libs/fleet/backend/handlers/analytics_attribution_test.go
+++ b/libs/fleet/backend/handlers/analytics_attribution_test.go
@@ -33,7 +33,8 @@ func TestRecordFleetAttributionBindsExternalFirstTouch(t *testing.T) {
Values: map[string]string{
"utm_source": "x",
"utm_medium": "organic-social",
- "utm_campaign": "openclaw-2-launch",
+ "utm_campaign": "cursor-cloud-fleets",
+ "utm_content": "thread-post-5",
},
}, &auth.User{ID: "subject-1", Email: "[email protected]", EmailVerified: true, AZP: "cyclops-cs-spa", PrincipalType: auth.PrincipalTypeUser})
response := httptest.NewRecorder()
@@ -49,11 +50,32 @@ func TestRecordFleetAttributionBindsExternalFirstTouch(t *testing.T) {
}
if event.SetOnce[productanalytics.FirstTouchUTMSourceProperty] != "x" ||
event.SetOnce[productanalytics.FirstTouchUTMMediumProperty] != "organic-social" ||
- event.SetOnce[productanalytics.FirstTouchUTMCampaignProperty] != "openclaw-2-launch" {
+ event.SetOnce[productanalytics.FirstTouchUTMCampaignProperty] != "cursor-cloud-fleets" ||
+ event.SetOnce[productanalytics.FirstTouchContentIDProperty] != "thread-post-5" {
t.Fatalf("set once = %#v", event.SetOnce)
}
}
+func TestValidateFleetAttributionContentAliases(t *testing.T) {
+ now := time.Now()
+ for _, values := range []map[string]string{
+ {"content_id": "thread-post-5"},
+ {"utm_content": "thread-post-5"},
+ {"content_id": "thread-post-5", "utm_content": "thread-post-5"},
+ } {
+ setOnce, valid := validateFleetAttribution(fleetAttributionRecord{Version: 1, CapturedAt: now.UnixMilli(), Values: values}, now)
+ if !valid || setOnce[productanalytics.FirstTouchContentIDProperty] != "thread-post-5" {
+ t.Fatalf("values/setOnce/valid = %#v/%#v/%v", values, setOnce, valid)
+ }
+ }
+
+ if _, valid := validateFleetAttribution(fleetAttributionRecord{
+ Version: 1, CapturedAt: now.UnixMilli(), Values: map[string]string{"content_id": "legacy", "utm_content": "standard"},
+ }, now); valid {
+ t.Fatal("conflicting content aliases must be rejected")
+ }
+}
+
func TestRecordFleetAttributionBindsMissingEmailIdentity(t *testing.T) {
capture := &analyticsCapture{}
h := Handlers{Analytics: capture, AuthCfg: configAuthForAnalytics()}
diff --git a/libs/fleet/docs/fleet-attribution-phase1.md b/libs/fleet/docs/fleet-attribution-phase1.md
index 1e9d0d3f21..5444d4646d 100644
--- a/libs/fleet/docs/fleet-attribution-phase1.md
+++ b/libs/fleet/docs/fleet-attribution-phase1.md
@@ -4,11 +4,11 @@ This public contract defines bounded first-touch campaign binding and workload q
## Browser capture
-Before Keycloak bootstrap, the SPA captures first-touch values from the current URL: `campaign_id`, `content_id`, `utm_source`, `utm_medium`, and `utm_campaign`. Values use a conservative ASCII set (`A-Z`, `a-z`, `0-9`, `.`, `_`, `~`, `-`), are non-empty, and are at most 128 characters. The serialized version-1 record is limited to 2048 UTF-8 bytes and expires after 7 days. Unknown query keys are ignored; repeated allowed keys, malformed values, and oversized records are rejected. The first valid record is write-once in browser `sessionStorage` and is removed after a successful bind.
+Before Keycloak bootstrap, the SPA captures first-touch values from the current URL: `campaign_id`, `content_id`, `utm_source`, `utm_medium`, `utm_campaign`, and the standard `utm_content` alias. `utm_content` is stored and bound under the existing canonical `content_id` field, preserving compatibility with older `content_id` links and the `fleet_first_touch_content_id` person property. If both aliases are present they must have the same value. Values use a conservative ASCII set (`A-Z`, `a-z`, `0-9`, `.`, `_`, `~`, `-`), are non-empty, and are at most 128 characters. The serialized version-1 record is limited to 2048 UTF-8 bytes and expires after 7 days. Unknown query keys are ignored; repeated allowed keys, conflicting aliases, malformed values, and oversized records are rejected. The first valid record is write-once in browser `sessionStorage` and is removed after a successful bind.
-The five stable fields are acquisition-channel neutral. They can represent email, SEO, partners, future channels, and organic or paid social traffic without provider-specific behavior. For example, both `utm_source=x&utm_medium=organic-social` and `utm_source=x&utm_medium=paid-social` are ordinary valid values. Provider SDKs, pixels, credentials, arbitrary provider payloads, and provider-specific success semantics are outside this contract. Pixels are optional downstream adapters and are not part of Phase 1.
+The five canonical fields are acquisition-channel neutral. They can represent email, SEO, partners, future channels, and organic or paid social traffic without provider-specific behavior. For example, both `utm_source=x&utm_medium=organic-social` and `utm_source=x&utm_medium=paid-social` are ordinary valid values. Provider SDKs, pixels, credentials, arbitrary provider payloads, and provider-specific success semantics are outside this contract. Pixels are optional downstream adapters and are not part of Phase 1.
-Use `content_id` for placement detail, not `utm_content` (an ignored unknown key). For the GitHub README CTA, use this capture-compatible URL:
+New links may use standard `utm_content`; existing `content_id` links remain supported. For the GitHub README CTA, this existing capture-compatible URL remains valid:
```text
https://run.cua.ai/?utm_source=github&utm_medium=referral&utm_campaign=fleet_activation&content_id=repo_readme
diff --git a/libs/fleet/src/auth/fleet-attribution.ts b/libs/fleet/src/auth/fleet-attribution.ts
index 57a7e9a967..22f1173f1d 100644
--- a/libs/fleet/src/auth/fleet-attribution.ts
+++ b/libs/fleet/src/auth/fleet-attribution.ts
@@ -4,6 +4,7 @@ export const ATTRIBUTION_MAX_VALUE_LENGTH = 128
export const ATTRIBUTION_MAX_RECORD_BYTES = 2048
const allowedKeys = ["campaign_id", "content_id", "utm_source", "utm_medium", "utm_campaign"] as const
+const queryKeys = [...allowedKeys, "utm_content"] as const
type AttributionKey = (typeof allowedKeys)[number]
export type AttributionRecord = { version: 1; capturedAt: number; values: Partial<Record<AttributionKey, string>> }
export interface StorageLike { getItem(key: string): string | null; setItem(key: string, value: string): void; removeItem?(key: string): void }
@@ -20,10 +21,14 @@ export function captureFleetAttribution(href: string, options: Options = {}): vo
let params: URLSearchParams
try { params = new URL(href).searchParams } catch { return }
const values: Partial<Record<AttributionKey, string>> = {}
- for (const key of allowedKeys) {
+ for (const key of queryKeys) {
const all = params.getAll(key)
if (all.length > 1 || (all.length === 1 && !validValue(all[0]!))) return
- if (all.length === 1) values[key] = all[0]!
+ if (all.length === 1) {
+ const canonicalKey: AttributionKey = key === "utm_content" ? "content_id" : key
+ if (values[canonicalKey] !== undefined && values[canonicalKey] !== all[0]) return
+ values[canonicalKey] = all[0]!
+ }
}
if (Object.keys(values).length === 0) return
const record: AttributionRecord = { version: 1, capturedAt: (options.now ?? Date.now)(), values }
diff --git a/libs/fleet/tests/fleet-attribution-doc.test.mjs b/libs/fleet/tests/fleet-attribution-doc.test.mjs
index eb6d15ebcf..944bd11405 100644
--- a/libs/fleet/tests/fleet-attribution-doc.test.mjs
+++ b/libs/fleet/tests/fleet-attribution-doc.test.mjs
@@ -18,6 +18,9 @@ test("public contract is channel-neutral and says unknown query keys are ignored
assert.match(contract, /utm_source=x.*utm_medium=organic-social/s)
assert.match(contract, /utm_source=x.*utm_medium=paid-social/s)
assert.match(contract, /unknown query keys are ignored/i)
+ assert.match(contract, /standard `utm_content` alias/i)
+ assert.match(contract, /stored and bound under the existing canonical `content_id` field/i)
+ assert.match(contract, /both aliases are present they must have the same value/i)
assert.match(contract, /pixels.*optional downstream adapters/i)
assert.match(contract, /keyed-HMAC pseudonym/i)
assert.match(contract, /internal and unknown identities are discarded/i)
diff --git a/libs/fleet/tests/fleet-attribution.test.ts b/libs/fleet/tests/fleet-attribution.test.ts
index fcd5e65a2b..a02660e13a 100644
--- a/libs/fleet/tests/fleet-attribution.test.ts
+++ b/libs/fleet/tests/fleet-attribution.test.ts
@@ -76,10 +76,7 @@ test("GitHub README CTA preserves all four fields through a simulated Keycloak b
},
}
- for (const href of [
- cta,
- `${cta}&utm_content=ignored&email=person%40example.test&identity=raw-subject&url=https%3A%2F%2Fexample.test`,
- ]) {
+ for (const href of [cta, `${cta}&email=person%40example.test&identity=raw-subject&url=https%3A%2F%2Fexample.test`]) {
const storage = memoryStorage()
captureFleetAttribution(href, { storage, now: () => firstTouch })
assert.deepEqual(JSON.parse(storage.getItem(ATTRIBUTION_STORAGE_KEY) ?? "null"), expected)
@@ -102,12 +99,25 @@ test("GitHub README CTA preserves all four fields through a simulated Keycloak b
getAccessToken: async () => "access-token",
})
- // Exact records exclude the raw URL, email, identity, and unknown utm_content.
+ // Exact records exclude the raw URL, email, identity, and unknown keys.
assert.deepEqual(bound, [expected])
assert.equal(storage.getItem(ATTRIBUTION_STORAGE_KEY), null)
}
})
+test("standard utm_content is stored under canonical content_id without loss", () => {
+ for (const href of [
+ "https://run.cua.ai/?utm_source=x&utm_medium=organic-social&utm_campaign=cursor-cloud-fleets&utm_content=thread-post-5",
+ "https://run.cua.ai/?utm_content=thread-post-5&content_id=thread-post-5",
+ ]) {
+ const storage = memoryStorage()
+ captureFleetAttribution(href, { storage, now: () => 50 })
+ const record = JSON.parse(storage.getItem(ATTRIBUTION_STORAGE_KEY) ?? "null")
+ assert.equal(record.values.content_id, "thread-post-5")
+ assert.equal(record.values.utm_content, undefined)
+ }
+})
+
test("invalid, malformed, empty, oversized, and expired records never reach a binder", async () => {
const now = 1_700_000_000_000
const invalidStoredRecords = [
@@ -133,6 +143,8 @@ test("capture rejects repeated, empty, invalid, and oversized values without tru
const invalidQueries = [
"?campaign_id=",
"?campaign_id=one&campaign_id=two",
+ "?utm_content=one&utm_content=two",
+ "?content_id=legacy&utm_content=standard",
"?campaign_id=has%20space",
`?campaign_id=${"x".repeat(ATTRIBUTION_MAX_VALUE_LENGTH + 1)}`,
]