Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 31 additions & 7 deletions infrastructure/analytics-api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,9 @@ secret values into parameters, source files, or shell history.
managed administrator secret before deploying code that reads a new
reporting relation. On reapplication, omit existing `CREATE ROLE` and
`CREATE MATERIALIZED VIEW` statements, then run the replaceable view and
idempotent `GRANT` statements.
idempotent `GRANT` statements. Also apply `spacetech-form-status.sql` to
create/grant the narrow form-lifecycle view before deploying the form-status
Lambda change. It is additive and safe to reapply; no historical data is changed.
6. Deploy `template.yaml` with `CAPABILITY_NAMED_IAM`, the shared HTTP API ID,
and the exact workgroup, wildcard certificate, public hosted zone, code
bucket, and code key.
Expand Down Expand Up @@ -253,12 +255,34 @@ filtering/sorting. The same table remains in Reports → Forms, whose CSV export
retains its server-generated date-range behavior. No reporting permission is
expanded. A denied Forms request leaves aggregate analytics usable.

Saved lead rows are Submitted. Partial names/answers are not collected; starts
and incomplete visits are aggregate analytics only. The published development
form already contains the seven answer/UTM fields above; metadata supplies the
date. No form schema or historical lead data is rewritten. The existing website
instrumentation remains required; historical FAQ opens and form-section exposure
cannot be reconstructed.
Saved lead rows are Submitted. The SpaceTech analytics response also includes
`formActivity`, anonymous unfinished attempts with only start time, source, medium,
campaign and status. The lead table combines these with Forms-authorized submissions;
partial names, emails and answers remain blank. Reports → Forms and its CSV export
remain submission-only.

Apply `spacetech-form-status.sql` before deploying the updated Lambda. Its narrow
view reads the existing start, abandonment and completion events, including
historical events, without granting access to the raw event table. No collector,
form schema or historical data changes are required. The UI explicitly reports
activity as unavailable when connected to an older API without `formActivity`.

Started means a start was observed without completion or abandonment. Incomplete
means an abandonment was observed without completion. Completion takes precedence
and removes the anonymous attempt; the submitted lead comes only from Forms.
Attempts are correlated by pseudonymous visitor and session, from each start until
the next start. Visitor/session IDs stay in SQL and never enter the API response.
The selected dates and UTM filters apply to the start; terminal events are checked
even after the selected end date or with changed UTM values. The mixed table labels
its date column Date Submitted / Started. Attribution comes from the start event.
Missing abandonment events are not guessed from elapsed time, so a Started row
is not a promise that the visitor is still online. Simultaneous tabs cannot be
unambiguously distinguished without a future per-form-instance tracking ID.

Activity follows warehouse ingestion, while submitted lead details remain
immediate. The existing 2,000-row response limit still fails explicitly rather
than silently truncating activity. Historical FAQ opens and form-section exposure
cannot be reconstructed without the corresponding website instrumentation.

Rollback: redeploy the previous Lambda CodeKey and template; restore the previous
processing enrichment parameter if needed. Leave the additive v2 projection and
Expand Down
2 changes: 2 additions & 0 deletions infrastructure/analytics-api/bootstrap.sql
Original file line number Diff line number Diff line change
Expand Up @@ -206,3 +206,5 @@ END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
REVOKE ALL ON PROCEDURE topcoder_web.refresh_spacetech_report() FROM PUBLIC;
GRANT EXECUTE ON PROCEDURE topcoder_web.refresh_spacetech_report() TO ROLE analytics_api_reader;

-- Also apply spacetech-form-status.sql before deploying the form-status API.
22 changes: 22 additions & 0 deletions infrastructure/analytics-api/spacetech-form-status.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
-- Apply before deploying the PM-6712 form-status Lambda change.
-- Additive and safe to reapply; grants no access to answers or raw events.
CREATE OR REPLACE VIEW topcoder_web.spacetech_form_events_v1 AS
SELECT DISTINCT
event_timestamp,
user_pseudo_id AS visitor_id,
session_id,
event_name,
traffic_source_source AS source,
traffic_source_medium AS medium,
traffic_source_campaign AS campaign,
traffic_source_content AS content
FROM topcoder_web.event_v2
WHERE COALESCE(
NULLIF(JSON_EXTRACT_PATH_TEXT(custom_parameters_json_str, 'page_path', true), ''),
page_view_page_url_path
) IN ('/space-tech', '/space-tech/')
AND JSON_EXTRACT_PATH_TEXT(custom_parameters_json_str, 'surface', true) = 'topcoder_website'
AND JSON_EXTRACT_PATH_TEXT(custom_parameters_json_str, 'form_id', true) = 'topcoder:space_tech_challenge'
AND event_name IN ('form_started', 'form_completed', 'form_abandoned');

