From 77ed78278700d790de6bce818a57b498d92eb470 Mon Sep 17 00:00:00 2001 From: Jacob Smith Date: Fri, 6 Nov 2026 13:34:32 -0800 Subject: [PATCH 01/14] Add browser Tracks helper and record opening workflow history Adds src/common/tracks.js, the browser counterpart of the PHP Tracker: same vip_workflows_ prefix and the same base properties, which PHP now hands to the admin and editor bundles as `tracks`. Nothing is recorded where the VIP Telemetry library isn't loaded or on local environments, and the Tracks client is imported on the first event so screens that record nothing never load stats.wp.com/w.js. First event: vip_workflows_editor_history_opened, on Show history. Co-Authored-By: Claude Opus 5.5 --- vip-workflows/includes/admin/class-admin.php | 1 + .../editor/class-editor-integration.php | 1 + .../includes/telemetry/class-tracker.php | 21 +++++ vip-workflows/package-lock.json | 50 +++++++++- vip-workflows/package.json | 1 + vip-workflows/src/common/tracks.js | 63 +++++++++++++ .../src/editor/components/WorkflowPanel.js | 6 +- .../tests/phpunit/Unit/TrackerTest.php | 39 ++++++++ vip-workflows/tests/unit-js/tracks.test.js | 94 +++++++++++++++++++ 9 files changed, 274 insertions(+), 2 deletions(-) create mode 100644 vip-workflows/src/common/tracks.js create mode 100644 vip-workflows/tests/unit-js/tracks.test.js diff --git a/vip-workflows/includes/admin/class-admin.php b/vip-workflows/includes/admin/class-admin.php index 1c6f272d..920ffedc 100644 --- a/vip-workflows/includes/admin/class-admin.php +++ b/vip-workflows/includes/admin/class-admin.php @@ -487,6 +487,7 @@ public function enqueue_scripts( string $hook_suffix ): void { 'myWork' => array( 'windowDays' => \VIPWorkflows\API\WorkflowController::MY_WORK_WINDOW_DAYS, ), + 'tracks' => \VIPWorkflows\Telemetry\Tracker::get_client_properties(), ); if ( self::screen_carries_skills( $hook_suffix ) ) { diff --git a/vip-workflows/includes/editor/class-editor-integration.php b/vip-workflows/includes/editor/class-editor-integration.php index 590b7064..aad3a3ec 100644 --- a/vip-workflows/includes/editor/class-editor-integration.php +++ b/vip-workflows/includes/editor/class-editor-integration.php @@ -167,6 +167,7 @@ public function enqueue_editor_assets(): void { 'metadataFields' => $metadata_fields, 'roles' => $roles, 'workflowStatus' => $workflow_status, + 'tracks' => \VIPWorkflows\Telemetry\Tracker::get_client_properties(), ) ) . ';', 'before' diff --git a/vip-workflows/includes/telemetry/class-tracker.php b/vip-workflows/includes/telemetry/class-tracker.php index 34c96244..53ac57c7 100644 --- a/vip-workflows/includes/telemetry/class-tracker.php +++ b/vip-workflows/includes/telemetry/class-tracker.php @@ -85,6 +85,27 @@ public static function is_available(): bool { return null !== self::telemetry(); } + /** + * Base properties for the events the browser records (src/common/tracks.js). + * + * The same properties the library puts on server events: VIP environment and + * organization, the anonymized user, and the plugin version. The browser + * records nothing when this is null, or when the environment is local. + * + * @return array|null Null where the VIP Telemetry library isn't loaded. + */ + public static function get_client_properties(): ?array { + $core_properties = '\\Automattic\\VIP\\Telemetry\\Tracks\\get_tracks_core_properties'; + if ( ! self::is_available() || ! function_exists( $core_properties ) ) { + return null; + } + + return array_merge( + $core_properties(), + array( 'plugin_version' => VIP_WORKFLOWS_VERSION ) + ); + } + /** * Replace the Telemetry instance, for tests. Pass null to use the library. * diff --git a/vip-workflows/package-lock.json b/vip-workflows/package-lock.json index d730ae20..b935049b 100644 --- a/vip-workflows/package-lock.json +++ b/vip-workflows/package-lock.json @@ -8,6 +8,7 @@ "name": "vip-workflows", "version": "1.0.0-beta.1", "dependencies": { + "@automattic/calypso-analytics": "^1.1.5", "@base-ui/react": "^1.2.0", "@dagrejs/dagre": "^3.0.0", "@dnd-kit/core": "^6.3.1", @@ -137,6 +138,38 @@ "dev": true, "license": "ISC" }, + "node_modules/@automattic/calypso-analytics": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/@automattic/calypso-analytics/-/calypso-analytics-1.1.5.tgz", + "integrity": "sha512-rSFa1KbJlLTYh0vCI2k5FTDwI9cXrNS2pHpMwdhPDmy9x6+XqDUJD3vEk8fGVI0Xu1ATaXNfJrMCnQC/vjQvbg==", + "license": "GPL-2.0-or-later", + "dependencies": { + "@automattic/load-script": "^1.0.0", + "cookie": "^0.7.2", + "debug": "^4.4.1", + "hash.js": "^1.1.7", + "tslib": "^2.8.1" + } + }, + "node_modules/@automattic/load-script": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/@automattic/load-script/-/load-script-1.0.0.tgz", + "integrity": "sha512-Hc1mRmTK12OKrONnGhe7Ht1Gpo4B/ls8WQ1IZ1/qBws1bUZ6u7Crnpv3HZkN4UI7irG3OU4l4Pn1TXtoJLcKRw==", + "license": "GPL-2.0-or-later", + "dependencies": { + "@babel/runtime": "^7.4.4", + "debug": "^3.2.6" + } + }, + "node_modules/@automattic/load-script/node_modules/debug": { + "version": "3.2.7", + "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.7.tgz", + "integrity": "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==", + "license": "MIT", + "dependencies": { + "ms": "^2.1.1" + } + }, "node_modules/@babel/code-frame": { "version": "7.29.7", "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.7.tgz", @@ -18040,7 +18073,6 @@ "version": "0.7.2", "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz", "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==", - "dev": true, "license": "MIT", "engines": { "node": ">= 0.6" @@ -21400,6 +21432,16 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/hash.js": { + "version": "1.1.7", + "resolved": "https://registry.npmjs.org/hash.js/-/hash.js-1.1.7.tgz", + "integrity": "sha512-taOaskGt4z4SOANNseOviYDvjEJinIkRgmp7LbKP2YTTmVxWBl87s/uzK9r+44BclBSp2X7K1hqeNfz9JbBeXA==", + "license": "MIT", + "dependencies": { + "inherits": "^2.0.3", + "minimalistic-assert": "^1.0.1" + } + }, "node_modules/hashery": { "version": "1.5.1", "resolved": "https://registry.npmjs.org/hashery/-/hashery-1.5.1.tgz", @@ -25396,6 +25438,12 @@ "webpack": "^5.0.0" } }, + "node_modules/minimalistic-assert": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/minimalistic-assert/-/minimalistic-assert-1.0.1.tgz", + "integrity": "sha512-UtJcAD4yEaGtjPezWuO9wC4nwUnVH/8/Im3yEHQP4b67cXlD/Qr9hdITCU1xDbSEXg2XKNaP8jsReV7vQd00/A==", + "license": "ISC" + }, "node_modules/minimatch": { "version": "11.0.7", "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-11.0.7.tgz", diff --git a/vip-workflows/package.json b/vip-workflows/package.json index b2738d03..af993bb2 100644 --- a/vip-workflows/package.json +++ b/vip-workflows/package.json @@ -36,6 +36,7 @@ "jest-environment-jsdom": "^30.5.2" }, "dependencies": { + "@automattic/calypso-analytics": "^1.1.5", "@base-ui/react": "^1.2.0", "@dagrejs/dagre": "^3.0.0", "@dnd-kit/core": "^6.3.1", diff --git a/vip-workflows/src/common/tracks.js b/vip-workflows/src/common/tracks.js new file mode 100644 index 00000000..f87a1d57 --- /dev/null +++ b/vip-workflows/src/common/tracks.js @@ -0,0 +1,63 @@ +/** + * Records product-usage events in Tracks from the browser. + * + * The browser counterpart of the PHP Tracker (includes/telemetry/class-tracker.php): + * same `vip_workflows_` prefix, same base properties. PHP hands those properties + * to the page as `tracks` on `vipWorkflowsAdmin` or `vipWorkflowsEditor`, and + * only where the VIP Telemetry library is loaded, so off VIP there is nothing + * to send. Local environments send nothing either. + * + * The Tracks client is imported on the first event rather than with the bundle: + * importing it loads stats.wp.com/w.js, which no screen should do when nothing + * will be recorded. + */ + +const EVENT_PREFIX = 'vip_workflows_'; + +let recorder = null; + +/** + * The base properties PHP localized for this screen. + * + * @return {Object|null} Null when this screen should record nothing. + */ +export function getTracksBaseProperties() { + return ( + window.vipWorkflowsAdmin?.tracks ?? + window.vipWorkflowsEditor?.tracks ?? + null + ); +} + +/** + * Record a Tracks event. + * + * Properties must be flat and snake_case, and must never carry content a + * customer typed: send a length or a count instead. + * + * @param {string} event Event name, without the `vip_workflows_` prefix. + * @param {Object} properties Event properties, merged over the base properties. + * @return {Promise} Settles once the event is queued, or skipped. + */ +export function recordTracksEvent( event, properties = {} ) { + const base = getTracksBaseProperties(); + + if ( ! base || base.vip_env === 'local' ) { + return Promise.resolve(); + } + + recorder ??= import( + /* webpackChunkName: "tracks" */ '@automattic/calypso-analytics' + ).then( ( analytics ) => analytics.recordTracksEvent ); + + return recorder + .then( ( record ) => + record( `${ EVENT_PREFIX }${ event }`, { + ...base, + ...properties, + } ) + ) + .catch( () => { + // Telemetry must never break the screen it is measuring. + } ); +} diff --git a/vip-workflows/src/editor/components/WorkflowPanel.js b/vip-workflows/src/editor/components/WorkflowPanel.js index ac7f5fb7..2ec61025 100644 --- a/vip-workflows/src/editor/components/WorkflowPanel.js +++ b/vip-workflows/src/editor/components/WorkflowPanel.js @@ -58,6 +58,7 @@ import { speak } from '@wordpress/a11y'; import { __, sprintf } from '@wordpress/i18n'; import { STORE_NAME } from '../store'; import { AuthorCell } from '../../common/DataViewCells'; +import { recordTracksEvent } from '../../common/tracks'; import { useRequiredMetadataGate } from '../required-metadata'; import { TransitionRail } from './TransitionRail'; import { IdeationPanel } from './IdeationPanel'; @@ -586,7 +587,10 @@ export function WorkflowPanel() { > diff --git a/vip-workflows/tests/phpunit/Unit/TrackerTest.php b/vip-workflows/tests/phpunit/Unit/TrackerTest.php index c62a61a6..bd56ccfa 100644 --- a/vip-workflows/tests/phpunit/Unit/TrackerTest.php +++ b/vip-workflows/tests/phpunit/Unit/TrackerTest.php @@ -220,4 +220,43 @@ public function test_it_is_available_when_there_is_a_telemetry_instance(): void $this->assertTrue( Tracker::is_available() ); } + + public function test_without_the_library_the_browser_gets_no_properties(): void + { + $this->assertNull( Tracker::get_client_properties() ); + } + + public function test_without_the_tracks_helpers_the_browser_gets_no_properties(): void + { + $this->assertFalse( function_exists( '\\Automattic\\VIP\\Telemetry\\Tracks\\get_tracks_core_properties' ), 'This test assumes the mu-plugin library is not loaded.' ); + Tracker::set_telemetry( $this->telemetry() ); + + $this->assertNull( Tracker::get_client_properties() ); + } + + /** + * In its own process, because the Tracks helper it declares cannot be undone. + * + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function test_the_browser_gets_the_library_base_properties_and_the_plugin_version(): void + { + if ( ! defined( 'VIP_WORKFLOWS_VERSION' ) ) { + define( 'VIP_WORKFLOWS_VERSION', '0.0.1' ); + } + eval( 'namespace Automattic\\VIP\\Telemetry\\Tracks; function get_tracks_core_properties() { return array( "vip_env" => "production", "vip_org" => 42, "_ui" => "abc", "_ut" => "vip:user_email", "plugin_version" => "stale" ); }' ); + Tracker::set_telemetry( $this->telemetry() ); + + $this->assertSame( + array( + 'vip_env' => 'production', + 'vip_org' => 42, + '_ui' => 'abc', + '_ut' => 'vip:user_email', + 'plugin_version' => VIP_WORKFLOWS_VERSION, + ), + Tracker::get_client_properties() + ); + } } diff --git a/vip-workflows/tests/unit-js/tracks.test.js b/vip-workflows/tests/unit-js/tracks.test.js new file mode 100644 index 00000000..ad92e452 --- /dev/null +++ b/vip-workflows/tests/unit-js/tracks.test.js @@ -0,0 +1,94 @@ +/** + * Unit tests for the browser Tracks helper. + * + * The helper must stay silent wherever PHP localized no base properties (off + * VIP) and on local environments, and otherwise send the prefixed event with + * the base properties under the event's own. + */ + +import { recordTracksEvent as recordWithCalypso } from '@automattic/calypso-analytics'; + +import { recordTracksEvent } from '../../src/common/tracks'; + +jest.mock( '@automattic/calypso-analytics', () => ( { + recordTracksEvent: jest.fn(), +} ) ); + +const base = { + plugin_version: '1.0.0', + vip_env: 'production', + vip_org: 1, + is_vip_user: false, + hosting_provider: 'wpvip', + is_multisite: false, + wp_version: '6.9', + _ui: 'abc', + _ut: 'vip:user_email', +}; + +describe( 'recordTracksEvent', () => { + beforeEach( () => { + delete window.vipWorkflowsAdmin; + delete window.vipWorkflowsEditor; + jest.clearAllMocks(); + } ); + + it( 'records nothing when no base properties were localized', async () => { + window.vipWorkflowsAdmin = { tracks: null }; + + await recordTracksEvent( 'editor_history_opened' ); + + expect( recordWithCalypso ).not.toHaveBeenCalled(); + } ); + + it( 'records nothing when the screen has no localized data at all', async () => { + await recordTracksEvent( 'editor_history_opened' ); + + expect( recordWithCalypso ).not.toHaveBeenCalled(); + } ); + + it( 'records nothing on a local environment', async () => { + window.vipWorkflowsEditor = { tracks: { ...base, vip_env: 'local' } }; + + await recordTracksEvent( 'editor_history_opened' ); + + expect( recordWithCalypso ).not.toHaveBeenCalled(); + } ); + + it( 'records the prefixed event with the editor base properties', async () => { + window.vipWorkflowsEditor = { tracks: base }; + + await recordTracksEvent( 'editor_history_opened' ); + + expect( recordWithCalypso ).toHaveBeenCalledTimes( 1 ); + expect( recordWithCalypso ).toHaveBeenCalledWith( + 'vip_workflows_editor_history_opened', + base + ); + } ); + + it( 'records with the admin base properties, event properties last', async () => { + window.vipWorkflowsAdmin = { tracks: base }; + + await recordTracksEvent( 'sequence_create_started', { + source: 'header', + plugin_version: 'overridden', + } ); + + expect( recordWithCalypso ).toHaveBeenCalledWith( + 'vip_workflows_sequence_create_started', + { ...base, source: 'header', plugin_version: 'overridden' } + ); + } ); + + it( 'swallows a failure in the Tracks client', async () => { + window.vipWorkflowsAdmin = { tracks: base }; + recordWithCalypso.mockImplementationOnce( () => { + throw new Error( 'boom' ); + } ); + + await expect( + recordTracksEvent( 'editor_history_opened' ) + ).resolves.toBeUndefined(); + } ); +} ); From b4d6898fe5987605b95b4a54f3e35458011ed215 Mon Sep 17 00:00:00 2001 From: Jacob Smith Date: Fri, 6 Nov 2026 13:35:09 -0800 Subject: [PATCH 02/14] Record starting and importing sequences in Tracks Co-Authored-By: Claude Opus 5.5 --- .../src/admin/components/SequencesList.js | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/vip-workflows/src/admin/components/SequencesList.js b/vip-workflows/src/admin/components/SequencesList.js index ae1216a7..31b96629 100644 --- a/vip-workflows/src/admin/components/SequencesList.js +++ b/vip-workflows/src/admin/components/SequencesList.js @@ -26,6 +26,7 @@ import { __, _n, sprintf } from '@wordpress/i18n'; import { plus } from '@wordpress/icons'; import { ModalActions } from '../../common/ModalActions'; +import { recordTracksEvent } from '../../common/tracks'; import AdminPage from './AdminPage'; import { CardGridView } from './CardGridView'; import { HowToModal } from './HowToModal'; @@ -321,6 +322,11 @@ export function SequencesList() { variant="primary" icon={ plus } href="#/new?type=workflow" + onClick={ () => + recordTracksEvent( 'sequence_create_started', { + source: 'header', + } ) + } > { __( 'New sequence', 'vip-workflows' ) } @@ -376,6 +382,14 @@ export function SequencesList() {