Agents Manager: add host-injectable tracking handler#109909
Draft
budzanowski wants to merge 1 commit intotrunkfrom
Draft
Agents Manager: add host-injectable tracking handler#109909budzanowski wants to merge 1 commit intotrunkfrom
budzanowski wants to merge 1 commit intotrunkfrom
Conversation
Adds a `tracking` module that wraps `@automattic/calypso-analytics`'s
`recordTracksEvent` so hosts can inject a tracking handler without
changing the default Calypso tracks behavior.
## tracking module
Two entry points for call sites:
- `recordTracksEvent( name, props )` — drop-in replacement for the
Calypso analytics import. Prepends `calypso_` when firing through
the default path, and also delivers to any registered handler with
the unprefixed name.
- `trackEvent( name, props )` — handler-only. No default path, so new
events are invisible to hosts that haven't opted in.
Two host-controlled switches:
- `setTrackingHandler( fn )` — register/clear the handler.
- `setDefaultTracksEnabled( enabled )` — toggle the default Calypso
tracks path. When disabled, only the handler receives events.
Both are wired into the existing `window.__agentsManagerActions`
pre-set pattern via `trackingHandler` and `disableDefaultTracks`
properties, read by `useSetupCustomActions` on first mount.
## Call site migration
The 4 existing `calypso_agents_manager_*` tracks events flow through
the new `recordTracksEvent` wrapper. Their event names drop the
`calypso_` prefix at the call site (the wrapper prepends it):
- components/custom-a-link — `agents_manager_link_click`
- components/sources-display — `agents_manager_link_click`
- hooks/use-feedback-action — `agents_manager_response_feedback_action`
- hooks/use-feedback-action — `agents_manager_response_feedback_submitted`
## New chat-shell events (handler-only, via trackEvent)
- `panel_view` — sidebar open (use-agent-layout-manager)
+ pop-out expand (agent-dock)
- `panel_close` — sidebar close (use-agent-layout-manager)
+ pop-out close (agent-dock)
- `panel_mode_change` — dock / undock dropdown (agent-dock)
- `button_click` — new_chat, view_history, select_conversation
All carry `chat_state` and `section_name`; `panel_mode_change` adds
`previous_state`/`new_state`; `button_click` adds `button_label`.
## Default behavior
Unchanged for hosts that don't register a handler. The 4 legacy
events still fire as `calypso_agents_manager_*` via the Calypso
tracks pipeline. The 6 new events do not fire at all unless a host
opts in — they're pure handler-only events.
Companion PR (CIAB side): `add/ciab-assistant-tracking-handler`
in ciab-admin, which pre-sets the \`trackingHandler\` to route chat
events into CIAB's tracks pipeline as \`assistant_*\`.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
Jetpack Cloud Live (direct link)
Automattic for Agencies Live (direct link)
Dashboard Live (dotcom) (direct link)
|
Contributor
|
This PR modifies the release build for the following Calypso Apps: For info about this notification, see here: PCYsg-OT6-p2
To test WordPress.com changes, run |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
trackingmodule to@automattic/agents-managerthat wraps@automattic/calypso-analytics'srecordTracksEventso hosts can inject a tracking handler without changing the default Calypso tracks behavior.Also adds six new chat-shell events (panel_view, panel_close, panel_mode_change, button_click × 3) that fire exclusively through the host handler — invisible to hosts that don't opt in.
This is the first of two companion PRs. The CIAB side is in
add/ciab-assistant-tracking-handleron ciab-admin, which pre-sets thetrackingHandlerto route chat events into CIAB's tracks pipeline asassistant_*withpage_surface_areacontext. That PR is blocked on this one merging and deploying.Why
Today agents-manager fires four
calypso_agents_manager_*tracks events (feedback ×2, link click ×2) via direct calls to@automattic/calypso-analytics. These work fine in Calypso but there's no way for hosts like CIAB to observe them in their own telemetry pipelines — and there's no chat-shell telemetry at all (no panel opens, closes, dock/undock, button clicks).This PR introduces a single gateway for all agents-manager tracks events with a host extension point, without changing the default behavior. Hosts that don't care see zero new events. Hosts that opt in receive every event (existing and new) through a single handler they control.
Design
tracking.tsmoduleTwo entry points for call sites:
recordTracksEvent( name, props )— drop-in replacement for the Calypso analytics import. Prependscalypso_when firing through the default path, and also delivers the unprefixed name to any registered handler.trackEvent( name, props )— handler-only. No default Calypso path. Use for new events that have never existed in the Calypso namespace.Two host-controlled switches:
setTrackingHandler( fn )— register or clear the handler.setDefaultTracksEnabled( enabled )— toggle the default Calypso path. When disabled, only the handler receives events.Host extension surface
Extends the existing
window.__agentsManagerActionspre-set pattern (same asisCompactMode,isChatEnabled,desktopMediaQuery):trackingHandlerfunctionundefineddisableDefaultTracksbooleanfalseuseSetupCustomActionsreads both on first mount and callssetTrackingHandler/setDefaultTracksEnabledaccordingly.Call site changes
4 existing
calypso_agents_manager_*events — droppedcalypso_prefix + swapped importcomponents/custom-a-link/index.tsxcalypso_agents_manager_link_clickagents_manager_link_clickcomponents/sources-display/index.tsxcalypso_agents_manager_link_clickagents_manager_link_clickhooks/use-feedback-action.tscalypso_agents_manager_response_feedback_actionagents_manager_response_feedback_actionhooks/use-feedback-action.tscalypso_agents_manager_response_feedback_submittedagents_manager_response_feedback_submittedWhat fires at the transport layer is unchanged: the wrapper prepends
calypso_before calling the realrecordTracksEvent, so the tracks pipeline still seescalypso_agents_manager_link_clicket al. Existing tests that mock@automattic/calypso-analyticspass unmodified.6 new chat-shell events — handler-only via
trackEventpanel_viewhooks/use-agent-layout-manager/index.tsxpanel_viewcomponents/agent-dock/index.tsxpanel_closehooks/use-agent-layout-manager/index.tsxpanel_closecomponents/agent-dock/index.tsxpanel_mode_changecomponents/agent-dock/index.tsxbutton_click(new_chat)components/agent-dock/index.tsxbutton_click(view_history)components/chat-header/index.tsxbutton_click(select_conversation)components/agent-dock/index.tsxhandleSelectConversationAll carry
chat_stateandsection_name.panel_mode_changeaddsprevious_state/new_state.button_clickaddsbutton_label(andconversation_typefor select_conversation).Default behavior
Unchanged for hosts that don't register a handler:
calypso_agents_manager_*via the Calypso tracks pipeline (identical bytes on the wire)Test plan
src/__tests__/tracking.test.tscover all 4 quadrants (default on/off × handler set/unset) plus the switchesuse-setup-custom-actions.test.tsto cover thetrackingHandleranddisableDefaultTrackspre-set wiringyarn lint:js packages/agents-manager)widgets.wp.com/agents-manager/on a sandbox, visit a CIAB site, verify:calypso_agents_manager_link_clicketc.) still fire when no handler is registeredwindow.__agentsManagerActions = { trackingHandler: (event, props) => console.log('EVENT', event, props) }in the browser, reload, and verify each panel lifecycle / button click produces a console entry with the unprefixed namedisableDefaultTracks: truein the same pre-set, verify nocalypso_agents_manager_*events fire in the Network tab (only the handler receives them)Related
add/ciab-assistant-tracking-handler— pre-sets the handler to route chat events into CIAB'sassistant_*namespace withpage_surface_areacontext🤖 Generated with Claude Code