GRANT SELECT ON topcoder_web.spacetech_form_events_v1 TO ROLE analytics_api_reader;
45 changes: 44 additions & 1 deletion infrastructure/analytics-api/src/handler.py
Original file line number Diff line number Diff line change
Expand Up @@ -378,7 +378,35 @@


SPACETECH_SQL = """
WITH date_events AS (
WITH form_events AS (
SELECT * FROM topcoder_web.spacetech_form_events_v1
WHERE event_timestamp >= CAST(:from_date AS timestamp)
), form_starts AS (
-- Attribute each attempt to its start, before applying any UTM filters.
-- Later starts delimit repeat attempts in the same visitor/session.
SELECT *, LEAD(event_timestamp) OVER (
PARTITION BY visitor_id, session_id ORDER BY event_timestamp
) AS next_start
FROM form_events WHERE event_name = 'form_started'
), form_attempts AS (
SELECT attempt.visitor_id, attempt.session_id, attempt.event_timestamp,
attempt.source, attempt.medium, attempt.campaign,
MAX(CASE WHEN terminal.event_name = 'form_completed' THEN 1 ELSE 0 END) AS completed,
MAX(CASE WHEN terminal.event_name = 'form_abandoned' THEN 1 ELSE 0 END) AS abandoned
FROM form_starts attempt
LEFT JOIN form_events terminal
ON terminal.visitor_id = attempt.visitor_id AND terminal.session_id = attempt.session_id
AND terminal.event_timestamp >= attempt.event_timestamp
AND (attempt.next_start IS NULL OR terminal.event_timestamp < attempt.next_start)
AND terminal.event_name IN ('form_completed', 'form_abandoned')
WHERE attempt.event_timestamp < DATEADD(day, 1, CAST(:to_date AS timestamp))
AND (:source = '*' OR attempt.source = :source)
AND (:medium = '*' OR attempt.medium = :medium)
AND (:campaign = '*' OR attempt.campaign = :campaign)
AND (:content = '*' OR attempt.content = :content)
GROUP BY attempt.visitor_id, attempt.session_id, attempt.event_timestamp,
attempt.source, attempt.medium, attempt.campaign
), date_events AS (
SELECT * FROM topcoder_web.spacetech_events_mv_v2
WHERE event_timestamp >= CAST(:from_date AS timestamp)
AND event_timestamp < DATEADD(day, 1, CAST(:to_date AS timestamp))
Expand Down Expand Up @@ -528,6 +556,13 @@
SELECT 'option_campaign'::varchar, campaign, NULL::varchar, NULL::varchar, NULL::varchar,
0::bigint, 0::bigint, 0::bigint, 0::bigint, 0::bigint, 0::bigint, 0::bigint, 0::bigint
FROM date_events WHERE campaign IS NOT NULL AND campaign <> '' GROUP BY campaign
UNION ALL
-- Completed attempts are supplied by the authorized Forms API, not duplicated here.
-- Visitor/session keys remain in SQL and never enter the response.
SELECT CASE WHEN abandoned = 1 THEN 'form_incomplete' ELSE 'form_started' END::varchar,
event_timestamp::varchar, source, medium, campaign,
0::bigint, 0::bigint, 0::bigint, 0::bigint, 0::bigint, 0::bigint, 0::bigint, 0::bigint
FROM form_attempts WHERE completed = 0
ORDER BY row_type, dimension_1, dimension_2, dimension_3, dimension_4
"""

Expand Down Expand Up @@ -2091,6 +2126,14 @@ def groups(kind: str, dimensions: list[str]) -> list[dict[str, Any]]:
"dataThrough": next((row.get("dimension_4") for row in rows if row.get("row_type") == "summary"), None),
"totals": metrics(next((row for row in rows if row.get("row_type") == "summary"), {})),
"series": series,
"formActivity": [{
"startedAt": datetime.fromisoformat(row["dimension_1"]).replace(tzinfo=timezone.utc)
.isoformat(timespec="milliseconds").replace("+00:00", "Z"),
"source": row.get("dimension_2") or "",
"medium": row.get("dimension_3") or "",
"campaign": row.get("dimension_4") or "",
"status": "Incomplete" if row["row_type"] == "form_incomplete" else "Started",
} for row in rows if row.get("row_type") in ("form_started", "form_incomplete")],
"personas": [{"persona": persona, **persona_totals.get(persona, metrics({}))}
for persona in personas],
"personaSeries": persona_series,
Expand Down
15 changes: 15 additions & 0 deletions infrastructure/analytics-api/tests/test_handler.py
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,21 @@ def test_spacetech_report_attribution_rates_and_quiet_days(self) -> None:
self.assertIn(":content", execute.call_args.args[0])
self.assertNotIn("linkedin", execute.call_args.args[0])

def test_spacetech_form_activity_excludes_identifiers_and_answers(self) -> None:
rows = [{"row_type": kind, "dimension_1": "2026-11-04 12:00:00",
"dimension_2": "linkedin", "dimension_3": "social", "dimension_4": "campaign",
"visitor_id": "private", "session_id": "private", "email": "private"}
for kind in ("form_started", "form_incomplete")]
with patch.object(self.module, "_execute_query", return_value=rows):
response = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], {
"from": "2026-11-04", "to": "2026-11-04",
}), None)
activity = json.loads(response["body"])["formActivity"]
self.assertEqual([row["status"] for row in activity], ["Started", "Incomplete"])
self.assertEqual(activity[0], {"startedAt": "2026-11-04T12:00:00.000Z", "source": "linkedin",
"medium": "social", "campaign": "campaign", "status": "Started"})
self.assertNotIn("private", response["body"])

def test_spacetech_persona_totals_and_weekly_rates(self) -> None:
"""Use independent full-period uniques; fill all personas and quiet UTC weeks."""
rows = [
Expand Down
51 changes: 51 additions & 0 deletions infrastructure/analytics-api/tests/test_spacetech_sql.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ def setUp(self):
source VARCHAR, medium VARCHAR, campaign VARCHAR, content VARCHAR, country VARCHAR,
device VARCHAR, user_engagement_time_msec BIGINT, placement VARCHAR, element_id VARCHAR, faq_id VARCHAR
)""")
self.db.execute("""CREATE TABLE topcoder_web.spacetech_form_events_v1 (
event_timestamp TIMESTAMP, visitor_id VARCHAR, session_id VARCHAR, event_name VARCHAR,
source VARCHAR, medium VARCHAR, campaign VARCHAR, content VARCHAR
)""")
self.params = dict(from_date="2026-11-04", to_date="2026-11-17",
source="*", medium="*", campaign="*", content="*")

Expand Down Expand Up @@ -97,3 +101,50 @@ def test_empty_and_zero_denominators(self):
self.assertEqual(george["submissions"], 1)
self.assertEqual(george["submissionRate"], 0)
self.assertEqual(george["averageEngagementSeconds"], 0)

def form_event(self, time, visitor, event, session="session", source="email", campaign="campaign"):
self.db.execute("INSERT INTO topcoder_web.spacetech_form_events_v1 VALUES (?,?,?,?,?,?,?,?)",
[time, visitor, session, event, source, "social", campaign, "post"])

def test_form_status_lifecycle_repeat_attempts_and_private_fields(self):
self.form_event("2026-11-04 10:00:00", "started", "form_started")
self.form_event("2026-11-04 11:00:00", "incomplete", "form_started")
self.form_event("2026-11-04 11:01:00", "incomplete", "form_abandoned")
# A completion wins even if a pagehide abandonment arrived first.
self.form_event("2026-11-04 12:00:00", "completed", "form_started")
self.form_event("2026-11-04 12:01:00", "completed", "form_abandoned")
self.form_event("2026-11-04 12:02:00", "completed", "form_completed")
# A later successful attempt must not erase a previous incomplete one.
self.form_event("2026-11-04 13:00:00", "repeat", "form_started")
self.form_event("2026-11-04 13:01:00", "repeat", "form_abandoned")
self.form_event("2026-11-04 14:00:00", "repeat", "form_started")
self.form_event("2026-11-04 14:01:00", "repeat", "form_completed")
self.form_event("2026-11-04 15:00:00", "repeat", "form_started")
# Same visitor, different session: must not suppress the unsubmitted attempt.
self.form_event("2026-11-04 15:01:00", "repeat", "form_completed", session="other")
activity = self.report()["formActivity"]
self.assertEqual(len(activity), 4)
self.assertEqual(sorted(row["status"] for row in activity),
["Incomplete", "Incomplete", "Started", "Started"])
self.assertTrue(all(set(row) == {"startedAt", "status", "source", "medium", "campaign"}
for row in activity))
self.assertTrue(all(row["source"] == "email" for row in activity))

def test_form_status_date_and_attribution_filters_do_not_hide_terminal_events(self):
# Status is latest observed, even when completion is outside the start date range
# or its UTM values differ. Starts outside the selected dates remain excluded.
self.form_event("2026-11-17 23:59:00", "complete", "form_started")
self.form_event("2026-11-18 00:01:00", "complete", "form_completed", source="changed")
self.form_event("2026-11-17 23:59:00", "left", "form_started")
self.form_event("2026-11-18 00:01:00", "left", "form_abandoned", source="changed")
self.form_event("2026-11-03 23:59:00", "before", "form_started")
self.form_event("2026-11-18 00:00:00", "after", "form_started")
self.form_event("2026-11-04 00:00:00", "other-source", "form_started", source="linkedin")
self.form_event("2026-11-04 00:00:00", "other-campaign", "form_started", campaign="other")
self.params.update(source="email", medium="social", campaign="campaign", content="post")
self.assertEqual(self.report()["formActivity"], [{
"startedAt": "2026-11-17T23:59:00.000Z", "source": "email", "medium": "social",
"campaign": "campaign", "status": "Incomplete",
}])
self.params["source"] = "missing"
self.assertEqual(self.report()["formActivity"], [])
12 changes: 8 additions & 4 deletions src/apps/analytics/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,14 +100,18 @@ form-section reach and accepted form submissions with source, medium, campaign
dropdown filters. It defaults to 90 days and supports the same 366-day limit.
The daily chart compares visitors with form submissions. Lead details appear below
the aggregates for users with existing Forms reporting permission, with all-column
sorting/filtering and Submitted status. The same table remains in Reports → Forms →
`space_tech_challenge`. New aggregate activity normally appears within three hours;
lead details are available immediately after submission.
sorting/filtering and Submitted, Started and Incomplete statuses. Unfinished attempts
show their start time and attribution with blank personal details. Started means a
start without an observed terminal event; Incomplete means an observed abandonment.
Completed attempts are excluded from anonymous activity to avoid duplicating submitted
leads. The mixed date column is labeled Date Submitted / Started. Reports → Forms →
`space_tech_challenge` and CSV exports remain submission-only. Activity follows
warehouse ingestion; lead details are available immediately after submission.
See [deployment requirements and metric definitions](../../../infrastructure/analytics-api/README.md#spacetech-campaign-pm-6712).

## Privacy

The analytics API returns aggregate counts only. It never returns member IDs,
The analytics API returns aggregate counts and anonymous form activity. It never returns member IDs,
pseudonymous analytics IDs, handles, email addresses, rendered click text, form
values, raw destination queries, or raw click coordinates. API errors are
mapped to safe categories before display, and last-good data remains visible if
Expand Down
11 changes: 11 additions & 0 deletions src/apps/analytics/src/lib/models/analytics.models.ts
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,18 @@ export interface SpaceTechGroup extends SpaceTechMetrics {

export type SpaceTechPersona = 'topcoder' | 'george' | 'anita' | 'tony'

/** Anonymous unfinished attempt; personal answers exist only in submitted Forms rows. */
export interface SpaceTechFormActivity {
startedAt: string
source: string
medium: string
campaign: string
status: 'Started' | 'Incomplete'
}

export interface SpaceTechReport {
/** Absent on older API deployments; an empty array means no unfinished attempts. */
formActivity?: SpaceTechFormActivity[]
filterOptions: { source: string[]; medium: string[]; campaign: string[] }
generatedAt: string
dataThrough?: string
Expand Down
6 changes: 5 additions & 1 deletion src/apps/analytics/src/pages/SpaceTechAnalyticsPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,11 @@ export const SpaceTechAnalyticsPage: FC = () => {
['device', 'Device category'], ['visitors', 'Visitors'],
]}
/>
<SpaceTechLeads key={leadRevision} filters={filters} />
<SpaceTechLeads
key={leadRevision}
filters={filters}
activity={report.data.formActivity}
/>
</>
)}
</section>
Expand Down
Loading
Loading